obsidian-livesync 快速设置向导指南:用 Setup Wizard 与 Setup URI 完成自托管同步的初始配置
obsidian-livesync 快速设置向导指南:用 Setup Wizard 与 Setup URI 完成自托管同步的初始配置
本指南围绕 obsidian-livesync(Self-hosted LiveSync)的「セットアップウィザード(Setup Wizard)」展开,讲解如何在第一台设备上通过向导完成远程数据库、加密与同步策略的初始配置,并通过 Setup URI 快速接入第二台及后续设备。读完本文,你将掌握向导每一步的配置含义、E2EE 加密与 Path Obfuscation 的作用、Setup URI 的正确生成与传递方式,以及向导在源码层面的实际执行流程。
为什么需要 Setup Wizard
obsidian-livesync 是一个功能非常丰富的 Obsidian 同步插件,为应对各种场景提供了大量可配置项。但从实际使用来看,绝大多数用户真正需要调整的选项并不多。为了让初始配置尽量简化,插件实现了「セットアップウィザード(Setup Wizard)」——把最关键的配置步骤(远程数据库、加密、同步预设)串成一个引导式流程。
从源码结构看,向导由 SetupManager 统一驱动,它负责在 new-user、existing-user、unknown 三种用户模式下分发到不同的向导对话框组件(位于 src/modules/features/SetupWizard/dialogs 目录),例如 Intro.svelte、SelectMethodNewUser.svelte、SetupRemoteCouchDB.svelte、SetupRemoteE2EE.svelte 等。这意味着向导本质上是「用户模式判断 + 分步对话框 + 设置应用与初始化调度」的组合。
需要特别注意的是:从第二台设备开始,不再需要重复走完整个向导,而是使用 現在の設定をセットアップURIにコピー(Copy settings as a new Setup URI)与 セットアップURIで接続(Use the copied setup URI)来完成配置复制。
向导的打开方式与两种启动模式
通过命令面板执行 🧙♂️ Setup wizard 即可打开向导。如果插件尚未完成任何设置、或没有启用任何同步设置,向导会在默认情况下自动打开。
在向导入口处,需要先决定如何处理已有的配置:
- Discard the existing configuration and set up:清空当前全部设置后开始向导,适合完全重新配置的场景;
- Do not discard the existing configuration and set up:保留现有设置、直接开始向导。注意:即使已有配置,在向导模式下也无法看到全部设置项,只能看到向导暴露的核心步骤。
无论选择哪一项,点击对应的 Next 按钮后,设置界面就会进入「Wizard 模式」(向导模式),之后按顺序逐项配置即可。
Remote Database configuration:远程数据库配置
进入 Wizard 模式后,第一步是配置远程数据库。需要填写的信息,就是你在搭建数据库(如 CouchDB)时自行决定的那几项:
| 字段 | 说明 |
|---|---|
| Remote database URI | 远程数据库地址,例如 http://localhost:5984(Obsidian Mobile 端要求 HTTPS) |
| Username | 连接数据库的用户名 |
| Password | 该用户的密码 |
| Database name | 数据库名称,例如 the_database |
关于地址的合法性,源码中的 isValidCouchDBServerURL(见 src/modules/features/SetupWizard/dialogs/couchDBConnectionProbe.ts)会校验:地址必须使用 http: 或 https: 协议且 hostname 非空,否则无法通过校验。更完整的服务器准备流程可参考 docs/setup_own_server.md。
Test database connection 与 Check database configuration
填写完连接信息后,需要依次确认「能否连上」与「配置是否完备」两个问题:
- Test Database Connection:只验证能否连接到数据库。失败可能有多种原因;此时建议先执行一次 Check database configuration,观察该项是否同样失败,以便定位问题;
- Check database configuration:检查数据库配置是否满足插件要求,发现不备之处会当场修复。
检查项会随连接对象的不同而变化。例如上图中列出的 httpd.enable_cors、couchdb.max_document_size 等问题,需要逐个点击 Fix 按钮。当 Fix 按钮全部消失、所有检查项都变为勾选状态时,即表示配置检查通过。
从实现上看,检查与修复逻辑对应 couchDBServerFixConfirmation.ts,而「在连接测试期间如何对待 CouchDB 远程资源」由 probeCouchDBConnection(couchDBConnectionProbe.ts)通过 withOwnedRemoteResource 管理,它会在一次「拥有的远程资源」生命周期内完成 check({ createIfMissing, showResult: false })。createIfMissing 参数决定了连接测试时是否允许自动创建缺失的数据库。
機密性設定:端到端加密与路径混淆
为防止数据库内容被意外暴露,向导建议启用 End to End Encryption(端到端加密)。启用后,笔记内容在离开设备的那一刻就会被加密。若同时启用 Path Obfuscation(路径混淆),文件路径/文件名也会被混淆,官方文档认为该功能目前已足够稳定,同样推荐启用。
加密算法采用的是 256-bit 的 AES-GCM。只有在满足以下条件时才建议关闭这些设置:
- 你处于完全封闭的网络内部(例如公司/家庭内网);
- 并且可以明确保证不会被第三方访问。
从源码看,这组配置对应 EncryptionSettings 类型(E2EE 开关、加密口令、路径混淆等),由 SetupRemoteE2EE.svelte 对话框采集,最终并入插件设置(见 SetupManager.ts 中的 onlyE2EEConfiguration 与 onConfigureManually 调用链)。
Next 与 Discard exist database and proceed
加密配置完成后:
- Next:直接进入下一步;
- Discard exist database and proceed:当远端数据库中已经存在数据时,选择该项会先丢弃远程数据库中的内容,再继续后续步骤——这是一个破坏性操作,仅应在确认远程数据可以清空时使用。
Sync Settings:同步预设与初始化
向导的最后一步是选择同步方式。从 Presets(预设) 中选择任一同步策略并点击 Apply,插件会根据需要初始化/构建本地与远程数据库。
当界面显示「All done!」(日文环境显示「完了!」)时,配置即告完成。此时插件会自动打开「現在の設定をセットアップURIにコピー(Copy settings as a new Setup URI)」对话框,要求输入一个用于加密 Setup URI 的パスフレーズ(口令)。
重要:这个口令只用于加密 Setup URI 本身,不是 Vault 数据的加密密钥。二者的定位不同:口令保护「配置串」的机密性,Vault 加密口令保护「同步数据」的机密性。
输入口令后,Setup URI 会被复制到剪贴板,你需要通过某种安全渠道把它传递给第二台及后续设备。
源码视角:向导如何应用设置并调度初始化
向导并不只是「填表保存」,设置应用与初始化调度在源码中有明确的先后关系。关键逻辑位于 SetupManager.onConfirmApplySettingsFromWizard:
- 新用户(
UserMode.NewUser)场景:先调用applySettingsWithScheduledInitialisation(this.core.rebuilder, "rebuild", ...),在启用导入的设置之前先预约 rebuild(重建),避免当前运行时提前开始普通同步流程; - 已有用户(
UserMode.ExistingUser)场景:预约fetch模式,必须先取回远端数据,再进行普通启动扫描。
这解释了为什么第二台设备导入 Setup URI 后通常先看到「数据取得」流程——因为它处于 fetch 调度模式。此外,onCouchDBManualSetup 会根据用户模式将 CouchDB 连接模式设为 create-or-connect(新用户)、connect-existing(已有用户)或 settings,并通过 upsertRemoteConfigurationInPlace 写入远程配置档案,然后才把 remoteType 设为 REMOTE_COUCHDB 并激活。
如果是从外部应用(如移动端扫码或点击链接)唤起向导,则通过 setuplivesync 协议处理:registerSetupProtocolHandler(src/serviceFeatures/setupObsidian/setupProtocol.ts)解析 obsidian://setuplivesync?settings=...,再调用 setupManager.onUseSetupURI(UserMode.Unknown, ...) 或 decodeQR 走同一套「确认并应用设置」的流程。
第二台及后续设备的设置方法
在第二台设备上安装 Self-hosted LiveSync 之后:
- 打开命令面板,执行
Use the copied setup URI (Formerly Open setup URI); - 粘贴从第一台设备复制来的 Setup URI;
- 输入之前设置的口令,向导随即打开,并出现两个确认问题:
Importing LiveSync's conf, OK?→ 选择 YesHow would you like to set it up?→ 选择 Set it up as secondary or subsequent device
确认后,第一台设备的全部配置(远程数据库、加密、同步策略)会反映到当前设备,复制(replication)随之开始。
从源码看,该入口对应 onUseSetupURI(SetupManager.ts),它会打开 UseSetupURI.svelte 对话框解析并解密 URI 中的设置,再进入与第一台设备相同的 onConfirmApplySettingsFromWizard 流程——区别仅在用户模式为已有用户时走 fetch 调度,而不是 rebuild。
ファストセットアップ(Fast Setup / Simple Fetch)
近期版本提供了一种更简化的初始同步流程:当第二台设备导入 Setup URI、或通过 Vault 根目录放置 redflag3.md / flag_fetch.md 等方式预约重新获取数据后,插件会在下次启动时进入数据获取预约模式,显示「Data retrieval scheduled(データ取得のスケジュール)」对话框。
Fast Setup 允许你直接选择同步策略:
- Compare time and take newer (newer-wins):按文件修改时间取较新者,适合已在多台设备上使用并希望按时间戳合并的场景;
- Overwrite all with remote files (remote-wins):以远端数据库为准,适合全新(空)Vault 的初始化,注意本地文件会被远端内容覆盖;
- Use the detailed flow (legacy):退回传统分步向导。
Fast Setup 的实现上采用了流式复制快速下载全部数据(fetchLocalDBFast),并有意延迟存储写入,待全部数据下载完成后再统一反映到本地,从而抑制「破損データ同期」「サイズ不一致」等瞬时告警;随后自动执行前台全量扫描(synchroniseAllFilesBetweenDBandStorage)。详细说明见 ファストセットアップガイド。
相关资源
- docs/setup_own_server.md:准备 CouchDB 服务器与 Setup URI 的完整流程;
- docs/tips/fast-setup_ja.md:Fast Setup / Simple Fetch 的机制与策略选择;
- docs/quick_setup_cn.md 与 docs/quick_setup.md:同一指南的中文与英文版本,英文版还包含「手动配置 CouchDB」与「首台设备完整实操」章节;
- 向导实现源码:src/modules/features/SetupManager.ts 与 src/modules/features/SetupWizard/dialogs;
- 向导单元测试:SetupManager.unit.spec.ts、couchDBConnectionProbe.unit.spec.ts,可用于验证上述流程的预期行为。






