obsidian-livesync Fast Setup(Simple Fetch)详解:第二台设备与数据库重建的快速初始化同步流程
obsidian-livesync Fast Setup(Simple Fetch)详解:第二台设备与数据库重建的快速初始化同步流程
Fast Setup(ファストセットアップ / Simple Fetch)是 obsidian-livesync 插件提供的一种简化数据抓取与初始化流程,面向第二台及后续设备的接入、或本地数据库重建后的数据恢复场景。它用高层的同步策略选择取代了传统设置向导中繁琐的多步对话框,将远程数据库下载与本地 Vault 扫描反映合并为一个连续自动执行的流程。读完本文,你将掌握 Fast Setup 的触发机制、三类数据处理策略与两级冲突/删除规则的取舍,以及中断后的恢复原理与源码级调用链。
Fast Setup 是什么:适用场景与定位
在传统流程中,在第二台设备上接入同步、或在数据库损坏后重建数据,需要经过设置向导(Setup Wizard)中一系列细粒度步骤:选择远端类型、填写 URI、配置加密选项、逐步确认……过程繁琐且容易出错。
Fast Setup 的定位正是替代这一流程:只让用户回答几个高层同步决策问题,随后插件自动完成「远端数据库下载 → 本地文件扫描 → 存储反映」的完整链路。它主要面向两类场景:
- 第二台及后续设备的首次接入:在已有设备通过 Setup URI(
sls+...形式)导入同步配置后,新设备需要从远端拉取全量数据; - 数据库重建后的数据恢复:本地数据库需要从远端重新构建(如执行 Fetch All / Reset Synchronisation)时,快速恢复数据。
它的原始文档位于 docs/tips/fast-setup.md(英文)与 docs/tips/fast-setup_ja.md(日文),下文将结合仓库源码展开讲解。
工作原理:从触发器到「Data retrieval scheduled」对话框
Fast Setup 的启动由预约机制驱动,整个流程分为「预约」与「执行」两个阶段。
触发条件(预约阶段)
在以下任一情况下,插件会为远端数据抓取设置调度:
- 导入 Setup URI:在第二台设备上通过 Setup URI 完成配置导入;
- 手动放置标志文件(flag file):在 Vault 根目录放置
redflag3.md/flag_fetch.md等 Fetch All 标志文件,预约一次全量数据抓取; - 设置对话框触发:在维护面板(PaneMaintenance)中点击 Reset Synchronisation on This Device 的 "Schedule and Restart" 按钮,插件会向 Vault 写入 Fetch All 标志文件并重启。
在源码中,标志文件机制由 src/serviceFeatures/redFlag.ts 中的 createFetchAllFlagHandler 实现。它会同时检查原始文件名与人类可读文件名(FlagFilesOriginal.FETCH_ALL / FlagFilesHumanReadable.FETCH_ALL)两种形式,并在流程结束后通过 cleanupFlag 清理两者。维护面板的写入动作可见于 src/modules/features/SettingDialogue/PaneMaintenance.ts:
// PaneMaintenance.ts(节选)
new Setting(paneEl)
.setName("Reset Synchronisation on This Device")
.addButton((button) =>
button
.setButtonText("Schedule and Restart")
.setCta()
.onClick(async () => {
await this.core.storageAccess.writeFileAuto(FlagFilesHumanReadable.FETCH_ALL, "");
this.services.appLifecycle.performRestart();
})
);
执行阶段(下次启动时)
在下次启动时,插件以数据抓取预约模式(scheduled fetch mode)启动,并显示一个简化对话框:"Data retrieval scheduled"(数据取得のスケジュール)。此时若配置了多个远端(remote configurations),插件会先弹出选择框让用户确认从哪个远端抓取(askAndActivateRemoteDatabase,见 src/serviceFeatures/redFlag.ts);随后进入 Fast Setup 的两级选择流程。
从源码结构可以推断,这一机制的实现集中在 src/serviceFeatures/redFlag.simpleFetch.ts 的 askAndPerformFastSetupOnScheduledFetchAll 函数,它由 Fetch All 标志处理器在启动时(onLayoutReady 事件)被调用。
三大技术特性:快、稳、简
Fast Setup 在底层做了三项关键优化,分别解决速度、可靠性与复杂性问题:
-
流式接收(Stream-based Replication)实现高速抓取 Fast Setup 获取全部远端数据,但使用流式复制(stream reception)而非逐块(chunk-by-chunk)抓取,因此在数据量较大时也能保持很高吞吐。源码中对应
rebuilder.$fetchLocalDBFast(false)——即文档中提到的fetchLocalDBFast。 -
延迟存储反映,抑制不必要的警告 在数据下载阶段,插件刻意推迟向本地文件系统(storage)写入文件的反映(reflection)操作。这样做可以避免同步过程中常见的临时性误报——例如「破壊データ同期(corrupted data synchronisation)」「サイズ不一致(size mismatch)」等警告。直到全部数据下载完成后,才一次性批量写入存储,避免用不必要的警告弹窗打扰用户。从
processVaultInitialisation(src/serviceFeatures/redFlag.ts)的实现看,初始化期间会设置suspendFileWatching: true并调用suspendAllSync()、suspendExtraSync(),正是这一「先抓取、后反映」策略的体现。 -
时间戳比较的合理性 在初始设置或恢复阶段(即刚进入该状态时),Vault 通常处于「全新」或「恢复中」的状态,此时基于文件修改时间(timestamp)的简单比较(newer-wins)已经足够产生准确、合理的同步结果,无需引入复杂的冲突解决机制。
操作步骤详解
步骤 1:选择数据处理方式
用户首先需要回答:抓取到的远端数据如何与本地现有文件集成?
- Compare time and take newer(newer-wins,比较时间取较新)
- 比较文件的修改时间,采用较新的一方。
- 推荐场景:已经在使用 Self-hosted LiveSync,且在多台设备上编辑过内容、希望基于时间戳合并各设备的修改。
- Overwrite all with remote files(remote-wins,远端优先覆盖)
- 将远端数据库内容视为唯一事实源(Source of Truth)。
- 推荐场景:全新设备(如空 Vault)的初始设置。
- ⚠️ 警告:本地所有文件都将被远端内容覆盖。若 Vault 中有重要数据,务必先备份。
- Use the detailed flow(legacy,传统详细流程)
- 回退到传统设置向导的详细对话框。
- 推荐场景:希望逐步细粒度控制、确认数据库配置选项时。
在源码中,这三个选项对应 src/serviceFeatures/redFlag.simpleFetch.ts 顶部的常量,且默认选项为 newer-wins:
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";
步骤 2:配置冲突与删除规则
根据步骤 1 的选择,用户进一步配置本地与远端不一致时的处理方式。
若选择「Compare time and take newer」:
- Delete local files if they were deleted on remote
- 其他设备已删除的文件,也一并从本地删除,保持 Vault 同步且干净。
- 源码映射:
FullScanModes.NEWER_WINS+ExtraOnLocal.DELETE_DB_DELETED。
- Recreate remote files even if they were deleted on remote
- 即使远端已删除该文件,也保留本地文件,并将其重新上传回远端数据库。
- 源码映射:
FullScanModes.NEWER_WINS+ExtraOnLocal.APPEND_STORAGE_ONLY。
若选择「Overwrite all with remote files」:
- Delete local files if not on remote
- 删除远端不存在的本地专有文件,使本地 Vault 与远端数据库完全一致。
- 源码映射:
FullScanModes.DB_APPLY+ExtraOnRemote.DELETE_LOCAL_MISSING。
- Keep local files even if not on remote
- 保留远端不存在的本地文件。注意:同步后可能出现重复文件,需要手动清理。
- 源码映射:
FullScanModes.DB_APPLY(不附加额外删除规则)。
以上映射关系由 buildSimpleFetchResult 函数精确实现(见 src/serviceFeatures/redFlag.simpleFetch.ts),FullScanModes 与 ExtraOnLocal / ExtraOnRemote 枚举来自 livesync-commonlib 的 offlineScanner 模块,同时被 synchroniseAllFilesBetweenDBandStorage 消费。
步骤 3:确认后自动执行
选定并确认后,插件依次执行:
- 快速下载远端数据库:调用
fetchLocalDBFast(源码中为rebuilder.$fetchLocalDBFast(false)),以流式方式把远端数据写入本地数据库; - 前台全量扫描:自动执行
synchroniseAllFilesBetweenDBandStorage(即文档中的synchroniseAllFilesBetweenDBandStorage),将数据库变更反映到本地 Vault 文件。源码中以normaliseFullScanOptions({ ...result.options, showingNotice: true, omitEvents: true, ignoreSuspending: true })调用,保证扫描期间展示进度提示、省略冗余事件并忽略挂起状态; - 恢复正常运行:调用
finishRebuild()结束重建、cleanupFlag()清理标志文件、清除记住的选择(clearRememberedSimpleFetchMode),随后插件回到普通工作状态。
核心执行逻辑如下(节选自 askAndPerformFastSetupOnScheduledFetchAll):
const performFastSetup = async () => {
// 1. 快速抓取远端数据库内容到本地数据库
await host.serviceModules.rebuilder.$fetchLocalDBFast(false);
// 2. 扩展的 synchroniseAllFilesBetweenDBandStorage 将变更反映到存储
const errorManager = new UnresolvedErrorManager(...);
const syncResult = await synchroniseAllFilesBetweenDBandStorage(host, log, errorManager,
normaliseFullScanOptions({ ...result.options, showingNotice: true, omitEvents: true, ignoreSuspending: true })
);
// ...失败时的重跑/放行处理
await host.serviceModules.rebuilder.finishRebuild();
await cleanupFlag();
clearRememberedSimpleFetchMode(host);
return true;
};
源码视角:完整调用链与状态机
标志处理器的优先级注册
Fast Setup 并非孤立功能,而是「Red Flag(标志文件)特性」的一部分。在 src/serviceFeatures/redFlag.ts 的 useRedFlagFeatures 中,三个标志处理器按优先级注册到 onLayoutReady:
| 处理器 | 优先级 | 作用 |
|---|---|---|
createSuspendFlagHandler(SCRAM) |
5 | 检测到 suspend-all 标志时挂起全部操作 |
createFetchAllFlagHandler |
10 | 检测到 Fetch All 标志时触发 Fast Setup 或传统 Fetch |
createRebuildFlagHandler |
20 | 检测到 Rebuild All 标志时以本地覆盖远端重建 |
Fast Setup 只处理「抓取」方向;Rebuild(以本设备文件覆盖远端)仍走传统对话框流程。
选择记忆与断点续传
- 用户的两级选择会被写入设置小配置(key 为
simple-fetch-mode,见rememberSimpleFetchMode/getRememberedSimpleFetchMode),因此流程中断后重启不会再次询问用户; - 流程成功完成后该记录被清除;若用户在下载中取消,则清除记录并恢复预约状态。
挂起策略(suspension policy)
processVaultInitialisation 接收 resume / keep / keep-on-failure 三种挂起策略。Fast Setup 使用 keep-on-failure:初始化期间同时挂起文件监听(suspendFileWatching)与复制结果解析(suspendParseReplicationResult),保证部分重建的数据库不会被应用到 Vault、也不会与新的本地改动混在一起;成功后才按完成状态恢复。
中断与恢复:Fast Setup 停止时怎么办
英文文档 docs/tips/fast-setup.md 对中断场景补充了完整的行为说明,在此一并整理:
-
断点续传:Fast Setup 在保存文档时会记录最后成功存储的远端位置(remote position)。瞬时连接中断会自动从该位置重试;只有捕获的远端状态被成功存储后,操作才会报告完成。
-
错误保护:若在解密数据、读取远端响应或写入本地数据库时发生错误,插件不会运行 Vault 扫描,也不会完成本地数据库的重建。它会保留:
- 已保存的远端位置;
- 已选择的数据处理方式;
- 抓取标志(fetch flag)。
同时,文件监听与数据库反映保持挂起,避免部分重建的数据库被应用。
-
恢复步骤:在 Show log 中查看第一个具体错误,修正原因后重启 Obsidian 从保留状态重试。在打算继续该操作期间,不要删除抓取标志,也不要手动恢复 SCRAM 开关。若重启后错误依旧,保持 LiveSync 挂起、保留现有数据,并按照 docs/troubleshooting.md 中的指引收集报告(Collect a report)。
这一行为在单元测试中得到验证:$fetchLocalDBFast 抛错(如 "cannot decrypt remote document" / "offline")时,测试断言 suspendFileWatching 与 suspendParseReplicationResult 仍为 true、finishRebuild 与 cleanupFlag 均未被调用(见 src/serviceFeatures/redFlag.unit.spec.ts 的 askAndPerformFastSetupOnScheduledFetchAll 用例组)。
测试验证与可靠性保障
src/serviceFeatures/redFlag.unit.spec.ts 是这一流程最完整的可验证依据,覆盖了:
- 两级选择对话框的全部组合(remote-only / newer-wins / detailed / cancel / abort)及对应的
FullScanOptions映射; - 多远端配置下的选择、激活与取消逻辑;
- Fast Setup 成功后释放两个方向的挂起、失败后保持挂起并保留恢复状态;
- 同步失败时用户选择「重启重跑」或「放行完成」的分支;
- 取消 / 中止时标志文件的清理与
performRestart的调用时序。
这些测试从侧面印证了 Fast Setup 是一个经过了严格边界校验、具备断点恢复能力的状态机流程。
小结
Fast Setup(Simple Fetch)是 obsidian-livesync 在「第二台设备接入」与「数据库恢复」两条路径上的核心体验优化:用「流式快速抓取 + 延迟存储反映 + 时间戳比较」三件套换取速度与稳定,用「1 个主策略 + 2 个删除规则」的两级问答换取配置的直观性。理解其触发标志(redflag3.md / flag_fetch.md 或维护面板按钮)、策略映射与中断恢复语义,可以帮助你在多设备场景下安全、高效地重建本地数据库。
继续深入阅读: