背景 链接到标题

Self-hosted LiveSync 插件的配置分散在多个设置页面，首次配置需要经过数步对话框引导，涉及 CouchDB 连接、同步模式、Doctor 诊断等多项设置。如果跨多台设备部署，每次手动点对话框效率低且难以保持一致。

将配置收敛到插件目录下的 data.json 文件 + 服务器端 CLI 操作，可以实现可重复、可审计、跨设备一致的部署流程。

服务器端：CouchDB 初始化 链接到标题

Livesync 需要 CouchDB 作为同步后端。以 CouchDB 3.x 为例，通过 API 完成初始化。

创建数据库 链接到标题 

curl -X PUT -u admin:密码 http://couchdb:5984/笔记库名

创建专用用户 链接到标题

为每个同步的 vault 创建独立用户，限制其权限范围：

curl -X PUT -u admin:密码 \
  http://couchdb:5984/_users/org.couchdb.user:sync_用户名 \
  -H "Content-Type: application/json" \
  -d '{"_id":"org.couchdb.user:sync_用户名","name":"sync_用户名","type":"user","roles":[],"password":"随机密码"}'

设置数据库权限 链接到标题

仅该用户和 admin 可以访问：

curl -X PUT -u admin:密码 \
  http://couchdb:5984/笔记库名/_security \
  -H "Content-Type: application/json" \
  -d '{"admins":{"names":["admin"],"roles":["_admin"]},"members":{"names":["sync_用户名"],"roles":[]}}'

验证权限隔离：

# 新用户可以访问自己的库
curl -u sync_用户名:密码 http://couchdb:5984/笔记库名

# 但无法访问其他库
curl -u sync_用户名:密码 http://couchdb:5984/其他库名
# → {"error":"forbidden","reason":"You are not allowed to access this db."}

客户端：data.json 配置 链接到标题

Livesync 插件的配置文件位于 vault 下的 .obsidian/plugins/obsidian-livesync/data.json。所有设置均以 JSON 格式存储，编辑该文件等效于在插件设置面板中操作。

连接信息 链接到标题 

{
  "couchDB_URI": "http://couchdb:5984",
  "couchDB_USER": "sync_用户名",
  "couchDB_PASSWORD": "密码",
  "couchDB_DBNAME": "笔记库名"
}

插件首次启动后会自动加密这些明文凭证，迁移到 remoteConfigurations 字段，并清空明文字段。

同步模式 链接到标题 

{
  "liveSync": true,
  "syncOnSave": true,
  "syncOnStart": true,
  "syncOnFileOpen": true
}
字段 作用
liveSync 实时同步（双向）
syncOnSave 保存时触发同步
syncOnStart 启动时自动开始同步
syncOnFileOpen 打开文件时同步

设备标识 链接到标题 

{
  "deviceAndVaultName": "机器名 - vault名"
}

用于在多设备间区分来源。

跳过首次欢迎向导 链接到标题 

{
  "isConfigured": true,
  "doctorProcessedVersion": "0.25.27"
}

isConfigured 设为 true 可跳过初始配置对话框。doctorProcessedVersion 填写诊断规则的版本号（不是插件版本号），对应 livesync 内置的 DoctorRegulation 版本。插件 0.25.79 对应的诊断规则版本是 0.25.27。

Doctor 诊断项 链接到标题

以下字段可通过配置文件预设，避免插件启动后逐个弹窗询问。

大小写敏感处理 链接到标题 

{
  "handleFilenameCaseSensitive": false
}

macOS 默认 APFS 文件系统不区分大小写，此项保持 false。如启用，与 Windows/Android 同步时可能产生意外行为。

按文件自定义同步 链接到标题 

{
  "usePluginSyncV2": true
}

启用后使用新的按文件高效同步机制。开启后与旧版本不兼容，所有设备需更新至 v0.23.18 以上。

Chunk 大小优化 链接到标题 

{
  "customChunkSize": 60,
  "minimumChunkSize": 5
}
字段 说明 推荐值
customChunkSize 增强 chunk 大小 60
minimumChunkSize 最小 chunk 阈值 5

其他 链接到标题 

{
  "notifyThresholdOfRemoteStorageSize": 0,
  "hashAlg": "xxhash64",
  "chunkSplitterVersion": "v3-rabin-karp",
  "E2EEAlgorithm": "v2",
  "useEden": false,
  "enableCompression": false
}

notifyThresholdOfRemoteStorageSize 设为 0 可禁用容量警告对话框。

完整 data.json 示例 链接到标题 

{
  "couchDB_URI": "http://couchdb:5984",
  "couchDB_USER": "sync_myai",
  "couchDB_PASSWORD": "随机密码",
  "couchDB_DBNAME": "笔记库名",
  "liveSync": true,
  "syncOnSave": true,
  "syncOnStart": true,
  "syncOnFileOpen": true,
  "deviceAndVaultName": "MacBook - my-ai-notes",
  "handleFilenameCaseSensitive": false,
  "usePluginSyncV2": true,
  "customChunkSize": 60,
  "minimumChunkSize": 5,
  "notifyThresholdOfRemoteStorageSize": 0,
  "isConfigured": true,
  "doctorProcessedVersion": "0.25.27",
  "hashAlg": "xxhash64",
  "chunkSplitterVersion": "v3-rabin-karp",
  "E2EEAlgorithm": "v2",
  "useEden": false,
  "enableCompression": false
}

注意事项 链接到标题

凭证加密 链接到标题

插件启动后会自动将 couchDB_PASSWORD 等敏感信息加密存储。加密后 data.json 中会出现 remoteConfigurations 和 encryptedCouchDBConnection 字段，明文字段被清空。这是正常行为，后续启动不再需要明文凭证。

如需修改连接信息，需先清空 remoteConfigurations 和 encryptedCouchDBConnection，重新填入明文再重启。

配置变更后需重建远端库 链接到标题

如果本地配置变更后远端 CouchDB 已有同步元数据，插件会检测到设备间配置不匹配并阻止连接。原因在于数据库中的 obsydian_livesync_version 文档记录了初始同步时的配置参数，本地变更后不再匹配。

解决方案：删除并重建 CouchDB 数据库，插件会自动写入新的匹配参数。

curl -X DELETE -u admin:密码 http://couchdb:5984/笔记库名
curl -X PUT -u admin:密码 http://couchdb:5984/笔记库名
# 重新设置权限

doctorProcessedVersion 链接到标题

该字段存的是 Livesync 内置诊断规则的版本号。插件代码中有多个 DoctorRegulation 对象，当前最新为 DoctorRegulationV0_25_27。如果填了插件版本号或空字符串，Doctor 会每次启动都重复弹窗。

数据库命名惯例 链接到标题

Livesync 的 additionalSuffixOfDatabaseName 字段（插件自动生成）用于区分多设备数据，主数据库名不变。避免多个 vault 使用相同的前缀名，否则可能混淆数据。

验证同步 链接到标题

启动 Obsidian 后查看 Livesync 日志面板，确认输出类似：

OneShot Sync begin... (pullOnly)
Replication completed
LiveSync begin...

查看 CouchDB 数据库文档数增长即表示同步正常运行：

curl -u sync_用户名:密码 http://couchdb:5984/笔记库名 | jq .doc_count

总结 链接到标题

通过 data.json + CouchDB API 完成 Livesync 配置，相比对话框交互有以下优势：

  • 可重复：同一份配置文件可用于多台设备
  • 可审计：diff data.json 即可知道配置变更历史
  • 一致性强：消除手动操作时的笔误或遗漏
  • 可纳入部署流程：适合服务器端批量初始化

对于单独使用的技术用户，纯配置文件方式省去了每次设备初始化时的繁琐点击，且后续维护只需编辑一个 JSON 文件。