obsidian-livesync 快速设置向导指南:用 Setup Wizard 与 Setup URI 完成自托管同步的初始配置

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

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 即可打开向导。如果插件尚未完成任何设置、或没有启用任何同步设置,向导会在默认情况下自动打开。

Setup Wizard 入口对话框

在向导入口处,需要先决定如何处理已有的配置:

  • Discard the existing configuration and set up:清空当前全部设置后开始向导,适合完全重新配置的场景;
  • Do not discard the existing configuration and set up:保留现有设置、直接开始向导。注意:即使已有配置,在向导模式下也无法看到全部设置项,只能看到向导暴露的核心步骤。

无论选择哪一项,点击对应的 Next 按钮后,设置界面就会进入「Wizard 模式」(向导模式),之后按顺序逐项配置即可。

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(路径混淆),文件路径/文件名也会被混淆,官方文档认为该功能目前已足够稳定,同样推荐启用。

机密性设置:E2EE 与 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 会被复制到剪贴板,你需要通过某种安全渠道把它传递给第二台及后续设备。

为 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 之后:

  1. 打开命令面板,执行 Use the copied setup URI (Formerly Open setup URI);
  2. 粘贴从第一台设备复制来的 Setup URI;
  3. 输入之前设置的口令,向导随即打开,并出现两个确认问题:
  • Importing LiveSync's conf, OK? → 选择 Yes
  • How 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)。详细说明见 ファストセットアップガイド。

相关资源

登录后查看全文
obsidian-livesync