OmniCloud 同步引擎源码解析:node-cron 定时任务与 SQLite 元数据镜像如何保持文件清单实时

原创2026-11-04 14:54:291,722 阅读

OmniCloud 同步引擎源码解析:node-cron 定时任务与 SQLite 元数据镜像如何保持文件清单实时

OmniCloud 是一个全栈网盘聚合平台,能把 Google Drive、OneDrive、MEGA、Dropbox、S3 等多个云存储账号汇入同一个工作区。它的"文件清单实时"能力由后端同步引擎支撑:node-cron 定时任务周期性拉取远端目录结构,SQLite(better-sqlite3)元数据镜像在本地存下完整文件索引,两者配合让前端列表查询永远命中本地数据库,无需每次穿透远端 API。本文带你读懂这套同步机制的核心源码。

OmniCloud 多云存储聚合架构图:多个网盘账号汇入统一工作区

同步引擎全景:三个核心模块

同步引擎分布在以下文件中,职责清晰分离:

模块 路径 职责
定时调度器 syncService.js cron 调度、增量同步、失败处理
元数据镜像 database.js SQLite 建表、索引、WAL 模式
镜像读写 fileService.js 文件清单增删改查、按账号整体替换
云厂商适配 adapterRegistry.js 按 provider 创建对应 Adapter

一次同步的完整链路是:

cron 定时器 → runDeltaSync(userId)
  → getActiveAccounts() 取出所有 active 账号
  → 每个账号:fetchStructure() + getStorageSummary()
  → replaceFilesForAccount() 事务整体替换镜像
  → updateAccountStorage() 刷新配额

node-cron 定时任务:调度器的四个关键设计

1. 用 cron 表达式控制同步频率

调度入口在 scheduleSync(),核心只有一行:

cron.schedule(`*/${interval} * * * *`, () => { ... });

interval 来自环境变量 SYNC_INTERVAL_MINUTES,默认 5 分钟(见 env.js)。*/5 * * * * 的含义就是"每 5 分钟触发一次"。

2. 按运行模式跳过定时任务

回调开头有一个判断:env.appMode !== 'local' 时直接 return。也就是说,只有本地模式(APP_MODE 未设为 hosted)才会跑定时同步——单用户本地部署依赖 cron 自动刷新,而托管模式改由用户按需触发。

3. 用"在途 Promise"防止同步重叠

runDeltaSync() 维护了一个模块级变量 activeSyncPromise:

  • 若上一轮同步还没结束,直接返回同一个 Promise,不发起新一轮;
  • 同步结束后在 finally 中清空引用。

这保证了一个网盘账号不会因为定时任务与手动同步并发执行,而出现"后写的旧数据覆盖新数据"的问题。

4. 服务启动时立即补一轮

server.js 在监听端口前就调用 scheduleSync(),并在 local 模式下立刻执行一次 runDeltaSync(LOCAL_USER_ID)——服务冷启动后不用等满 5 分钟,文件清单立即就位。

SQLite 元数据镜像:为什么前端查询这么快

前端列表、搜索、最近文件、收藏等页面读取的不是网盘 API,而是本地 file_metadata 表。建表语句在 database.js,关键字段:

  • virtual_path + file_name:统一虚拟目录树,把各家网盘"拍平"到一棵目录里;
  • cloud_account_id + remote_file_id:回溯到具体账号和远端文件;
  • size、mime_type、remote_modified_time:支撑排序与展示。

配合 database.js 中的索引设计,查询被控制在毫秒级:

  • 唯一索引 idx_file_account_remote_id(cloud_account_id, remote_file_id):定位远端文件;
  • 索引 idx_file_virtual_path(user_id, virtual_path):支撑目录浏览;
  • 索引 idx_file_remote_id:支撑按远端 ID 反查。

此外还开启了 PRAGMA journal_mode = WAL(database.js),写入同步镜像时不阻塞前端读查询。

My Drive 文件列表界面:所有网盘文件统一展示在一张列表中

一次同步的完整流程:快照、重试、整体替换

拉取快照:fetchAccountSnapshot

syncService.js 中,每个账号通过 adapterRegistry.js 创建对应 Adapter(如 GoogleDriveAdapter.js 分页拉取全部文件),然后并行拿到两样东西:

  • remoteFiles:完整目录结构;
  • storage:总容量 / 已用容量。

整个拉取过程包在 providerErrors.js 的 withRetry 里:最多重试 3 次,采用指数退避 + 随机抖动(500ms → 1s → 2s,上限 8s)。但有一个例外——认证错误(401/403 或 token 过期类错误)不重试,直接抛出,避免拿无效 token 白白打满重试。

镜像写入:事务内"先删后插"

拿到快照后调用 replaceFilesForAccount():

const replace = db.transaction(() => {
  db.prepare('DELETE FROM file_metadata WHERE user_id = ? AND cloud_account_id = ?')
    .run(userId, cloudAccountId);
  // 再批量 INSERT 本账号最新快照
});

在一个数据库事务里删除该账号全部旧记录、再写入新快照。这种"整体替换"比逐条 diff 简单得多,且事务保证任何时刻镜像都是自洽的——不会出现"一半旧数据一半新数据"的中间态。写入完成后,updateAccountStorage() 把最新配额同步到 cloud_accounts 表,前端的存储用量进度条随之更新。

失败处理:区分"认证失效"和"网络抖动"

handleSyncFailure() 是保证"清单不失真"的关键:

  • 认证错误(isAuthError() 通过正则与状态码识别):立即清空该账号镜像并置为 invalid_token。宁可让清单"消失",也不留一份看起来还在、实际已失效的假数据;
  • 临时错误(429/5xx、超时、断连等):只记日志,账号保持 active,镜像保留上一轮结果,等下一轮定时任务再试。

Storage 总览页面:各网盘账号配额与 Sync now 手动同步按钮

定时之外的三条实时触发路径

除了 cron,还有三处会让镜像"立刻"刷新:

  1. 手动同步:Storage 页面的 "Sync now" 按钮调用 POST /api/sync/run,直接执行 runDeltaSync(),返回本次扫描的账号数与变更文件数(对应 QuotaView.vue);
  2. 账号变更事件:OAuth 授权完成、上传结束、删除文件后都会调用 syncAccount() 单独刷新该账号(如 uploadService.js、fileRoutes.js),保证"操作即所见";
  3. 前端静默轮询:MyDriveView.vue 每 20 秒调用 /api/health 比对 sync.lastRunAt(见 getLastSyncReport()),发现后端刚完成一轮同步就重新拉取当前目录。配合通用轮询工具 useAutoRefresh.js,页面无需手动刷新即可看到新文件。

总结:小而稳的实时性设计

OmniCloud 的同步引擎没有引入消息队列或变更订阅,而是用"定时全量快照 + 本地镜像"的组合把复杂问题做简单了:

  • node-cron 保证周期兜底,activeSyncPromise 保证不重叠;
  • withRetry 指数退避吸收网络抖动,认证失败则果断清理、标记 invalid_token;
  • SQLite 事务"先删后插"让镜像永远自洽,WAL + 多索引让前端查询始终走本地;
  • 手动同步、账号事件、前端轮询三条路径补上了定时之间的空窗。

如果你也想给多网盘聚合场景做类似设计,这套"快照-镜像-校验"的思路可以直接参考 syncService.js 的完整实现。

登录后查看全文
OmniCloud