Obsidian Self-hosted LiveSync Fast Setup 快速设置指南:流式拉取加速二设备初始化与数据库恢复
Obsidian Self-hosted LiveSync Fast Setup 快速设置指南:流式拉取加速二设备初始化与数据库恢复
Fast Setup(快速设置,源码中也称为 Simple Fetch)是 Obsidian Self-hosted LiveSync 提供的一条精简数据拉取与初始化流程,专门用于简化第二台设备的初始化和本地数据库恢复。与传统的多步骤设置向导不同,它只向用户提出少数几个高层同步决策,然后在一个连续过程中自动完成远端数据下载与本地存储扫描。读完本文,你将掌握 Fast Setup 的触发方式、三种数据处理策略的适用场景、冲突与删除规则的源码映射,以及流程中断后的状态保留与恢复方法。
Fast Setup 是什么
在 Obsidian Self-hosted LiveSync 中,首次配置或从空库恢复通常依赖详细的多步骤设置向导(Setup Wizard),用户需要逐项确认数据库选项。Fast Setup 是对这一流程的简化替代:插件只询问"如何处理取回的数据"等高层决策,其余下载与落盘工作全部自动化,避免在多台设备间反复进行繁琐的逐步配置。
从源码结构看,Fast Setup 的实现集中在 src/serviceFeatures/redFlag.simpleFetch.ts,它作为"Fetch All(全量拉取)"调度流程的可选分支被挂载在 src/serviceFeatures/redFlag.ts 中。该文件顶部定义了流程中所有对话框选项的常量(即用户界面上可见的文案),例如:
export const SIMPLE_FETCH_STAGE1_REMOTE_WINS = "Overwrite all with remote files";
export const SIMPLE_FETCH_STAGE1_NEWER_WINS = "Compare time and take newer";
export const SIMPLE_FETCH_STAGE1_DETAILED = "Use the detailed flow";
export const SIMPLE_FETCH_STAGE1_CANCEL = "Cancel";
export const SIMPLE_FETCH_STAGE2_REMOTE_DELETE_NONE = "Keep local files even if not on remote";
export const SIMPLE_FETCH_STAGE2_REMOTE_DELETE_ALL = "Delete local files if not on remote";
export const SIMPLE_FETCH_STAGE2_NEWER_CLEANUP = "Delete local files if deleted on remote";
export const SIMPLE_FETCH_STAGE2_NEWER_SYNC_ALL = "Keep local files even if deleted on remote";
export const STAGE2_ABORT = "Cancel all and reboot";
这些常量直接对应本文后续步骤中的界面选项,是理解整个流程的关键索引。
触发方式与执行流程
Fast Setup 会在以下两类场景被调度:
- 导入 Setup URI:在第二台设备上导入由首台设备生成的 Setup URI(对应 src/serviceFeatures/setupObsidian/setupUri.ts 中的
copySetupURI/copySetupURIFull命令生成的一键配置串),插件会预约定时远端数据拉取; - Fetch All 操作:在 Vault 根目录放置
redflag3.md(可读名flag_fetch.md)旗标文件,或手动执行"Reset Synchronisation on This Device"类操作。
检测到上述调度后,插件在下一次启动时进入"定时拉取"(scheduled fetch)模式,弹出简化的 "Data retrieval scheduled"(数据拉取已安排) 对话框。在 src/serviceFeatures/redFlag.ts 中,createFetchAllFlagHandler(优先级 10)负责监听旗标:
const isFlagActive = async () =>
(await isFlagFileExist(host, FlagFilesOriginal.FETCH_ALL)) ||
(await isFlagFileExist(host, FlagFilesHumanReadable.FETCH_ALL));
即同时兼容旧名 redflag3.md 与新可读名 flag_fetch.md 两种旗标文件。一旦激活,处理器会先让用户选择要使用的远端配置(存在多个远端配置时),再调用 askAndPerformFastSetupOnScheduledFetchAll 进入 Fast Setup 主流程;若用户选择进入详细流程,则回退到传统 FetchEverything 对话框。
三项后端优化:为什么 Fast Setup 更快、更安全、更干净
Fast Setup 并非简单地把传统流程"压缩"成两步,而是借助三类后端优化提升拉取体验:
1. 基于流的复制(Stream-based Replication)提升速度
Fast Setup 通过流式接收(stream reception)一次性拉取全部远端元数据,而不是传统的逐 chunk 检索。实现上对应 $fetchLocalDBFast(false) 这一快速数据库下载入口(rebuilder 模块),相比逐块拉取在速度上有数量级的优势。这一点在 src/serviceFeatures/redFlag.simpleFetch.ts 的 performFastSetup 中直接体现:
// 1. Perform fast DB fetch (download remote DB content to local DB)
await host.serviceModules.rebuilder.$fetchLocalDBFast(false);
2. 延迟文件反射,避免误报"数据损坏"
在下载阶段,插件会挂起文件反射(file reflection),即暂停数据库变更向 Vault 文件的回写。这样在 chunk 下载过程中,不会因为数据库与存储文件暂时不一致而触发临时的"corrupted data synchronisation(数据同步损坏)"或"size mismatch(大小不匹配)"警告。
这一机制由 processVaultInitialisation(host, log, performFastSetup, "keep-on-failure") 实现(见 src/serviceFeatures/redFlag.ts)。初始化期间会关闭批量保存(batchSave: false)、挂起全部同步(suspendAllSync / suspendExtraSync)并置 suspendFileWatching: true;而 "keep-on-failure" 策略还额外保持 suspendParseReplicationResult: true,确保一个未完整重建的数据库绝不会被应用到 Vault 或与新的本地变更合并。
3. 基于时间的比较在多数情况下足够可靠
由于进入 Fast Setup 时 Vault 正处于全新同步或恢复状态,文件不存在多设备冲突的历史包袱,因此基于修改时间戳"新者胜"(newer-wins)的比较即可可靠地调和文件,无需复杂的手动冲突解决。源码中这一策略对应 FullScanModes.NEWER_WINS(见 buildSimpleFetchResult 对第一阶段选项的映射)。
分步操作指南
Step 1:选择数据处理方式
对话框 "Data retrieval scheduled" 会要求你选择取回的远端数据如何与现有本地文件交互:
| 选项 | 行为 | 推荐场景 | 注意事项 |
|---|---|---|---|
| Compare time and take newer(比较时间,新者胜) | 比较文件修改时间,接受较新版本 | 已在多台设备上使用 Self-hosted LiveSync,希望合并各设备改动 | 基于时间戳合并,不产生复杂冲突 |
| Overwrite all with remote files(远端覆盖一切) | 将远端数据视为唯一事实来源 | 全新设备、空 Vault 或干净 Vault 的初始化 | 会用远端文件覆盖本地文件,操作前请务必备份本地 Vault |
| Use the detailed flow(使用详细流程,旧版) | 回退到传统多步骤设置向导 | 希望对数据库设置逐项完全掌控 | 适合需要精细控制、想在应用前审阅变更的用户 |
源码映射(src/serviceFeatures/redFlag.simpleFetch.ts 的 buildSimpleFetchResult):
SIMPLE_FETCH_STAGE1_DETAILED→{ mode: "detailed", options: {} },交由传统 FetchEverything 流程处理;SIMPLE_FETCH_STAGE1_REMOTE_WINS→mode: "remote-only",对应FullScanModes.DB_APPLY;SIMPLE_FETCH_STAGE1_NEWER_WINS→mode: "newer-wins",对应FullScanModes.NEWER_WINS。
Step 2:配置冲突与删除规则
根据 Step 1 的选择,系统会进一步询问如何处理不匹配文件:
若选择 "Compare time and take newer"(新者胜)
| 选项 | 行为 |
|---|---|
| Delete local files if they were deleted on remote | 删除远端已删除的本地文件,保持本地 Vault 整洁 |
| Recreate remote files even if they were deleted on remote | 保留本地文件并重新上传回远端数据库,即使这些文件在其他设备上已被删除 |
源码中,前者对应 ExtraOnLocal.DELETE_DB_DELETED(清理策略),后者对应 ExtraOnLocal.APPEND_STORAGE_ONLY(全部保留并回传)。
若选择 "Overwrite all with remote files"(远端覆盖)
| 选项 | 行为 |
|---|---|
| Delete local files if not on remote | 删除仅存在于本地的文件,使本地 Vault 与远端数据库完全一致 |
| Keep local files even if not on remote | 保留所有本地独有文件,但可能产生重复内容,同步后需手动清理 |
源码中,前者对应 ExtraOnRemote.DELETE_LOCAL_MISSING(严格对齐远端),后者则不设置该标志(保留本地独有文件)。
两阶段选择会被记录在 simple-fetch-mode 小配置键中(rememberSimpleFetchMode / getRememberedSimpleFetchMode),在定时拉取尚未完成期间重启 Obsidian 时,插件会记住你的选择而不会重复提问;流程成功结束后则通过 clearRememberedSimpleFetchMode 清除。
Step 3:自动化同步
确认选择后,插件依次执行(对应 performFastSetup 的实现):
- 快速下载远端数据库:调用
fetchLocalDBFast将远端数据库内容下载到本地; - 前台全量扫描:调用
synchroniseAllFilesBetweenDBandStorage在前台全量扫描,将数据库变更立即反映到本地 Vault 文件。该调用使用扩展选项:normaliseFullScanOptions({ ...result.options, showingNotice: true, omitEvents: true, ignoreSuspending: true }),即显示进度通知、省略事件触发、忽略挂起限制; - 收尾并恢复正常运行:调用
finishRebuild结束重建状态、清除 fetch 旗标、清除记住的选择,然后恢复文件监听与数据库反射。
如果全量扫描阶段有文件同步失败,插件会弹出 "Some files failed to synchronise" 对话框,提供 "Reboot to re-run the process"(重启重试) 与 "Finalise the process and resume normal operation"(完成流程并恢复正常运行) 两个选项:前者保留旗标、重启后重跑;后者即使存在个别失败也完成收尾。相关行为均有 src/serviceFeatures/redFlag.unit.spec.ts 中的单元测试覆盖(例如 releases both reflection suspensions after Fast Setup succeeds、keeps Vault reflection suspended and preserves recovery state when Fast Fetch fails 等用例)。
如果 Fast Setup 中断:状态保留与恢复
Fast Setup 在设计上考虑了中途失败的可恢复性:
- 断点续传:每保存一个文档,插件都会记录最后一个成功写入的远端位置。瞬时连接中断会从该位置自动重试;只有捕获到的远端状态被成功存储后,操作才报告完成。
- 失败不落盘:如果在解密数据、读取远端响应或写入本地数据库时发生错误导致操作停止,LiveSync 不会运行 Vault 扫描,也不会收尾重建后的本地数据库。它同时保留:
- 已保存的远端位置(last successfully stored remote position);
- 所选的数据处理方法(selected data-processing method);
- fetch 旗标(fetch flag)。
- 反射保持挂起:文件监听与数据库反射继续处于挂起状态(
suspendFileWatching与suspendParseReplicationResult均为 true),确保部分重建的数据库不会与新的本地变更混合或被应用到 Vault。
失败后的正确处理步骤:
- 打开 Show log(显示日志),查看第一个具体错误;
- 修正错误原因(例如远端凭据、网络或解密参数问题);
- 重启 Obsidian,从保留状态自动重试;
- 只要你还打算继续该操作,不要删除 fetch 旗标,也不要手动恢复 Scram Switches(挂起开关);
- 若重启后仍出现相同错误,保持 LiveSync 挂起、保留可用数据,并按照 docs/troubleshooting.md 的 Collect a report(收集报告)流程提交问题报告。
从源码看,"keep-on-failure" 策略在 processVaultInitialisation 的 finally 块中会重新断言两个方向的挂起状态(suspendFileWatching: !completed、suspendParseReplicationResult: !completed),即使 finishRebuild 已经开始恢复反射后再失败,也会被重新挂起,保证部分重建的数据始终与 Vault 隔离。
与恢复操作、旗标文件的关系
Fast Setup 通常由 fetch 旗标触发,而旗标文件是 LiveSync 启动序列中受支持的干预手段。完整旗标参照(见 docs/recovery.md):
| Vault 根目录文件 | 效果 |
|---|---|
redflag.md |
挂起常规 LiveSync 工作以便诊断,需手动移除 |
flag_fetch.md 或 redflag3.md |
调度"从所选远端重置本设备同步",即触发 Fast Setup |
flag_rebuild.md 或 redflag2.md |
调度"用本设备文件覆盖服务端数据",或本地 P2P 准备 |
旗标文件本身不会参与同步。Fetch 与 Rebuild 旗标会在流程完成或安全取消后被自动移除;失败的 Fast Setup 会保留 fetch 旗标,以便下次启动继续重试。在 P2P 模式下,触发 Fetch 需要一个在线、被发现并已在 P2P Rebuild 中选定的对等节点,仅打开空的信令房间不会完成拉取。在包含未同步本地工作的 Vault 上执行此类操作前,建议先通读 Fast Setup 指南 与 docs/recovery.md。
小结
Fast Setup 是 Self-hosted LiveSync 面向"第二设备初始化"与"数据库恢复"两大高频场景交付的精简通道:用流式复制替代逐块检索换取速度,用延迟文件反射换取干净无警告的下载过程,用时间戳"新者胜"策略换取免冲突的合并体验。它把原本需要逐项确认的设置向导压缩为两轮高层决策,并依靠"断点续传 + 失败保留状态 + 双方向挂起"的设计保证任何中断都不会污染 Vault 或本地数据库。如果需要进一步探索实现细节,可以从 src/serviceFeatures/redFlag.simpleFetch.ts(流程实现)、src/serviceFeatures/redFlag.ts(旗标与挂起管理)以及 src/serviceFeatures/redFlag.unit.spec.ts(行为验证)入手。