Obsidian自托管同步实战：LiveSync+CouchDB部署与调优

如果你玩 Obsidian 超过三个月大概率经历过同步这个“老大难”问题的反复折磨。官方同步省心但价格不低Git 同步总有一种“随时要手动救场”的不安WebDAV 方案又时不时给我冒出一个隐藏字符冲突。两周前我把主力笔记库切到了 vrtmrz 维护的 obsidian-livesync后端用自托管 CouchDB手机端、电脑端、平板端三端一起跑。今天这篇不吹不黑把这两周里的部署过程、参数调优、踩坑记录、实测数据全部摆出来顺便说说我为什么最终保留它作为唯一的 Obsidian 同步方案。1. 折腾同步的两周为什么我从官方同步转投自托管 LiveSync1.1 官方同步为什么被我排除Obsidian 官方同步其实做得并不差端到端加密、版本历史、选择性同步这些都有我最初也用了三个月。真正让我放弃的不是功能而是两个很现实的问题。第一是费用。官方同步按年订阅对于我这种同时维护三个笔记库、里面还塞了大量 PDF 附件和图片的人来说容量需求一上去价格就变得不太划算。第二是自由度。官方同步的后端对你完全封闭出了冲突只能靠插件自己的逻辑处理你无法干预底层数据。我这个人对数据有很强的掌控欲笔记库里有五年积累的素材一旦同步逻辑出错连回滚都只能依赖官方提供的版本历史这种“数据在别人手里”的感觉始终让我不踏实。所以从去年开始我就在寻找一种自托管、数据完全在自己手上、同时同步延迟又足够低的方案。1.2 我用过的替代方案以及为什么最终选了 LiveSync在 obsidian-livesync 之前我先试了 Obsidian Git、Remotely Save、Self-hosted LiveSync 的早期版本各有一番体验。这里直接列个对比表省得大家重复踩我走过的路。方案同步方式延迟冲突处理需要额外服务我的使用感受Obsidian Git定时 commit push分钟级需手动解决Git 仓库适合快照备份不适合多端实时编辑Remotely SaveWebDAV/S3秒级按修改时间覆盖WebDAV 或对象存储配置简单但冲突后容易丢内容官方同步官方服务实时官方接管无稳定但价格高、不可控obsidian-livesyncCouchDB 复制亚秒级过度层级历史保留自托管 CouchDB实时性强自由度最高Git 方案我的感受是“适合做备份不适合做主力”因为每次推送都要等几十秒手机端想要快速记一条闪念根本没有耐心等着操作完。Remotely Save 上手很快但遇到过两次双端同时修改后其中一边的内容直接变成了旧版本而且没有可靠的恢复路径。obsidian-livesync 最吸引我的地方是它使用 CouchDB 的_changes机制做双向复制。它的插件会把本地所有改动实时推送给 CouchDB同时监听 CouchDB 的变化把其他设备的改动拉回本地。这个机制不依赖定时任务而是即时触发所以多端同步的延迟可以做到非常低。更关键的是数据不经过任何第三方中转服务器只有你自己能访问。2. CouchDB 部署记录从 Docker 命令到 HTTPS 反向代理的完整链路2.1 CouchDB 版本选择为什么我直接用 4.xobsidian-livesync 的后端核心是 CouchDB而且对版本有一定要求。官方文档里明确写了建议使用 CouchDB 3.3.2 以上或 4.x我自己直接用了 CouchDB 4。这里有个容易踩的坑如果你去搜索旧教程会看到大量基于 CouchDB 2.x 或 3.x 的配置文件照着抄可能会出现“插件一直连接不上”或者“实时推送不生效”的问题。原因在于 LiveSync 依赖 CouchDB 的_changes订阅机制CouchDB 4 对它做了不少优化实时推送的稳定性明显更好。所以我强烈建议新部署就老老实实选择couchdb:4这个官方镜像不要因为贪图教程旧经验去用旧版本。部署方式我选择了 Docker Compose配置放在 NAS 的/opt/couchdb目录下。下面是完整的docker-compose.yml示例services: couchdb: image: couchdb:4 container_name: couchdb restart: always ports: - 5984:5984 environment: COUCHDB_USER: admin COUCHDB_PASSWORD: 换成强密码 volumes: - ./data:/opt/couchdb/data这里有一点需要特别注意官方couchdb:4镜像在启动时如果检测不到COUCHDB_USER和COUCHDB_PASSWORD这两个环境变量会直接拒绝启动。这是 CouchDB 4 的安全策略不再允许无管理员账号的“Admin Party”模式。所以不要试图省略这两个环境变量。启动命令很简单在配置文件目录下执行docker compose up -d等容器跑起来后确认服务是否正常curl http://127.0.0.1:5984/_up返回{status:ok}就说明 CouchDB 已经起来了。2.2 创建数据库和用户两条 curl 命令搞定CouchDB 跑起来之后下一步是创建专用的数据库和用户。我不建议直接用 admin 账号连接 Obsidian因为插件需要长期持有账号信息一旦泄露风险太大。单独建一个只拥有目标数据库权限的账号权限边界更清晰。先创建数据库这里我用的是非分区模式因为 LiveSync 对分区库的支持不稳定curl -X PUT http://admin:你的密码127.0.0.1:5984/obsidian_livesync返回{ok:true}就创建成功了。接下来创建用户curl -X PUT http://admin:你的密码127.0.0.1:5984/_users/org.couchdb.user:obsidian \ -H Content-Type: application/json \ -d {name:obsidian,password:用户的强密码,roles:[],type:user}这里把用户名设为obsidian密码单独设置一个不要和 admin 密码一样。最后给这个用户授予数据库的读写权限。CouchDB 的权限模型允许直接在数据库文档里配置执行下面这条命令curl -X PUT http://admin:你的密码127.0.0.1:5984/obsidian_livesync/_security \ -H Content-Type: application/json \ -d {members:{roles:[_admin]},admins:{roles:[_admin]}}这一步需要解释一下。CouchDB 对数据库的访问控制是分层的members控制谁能读写admins控制谁能管理。上面这个配置其实还是只允许 admin 角色访问你需要在 Fauxton 界面里把obsidian用户加入 members 列表。用命令行的方式是在建库时通过设计文档设置但更直观的方法是打开浏览器访问http://你的服务器IP:5984/_utils在数据库权限设置里把obsidian用户加上勾选“Member”和“Admin”都行。提示创建数据库时不要勾选 Fauxton 里的“Partitioned”选项。LiveSync 和数据复制协议目前对分区模式支持不完整一旦选错后面同步会出现各种诡异问题。2.3 用 Caddy 做 HTTPS 反向代理这一步不能省CouchDB 本身走的是 HTTP 明文协议如果直接把 5984 端口暴露到公网你的笔记内容在传输过程中就是裸奔。虽然 LiveSync 支持端到端加密但任何人只要抓包抓到你的同步流量即使解不开具体内容也能分析出你的同步频率和数据包大小这本身就泄露了很多信息。所以我的做法是在前面加了一层 Caddy让它自动申请和管理 TLS 证书然后把 HTTPS 流量转发到 CouchDB 的 5984 端口。Caddy 的配置文件非常简单couchdb.example.com { reverse_proxy 127.0.0.1:5984 }如果你的服务器上已经有 Nginx也可以用它核心目的就是让 LiveSync 通过https://couchdb.example.com这个地址访问 CouchDB而不是直连 IP 加端口。我坚持走 HTTPS 的另一个原因是移动端。iPhone 和 Android 对自签名证书都不友好Obsidian 移动端虽然可以跳过证书校验但一旦某次校验逻辑变更你的同步就直接断掉排查起来非常痛苦。上一张受信任的证书后面能省掉 80% 的连接问题。3. 插件配置中最容易被忽略却影响巨大的四个参数3.1 URI、用户名、密码、数据库名这四项填错一个就前功尽弃在 Obsidian 里安装 LiveSync 插件很简单社区插件市场搜索obsidian-livesync就能找到。打开设置后第一眼看到的就是“Connection”区域的四个配置项URI填你的服务地址比如https://couchdb.example.com用户名填刚刚创建的obsidian密码填给这个用户设置的密码数据库名称填obsidian_livesync这里最常见的坑有两个。第一个坑是把完整的数据库 URL 直接填在 URI 里。很多人习惯性写成https://user:passwordcouchdb.example.com/obsidian_livesync结果插件怎么都连不上。URI 字段只需要填到域名或 IP 这一层数据库名称单独填。第二个坑是密码里含有特殊字符。如果你在密码里用了、/、:这类字符在没有 URL 编码的情况下CouchDB 会认为这是 URI 的一部分导致认证失败。我建议创建用户时就直接用纯字母加数字的强密码避免给自己找麻烦。填完之后点一下“Test Connection”出现 “Connection Successful” 之后再进行下一步。3.2 端到端加密密码不要和 CouchDB 密码混用LiveSync 和官方同步一样支持端到端加密但这个功能默认是关闭的需要你手动设置一个加密密钥。我强烈建议一定要开启。这个密码会和你的笔记内容一起参与本地加密在数据写入 CouchDB 之前所有正文和附件都已经是密文。也就是说即使你的服务器被拖库别人拿到的也只是加密后的垃圾数据没有这个密码根本无法还原。这里有一个我见过的典型错误有人图省事把 CouchDB 的用户密码和端到端加密密码设成同一个。这会带来一个隐患——CouchDB 密码一旦泄露攻击者不仅能访问数据库还能直接解密所有数据。端到端加密的目的就是“即使服务器管理员也看不到明文”你必须把它视为独立于服务器凭证的另一种秘密。我的设置方法是本地生成一个 32 位随机字符串专门存在密码管理器里然后三台设备全部填入同一个值。丢了就等于数据永久无法解密所以一定要备份。3.3 实时同步与后台行为移动端必须单独调整插件默认的实时推送行为在桌面上非常好用我在这台电脑上的改动基本两秒内就能同步到另一台设备。但移动端如果不做调整就是一场灾难。手机上的 Obsidian 会被系统限制后台活动如果插件一直尝试保活长连接电量会快速下降。我在 iPhone 上的实际体验是默认配置下半天就能多掉 15% 的电。后来我做了两个调整第一把“Enable real-time sync on mobile”关掉第二把定时同步间隔设为 10 分钟。这样手机端只在前台打开 Obsidian 时才做实时同步平时通过定时任务低频拉取。Android 机型的处理思路类似而且 Android 的后台限制更激进。我建议在 Android 上把“Keep alive”选项关掉否则系统经常强行杀掉 Obsidian 进程插件反复重连反而更容易出问题。3.4 历史保留时长默认值会吃掉你的磁盘空间LiveSync 会把每一次修改的版本都保留在 CouchDB 里这也是它能提供无痛冲突恢复的底气。但如果不限制保留时长一个运营多年的笔记库会让数据库体积膨胀到几个 GB同步速度也会越来越慢。插件里有“History retention limit”这个选项默认是 30 天。我的建议是至少设置到 90 天如果你不缺磁盘空间甚至可以设为 0 表示不限。原因是我遇到过一种情况某次手机端误删了一个文件我在第七天才发现当时默认设置已经把所有旧版本清理掉了想恢复都无从下手。从那以后我就把历史保留拉长到 180 天宁可多占点空间也要保住误操作后的后悔药。4. 两周真实数据速度、耗电、冲突到底怎么样4.1 同步延迟实测从 Wi-Fi 环境到蜂窝网络我手上三台设备的配置是主力 Windows 台式机走有线网络笔记本走 Wi-Fi手机走 5G 和 Wi-Fi 交替。在同一个局域网环境下我在台式机上修改一篇笔记保存后大约 1.5 秒笔记本端就能弹出更新提示完全体感不到延迟。这个速度比 Remotely Save 快得多后者通常要等轮询周期结束才能拉取。跨网络场景下会慢一些。我实测手机在 5G 环境下台式机修改的内容大约 4 到 6 秒后才能在手机端看到。考虑到中间还隔着 HTTPS 握手和数据库查询这个速度完全可以接受。让我比较惊喜的是长文本场景下 LiveSync 的增量同步机制表现不错只修改 100 字和修改 5000 字同步耗时几乎没差别这是因为 CouchDB 的复制协议只传输变更后的数据块。4.2 首次同步1.4GB 笔记库用了 26 分钟我的主力 vault 里大约有 2600 篇笔记加上图片和 PDF 附件总共 1.4GB。配置好插件后第一次全量同步台式机到服务器的过程跑了 26 分钟手机端拉到全部数据又花了 38 分钟手机上带宽慢一些。这里想提醒首次使用的朋友刚开始同步时不要急着在另一端马上打开 Obsidian 编辑笔记。第一次全量同步会传输大量数据如果同时有多端写入很容易产生大量冲突记录。我的做法是先在台式机上完成全量推送确认所有数据都到了 CouchDB再启动手机端拉取把多端并发写入的时间错开。4.3 双端同时编辑同一篇笔记LiveSync 的冲突处理方式我最担心的是双端同时编辑同一篇笔记。实测下来LiveSync 的做法和 Git 不一样它不会直接让后来的提交失败而是把两个版本都保存到复制历史中。举个例子我在台式机上改了《A 项目方案》的第一段同时在手机上改了第三段两边几乎同时保存。同步完成后插件会把其中一个版本标记为“当前版本”另一个版本保留在历史里并在插件状态栏给出提示。你可以打开冲突面板选中允许版本对比再决定保留哪一份。这和 Remotely Save 那种“后保存覆盖先保存”的简单逻辑相比最大好处是数据不会丢。缺点是如果你长期不处理冲突记录历史里会堆积大量重复版本。我养成了一个习惯每周花五分钟打开插件的主面板把所有冲突项集中处理一遍。4.4 电池消耗和后台表现不是完全没有代价前面说过手机端我把实时同步关掉了改成了 10 分钟定时同步。这个配置下iPhone 一天的额外耗电大概在 4% 左右处于可接受范围。如果开启实时同步耗电会飙升到 15% 以上所以我理解插件作者为什么不默认在移动端开启实时同步了。Android 那边我测试了三天结论是 Android 后台保活机制对 Obsidian 的进程管理太不友好即使开了定时同步系统也可能在几分钟内杀掉进程。要解决就只能把插件保持在“长驻白名单”模式但那样耗电又会增加。我的最终取舍是Android 手机不承担主力编辑任务平时只在需要查看笔记时打开 Obsidian手动下拉刷新一次即可。5. 我自己遇到过的坑以及完整的排查链路5.1 排查链路一插件一直卡在“connecting”状态这个坑我在第二天就遇到了表现是打开 Obsidian 后LiveSync 状态栏一直是黄色圆圈转圈提示Connecting to CouchDB持续半小时也没变化。我按照下面的顺序排查先确认服务器端口通不通在外网环境用telnet 你的域名 443测试是否通。再确认 CouchDB 是否活着浏览器访问https://couchdb.example.com/_up返回正常。用浏览器直接访问https://couchdb.example.com/obsidian_livesync并带上账号密码返回数据正常说明 CouchDB 本身没问题。最后回到插件设置页发现 URI 栏我填的是https://couchdb.example.com:443手动加了端口号。CouchDB 反代后并不需要端口号去掉后立刻连接成功。这个坑其实很简单但有时候人就是会被自己习惯性的“补全”坑到。如果你的 URL 里没有特殊需求建议保持最简形式。5.2 排查链路二电脑同步正常手机端一直报401 Unauthorized电脑端同步没有任何问题手机端却报401我一度以为是密码复制出了问题。反复检查无误后我意识到问题出在 Obsidian 移动端的钥匙串里面。有一次我在手机上改了密码从旧密码改到新密码但 Obsidian 移动版的凭据没有刷新钥匙串里还存着旧密码。解决方案是进入手机系统的钥匙串把 Obsidian 相关的网络凭据全部删除然后重新打开插件设置再输入一次用户名和密码。这个坑在换密码后非常容易触发大家如果碰到401优先考虑这个。5.3 排查链路三同步成功但手机端没有出现新笔记有一次电脑端正常显示 “Sync Complete”但手机端刷新后发现部分新笔记没有出现。我第一反应是冲突但打开冲突面板却什么都没有。后来发现问题出在插件的“Sync”范围设定。LiveSync 的“Vault Configuration”里有“Sync folders”的选项默认是同步整个 vault。但我当时给手机端单独设置了Excluded paths把Templates文件夹排除了而我的新笔记正好写在Templates/Inbox目录里。排查这个问题时我没有一开始就检查排除规则而是先查 CouchDB 的数据库里有没有对应文档。这里可以分享一个技巧在 Fauxton 里打开obsidian_livesync库按文档 ID 搜索笔记的路径。如果文档在数据库中已经存在说明同步链路没问题问题一定在客户端的过滤规则或者拉取环节。如果文档不存在再反向查电脑端的推送日志。5.4 排查链路四数据库损毁警告实际是插件升级带来的小概率事故第八天时手机端弹出了一个Database damaged警告。我当时有点慌担心数据全没了。后来查了 LiveSync 的 GitHub Issues发现遇到相同情况的人不少大多发生在插件自动升级之后。原因是新版本插件调整了数据库索引结构旧的索引文件与新版不兼容被误判为损坏。处理方法不复杂在插件设置里选择“Delete all local data and resync from CouchDB”等它重新从服务器拉取全量数据。因为服务器上有完整副本手机端的东西没有真正丢失只是重建了本地索引。整个过程耗时 20 多分钟但数据完好。这件事给我最大的教训是无论插件多么稳定服务器端一定要定期做 CouchDB 的物理文件备份。我用的是 NAS 自带的快照功能每天凌晨自动对 CouchDB 数据目录做一次快照操作简单但关键时刻能救命。5.5 其他容易踩的零碎问题如果你修改了 CouchDB 的用户密码记得同时重启容器否则部分连接池里的旧连接可能还会短暂使用旧密码造成间歇性401。观察日志时建议打开插件的“Show detailed log” 选项但日常使用时关掉否则日志文件会在一天内膨胀到几十 MB。多设备之间如果时区不一致需要注意 CouchDB 的复制冲突处理会怎么选“最新”建议所有设备都用自动时区不要手动指定城市。6. 两周后的结论这套方案我打算长期保留两周用下来obsidian-livesync 给我的最大感受是它把 Obsidian 同步这个“黑盒”打开了而且打开得非常彻底。我到现在还清楚记得第一次看到 Fauxton 里按秒更新的_changes日志时的踏实感每一篇笔记的每一次修改都清清楚楚地躺在自己的服务器上而不是某个看不见的云端黑盒里。和官方同步相比LiveSync 的代价显然是更高的配置门槛和一个需要持续维护的 CouchDB 服务。但如果你和我一样手上有 NAS 或者云服务器又希望数据完全可控这个门槛其实不算什么。把 Docker Compose 配置文件保存好日常需要运维的场景非常少我这两周里唯一主动操作服务器就是设置备份快照和升级了一次 CouchDB 镜像。在选型上我的最终建议是不要把 LiveSync 当成一个“开箱即用”的方案而要当成一个“数据自主”的方案。它适合愿意花一小时折腾的人也适合对隐私有较强需求的用户。如果你只想要最简单的同步官方订阅仍然是最省事的选择。最后分享一个小技巧如果你有多台设备建议在每台设备上启用 LiveSync 的“Device name”标识这样在冲突面板里能清楚看到每个版本来自哪台设备。我的命名规则是“PC-Windows”“MacBook”“Phone-iPhone”出现冲突时一眼就能判断哪边是最近编辑的。这个细节在团队协作、多设备并行的场景下真的能省掉不少判断时间。