Obsidian Self-hosted LiveSync Fast Setup 快速设置指南:流式拉取加速二设备初始化与数据库恢复

原创2026-09-22 16:35:502,000 阅读
文章标签:数据同步插件系统WebRTC跨平台密码学对象存储

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 会在以下两类场景被调度:

  1. 导入 Setup URI:在第二台设备上导入由首台设备生成的 Setup URI(对应 src/serviceFeatures/setupObsidian/setupUri.ts 中的 copySetupURI / copySetupURIFull 命令生成的一键配置串),插件会预约定时远端数据拉取;
  2. 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 的实现):

  1. 快速下载远端数据库:调用 fetchLocalDBFast 将远端数据库内容下载到本地;
  2. 前台全量扫描:调用 synchroniseAllFilesBetweenDBandStorage 在前台全量扫描,将数据库变更立即反映到本地 Vault 文件。该调用使用扩展选项:normaliseFullScanOptions({ ...result.options, showingNotice: true, omitEvents: true, ignoreSuspending: true }),即显示进度通知、省略事件触发、忽略挂起限制;
  3. 收尾并恢复正常运行:调用 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。

失败后的正确处理步骤:

  1. 打开 Show log(显示日志),查看第一个具体错误;
  2. 修正错误原因(例如远端凭据、网络或解密参数问题);
  3. 重启 Obsidian,从保留状态自动重试;
  4. 只要你还打算继续该操作,不要删除 fetch 旗标,也不要手动恢复 Scram Switches(挂起开关);
  5. 若重启后仍出现相同错误,保持 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(行为验证)入手。

登录后查看全文
obsidian-livesync