OmniCloud 同步引擎源码解析:node-cron 定时任务与 SQLite 元数据镜像如何保持文件清单实时
OmniCloud 同步引擎源码解析:node-cron 定时任务与 SQLite 元数据镜像如何保持文件清单实时
OmniCloud 是一个全栈网盘聚合平台,能把 Google Drive、OneDrive、MEGA、Dropbox、S3 等多个云存储账号汇入同一个工作区。它的"文件清单实时"能力由后端同步引擎支撑:node-cron 定时任务周期性拉取远端目录结构,SQLite(better-sqlite3)元数据镜像在本地存下完整文件索引,两者配合让前端列表查询永远命中本地数据库,无需每次穿透远端 API。本文带你读懂这套同步机制的核心源码。
同步引擎全景:三个核心模块
同步引擎分布在以下文件中,职责清晰分离:
| 模块 | 路径 | 职责 |
|---|---|---|
| 定时调度器 | 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),写入同步镜像时不阻塞前端读查询。
一次同步的完整流程:快照、重试、整体替换
拉取快照: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,镜像保留上一轮结果,等下一轮定时任务再试。
定时之外的三条实时触发路径
除了 cron,还有三处会让镜像"立刻"刷新:
- 手动同步:Storage 页面的 "Sync now" 按钮调用 POST /api/sync/run,直接执行
runDeltaSync(),返回本次扫描的账号数与变更文件数(对应 QuotaView.vue); - 账号变更事件:OAuth 授权完成、上传结束、删除文件后都会调用 syncAccount() 单独刷新该账号(如 uploadService.js、fileRoutes.js),保证"操作即所见";
- 前端静默轮询:MyDriveView.vue 每 20 秒调用
/api/health比对sync.lastRunAt(见 getLastSyncReport()),发现后端刚完成一轮同步就重新拉取当前目录。配合通用轮询工具 useAutoRefresh.js,页面无需手动刷新即可看到新文件。
总结:小而稳的实时性设计
OmniCloud 的同步引擎没有引入消息队列或变更订阅,而是用"定时全量快照 + 本地镜像"的组合把复杂问题做简单了:
node-cron保证周期兜底,activeSyncPromise保证不重叠;withRetry指数退避吸收网络抖动,认证失败则果断清理、标记invalid_token;- SQLite 事务"先删后插"让镜像永远自洽,WAL + 多索引让前端查询始终走本地;
- 手动同步、账号事件、前端轮询三条路径补上了定时之间的空窗。
如果你也想给多网盘聚合场景做类似设计,这套"快照-镜像-校验"的思路可以直接参考 syncService.js 的完整实现。


