Obsidian 用了两三年笔记越来越多手机、平板、公司电脑来回折腾同步方案试过网盘中转、Git 仓库、第三方同步服务各有各的难受网盘中转偶尔冲突Git 提交麻烦还得手动拉第三方服务要么收费要么数据过一手心里不踏实。后来换了Self-hosted LiveSync插件配自家服务器上的 CouchDB才算消停。这篇就把 Ubuntu 22.04 上从零搭建 CouchDB、再配好 Obsidian 多端实时同步的完整过程写出来包括踩过的坑和排查思路。1. 为什么选 CouchDB Self-hosted LiveSync 这套组合先说结论Self-hosted LiveSync是目前 Obsidian 自建同步方案里体验最接近官方同步的而 CouchDB 是它的最佳搭档。它不是文件同步而是数据库同步两者有本质区别。1.1 和网盘同步、Git 同步的本质差异网盘同步比如某同步盘同步整个 Obsidian 库文件夹走的是文件级同步。问题是 Obsidian 的库文件由一堆.md文本和.json配置组成任何一端改几个字网盘客户端就要整文件上传下载。文件多了、设备多了以后冲突频繁不说有时还会出现明明改了却不同步的怪问题得手动核对文件时间戳。Git 同步更麻烦。每次换设备得记得git pull改完得写提交信息、推送手机端还得装个 Git 客户端对只想安静写笔记的人来说负担太重。LiveSync 的思路完全不同它把整个 Obsidian 库拆成一条条细粒度的操作记录可以理解为哪次编辑改动了哪个文件的哪一段同步到 CouchDB 数据库。其他设备通过数据库的实时变更通知机制增量拉取这些操作记录并自动合并。所以它不需要整文件传输实时性、省流量、冲突处理都远超文件同步方案。1.2 CouchDB 在里面的角色和独特优势CouchDB 是个面向文档的 NoSQL 数据库和 LiveSync 配合有几个关键特性多主复制这是个核心能力。每台设备的 Obsidian 都可以视为一个主节点各自独立写入CouchDB 负责把各节点的写入合并起来。不像传统主从架构那样只有一个写入入口非常契合多台设备随时离线在线的场景。变更通知机制CouchDB 的_changes接口可以实时推送数据库变化LiveSync 正是通过它实现这边刚保存那边一两秒内就同步过来的效果。端到端加密LiveSync 会在本地用密码学方式加密笔记内容再存入 CouchDB。也就是说服务器上即使数据库被拖走对方看到的也只是密文这一点是自己搭同步服务最重要的安全感来源。提示如果你只是随便搭个服务玩玩可能觉得用 SQLite 或 MySQL 也行。但要做实时双向同步没有多主复制和变更推送这两个能力就得自己在应用层写一堆冲突合并逻辑用 CouchDB 是绕开这些复杂度的最省力路径。2. Ubuntu 22.04 安装 CouchDB从仓库配置到数据库创建我是在一台 2 核 2G 内存的云服务器上装的Ubuntu 22.04 LTS系统很干净。CouchDB 最新稳定版已经到了 3.3.x官方为 Debian/Ubuntu 提供了现成仓库不用编译源码省事。2.1 添加官方仓库并导入 GPG 密钥Ubuntu 自带的源里 CouchDB 版本偏老不建议用。直接走官方仓库命令如下# 安装依赖工具 sudo apt update sudo apt install -y curl gnupg ca-certificates # 导入 CouchDB 官方 GPG 密钥 curl -fsSL https://couchdb.apache.org/repo/keys.asc | sudo gpg --dearmor -o /usr/share/keyrings/couchdb-archive-keyring.gpg # 添加仓库源 echo deb [signed-by/usr/share/keyrings/couchdb-archive-keyring.gpg] https://apache.jfrog.io/artifactory/couchdb-deb/ jammy main | sudo tee /etc/apt/sources.list.d/couchdb.list注意jammy是 Ubuntu 22.04 的代号不要照抄其他教程里的focal20.04或bullseyeDebian 11不然会提示找不到包。2.2 安装过程的交互配置陷阱更新索引然后安装sudo apt update sudo apt install couchdb安装过程中会弹几个交互式配置界面这一步是很多新手卡住的地方。它会问三件事安装模式选standalone独立模式除非你明确知道要搭集群否则别选 clustered。监听地址默认是127.0.0.1会问你想不想改成0.0.0.0。这里建议暂时保持127.0.0.1等你配好 Nginx 反代之后再由 Nginx 对外提供访问不要让 CouchDB 直接裸奔在公网。管理员密码设一个强密码记好了。CouchDB 3.x 开始强制要求管理员账户设置后访问数据库都要带认证。如果你当时按太快没看清选项装完也可以通过重新配置来改不过更干净的做法是卸载重装sudo apt remove --purge couchdb再走一遍。2.3 验证安装状态和端口监听装完先看服务状态和端口sudo systemctl status couchdb sudo ss -lntp | grep 59845984是 CouchDB 默认端口。如果systemctl显示 activerunning且 127.0.0.1:5984 在监听说明安装成功。然后测一下 HTTP 接口能否正常响应认证请求curl -u admin:你的密码 http://127.0.0.1:5984/返回的 JSON 里能看到couchdb: Welcome和版本号就说明服务活了。此时建议顺手做一步安全加固绑定地址确认是127.0.0.1。CouchDB 绑定在 127.0.0.1 时外网无法直接访问 5984 端口只允许本机通过 Nginx 访问。这个配置在/opt/couchdb/etc/local.ini里[chttpd] bind_address 127.0.0.1 [chttpd_auth] require_valid_user truerequire_valid_user true意味着所有请求都要走认证不开放匿名访问配合后面的反向代理配置更稳妥。2.4 创建专用数据库和用户用 curl 操作 CouchDB 的 REST 接口创建两个数据库一个存数据一个存配置# 创建两个数据库 curl -u admin:你的密码 -X PUT http://127.0.0.1:5984/obsidian-livesync-data curl -u admin:你的密码 -X PUT http://127.0.0.1:5984/obsidian-livesync-config数据库名可以自定义但建议别用默认的couchdb这些太通用的名字避免和其他服务混淆。然后创建一个专门给同步用的受限用户不要拿着管理员账号直接给 Obsidian 用curl -u admin:你的密码 -X PUT http://127.0.0.1:5984/_users/org.couchdb.user:syncuser \ -H Content-Type: application/json \ -d {name:syncuser,password:一个单独的强密码,roles:[],type:user}最后给这个用户分配两个数据库的读写权限# 对两个数据库设置安全对象允许 syncuser 读写 curl -u admin:你的密码 -X PUT http://127.0.0.1:5984/obsidian-livesync-data/_security \ -H Content-Type: application/json \ -d {admins:{names:[],roles:[]},members:{names:[syncuser],roles:[]}} curl -u admin:你的密码 -X PUT http://127.0.0.1:5984/obsidian-livesync-config/_security \ -H Content-Type: application/json \ -d {admins:{names:[],roles:[]},members:{names:[syncuser],roles:[]}}提示为什么不直接用 admin 账号因为 Obsidian 客户端的配置里会保存数据库地址和账号密码万一哪台设备失窃或者插件配置泄露受限用户最多只能读写同步相关的两个库动不了 CouchDB 全局配置和管理接口攻击面小得多。3. 用 Nginx 反向代理 HTTPS 让 CouchDB 安全暴露给各端CouchDB 默认走 HTTP数据在网络上是明文传输的。虽然 LiveSync 有端到端加密但地址、用户名这些元信息还是不要裸奔。更重要的是LiveSync 插件以及 PWA 版在非 HTTPS 环境下会有很多功能受限。所以必须用 Nginx 反代 Lets Encrypt 证书把它包成 HTTPS 服务。3.1 为什么需要 Nginx 而不直接改 CouchDB 的 SSLCouchDB 本身也支持配置 HTTPS理论上可以直出但我仍然建议套一层 Nginx原因有几点CouchDB 的 TLS 配置相对繁琐而且证书续期后要重启服务才行。Nginx 可以顺带处理 WebSocket 支持LiveSync 实时推送会用到后面细说、请求日志、限速等其他维度。后面即使 CouchDB 换机器、换版本只要 Nginx 反代地址不变Obsidian 端就不用做任何改动。3.2 安装 Nginx 并申请证书sudo apt install -y nginx sudo apt install -y certbot python3-certbot-nginx证书申请需要域名我用自己的一个子域名假定是sync.example.com解析到这台服务器 IP。然后执行sudo certbot --nginx -d sync.example.comCertbot 会自动做证书签发和 Nginx 配置改写。如果申请失败通常是 DNS 解析还没生效等几分钟再试不要反复执行。3.3 Nginx 配置要点反向代理和 WebSocketCertbot 生成的基础配置里需要手动改一下 location 块。编辑/etc/nginx/sites-available/sync.example.com加一段server { listen 443 ssl; server_name sync.example.com; ssl_certificate /etc/letsencrypt/live/sync.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/sync.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:5984; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket 协议头 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; # 超时调大避免长连接被莫名断开 proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }校验配置并重载sudo nginx -t sudo systemctl reload nginx提示里面proxy_http_version 1.1和Upgrade头是给 WebSocket 用的。CouchDB 的_changes?feedcontinuous长连接特性依赖这个机制少了这两行LiveSync 的实时推送会变成过一会儿手动拉一次的模式反应速度差很多。3.4 验证 HTTPS 端是否正常工作curl -u syncuser:密码 https://sync.example.com/obsidian-livesync-data能返回一个包含db_name的 JSON 就说明反代成功。到这里CouchDB 这侧的基础设施全部就绪。4. Obsidian 端配置 Self-hosted LiveSync从安装到首次同步插件全名是Self-hosted LiveSync社区插件里直接搜。它支持桌面端Windows、macOS、Linux和移动端Android、iOS。配置路径几乎一模一样区别只是移动端输入 URL 时注意别被自动补全坑了。4.1 安装插件并打开配置界面在 Obsidian 里打开设置 - 第三方插件 - 社区插件关闭安全模式点浏览搜索Self-hosted LiveSync安装后启用。左侧栏会出现一个带插头图标的按钮点击就能进入配置面板。面板内容很多但真正需要手动配的就六个字段配置项填写内容URIhttps://sync.example.com/obsidian-livesync-data用户名syncuser密码你给 syncuser 设的密码数据库名称保持默认即可插件自动识别 URI 里的库名加密密码首次设置时自己生成一个或点 Generate配置数据库 URIhttps://sync.example.com/obsidian-livesync-config其中加密密码是用于端到端加密的独立密码和数据库账号密码完全无关。一旦启用加密切记自己备份好这个加密密码丢了等于所有笔记永久无法解密没有找回途径。4.2 首次同步用小库试水而不是直接开干第一次同步建议这样操作先在主设备上建一个测试库里面放几个几 KB 的小笔记配好插件后点击 Check database configuration 验证连接然后直接开始同步。确认改动能在另一台设备上实时出现后再逐步把真实笔记库整个同步过去。因为首次全量同步会创建索引、建立文档映射如果某台设备上有成千上万个文件小内存的服务器可能会卡顿一段时间。用小库试水可以先把流程跑通避免把问题混在一起排查。注意Obsidian 里的多个笔记库Vault默认会使用同一个 CouchDB 数据库。如果你在同一个服务器上同步两个完全不同的 Vault最好为每个 Vault 建独立的 CouchDB 数据库。不要共用一个库否则会出现诡异的互相覆盖问题。4.3 推荐的关键开关设置配置面板里有几个选项我看着默认值不顺眼按自己的使用习惯做了调整供参考Allow self-signed certificate如果你没走 Lets Encrypt 而是自签证书得打开这个否则握手直接被掐断。但自签证书的浏览器/客户端兼容性问题一堆不推荐长期使用。Sync on save保存时同步保持开启。这就是实时感的来源每次 CtrlS 保存后立即推送到其他设备。Periodic sync interval定期同步间隔我设成 5 分钟。这个是自己多加的一道保险防止某些情况下实时推送通道断开导致漏同步。Conflict detection冲突检测建议保持默认的use db doc changes。真出现冲突时插件会在文件旁边生成冲突副本而不是悄悄覆盖。5. 实测中的高频问题证书校验失败、同步回环与冲突处理跑通只是第一步日常用起来才会遇到真正磨人的问题。这里列几个我遇到过的、概率极高的状况附排查链路免得你到时候对着报错一头雾水。5.1 Error: self-signed certificate 或证书校验失败表现桌面端配置完成后点测试连接蘑菇头提示SSL certificate problem。我当时的排查过程是这样的第一步先用浏览器打开https://sync.example.com/obsidian-livesync-data。浏览器能正常访问看到 JSON说明证书链没问题。再用openssl s_client -connect sync.example.com:443 -servername sync.example.com /dev/null检查完整证书链确认证书确实是给这个域名签发的而不是中间层漏配。结果发现问题出在 Obsidian 端检测到系统代理相关或者本地时钟不准。CouchDB 和 Nginx 这层没问题是某台测试机上系统时间慢了 3 分钟TLS 握手把时间差视为潜在重放攻击直接拒绝。如果你也遇到类似证书类报错优先排查这三点系统时间是否准确、证书链是否完整、域名是否匹配。顺序不要乱时间问题最常见。5.2 同步出现无限回环A 设备改一处B 设备改回再来回打架LiveSync 一个很反直觉的坑同步本身会触发本地文件变更事件如果配置不当插件会把从数据库同步回来的内容又当成本地新修改再推回数据库形成死循环。排查路径是确认插件版本是最新版早期版本确实有过回环 bug。在能出现回环的设备上临时关掉插件观察数据库里的_changes是否还在持续产生数据。如果停止了说明问题出在这台设备的插件实例上。重新配置时注意插件文档里提到的 Ignore certain folders/files忽略特定文件配置。我和几个朋友踩过有人把一个缓存文件夹放在 Vault 里没忽略每次同步回来缓存变化又触发上传回环不断。解决后顺手做了一次重新扫描本地文件的操作回环就彻底消停了。5.3 移动端后台同步失效锁屏就断连手机上 Obsidian 不像电脑能始终保持前台运行安卓尤其激进地杀后台进程。LiveSync 作为 Obsidian 插件一旦 Obsidian 进程被系统回收同步自然中断。我的做法是安卓那边在系统设置里把 Obsidian 设为不受电池优化限制并允许后台自启动。iOS 上好一点但也要注意 Obsidian 的通知权限不能完全关掉否则系统也会视为低活跃应用。如果实在频繁被杀退而求其次把定期同步间隔调小比如 1 分钟至少每次打开 App 后很快就能拉到最新内容。实测下来这个折中方案体验也很接近实时同步了。5.4 数据库体积膨胀你以为存的是文本其实存了一堆历史CouchDB 存储的是文档变更历史每次修改都生成新版本文档所以数据库体积增长比想象中快。一个 300MB 的纯 Markdown 库跑两三个月数据库可能膨胀到 1.5GB 以上原因就是历史版本的累积。我用定时压缩和清理机制来控制体积。CouchDB 自带一个清理端点可以针对过期修订做处理但需要谨慎使用别误删有效数据。个人更推荐用插件自带的 Maintenance 功能定期执行数据库压缩Compaction这和 CouchDB 本身的压缩语义对应。大小降下来之后备份和恢复都轻松很多。提示在删除大量笔记后立即做一次压缩效果最明显。因为被删除文档的历史修订还占着空间压缩能真正把空间还回来。6. 备份与恢复自建服务最容易被忽视的最后一环自建服务的最大悖论是以为自己掌控了数据结果服务器一宕机才发现所有笔记都在上面从来没备份过。这部分讲清楚我使用的备份策略比前面的安装配置更值钱。6.1 CouchDB 两种备份思路对比CouchDB 备份有两条路快照文件备份和_replicate远程复制。我试了两种结论如下方式优点缺点适用场景直接备份数据目录简单恢复快必须停服或做一致快照否则数据可能不一致单机小规模部署_replicate复制到另一个数据库/机器在线完成不中断服务恢复时要注意目标库状态初次复制耗时较长长期稳定备份我倾向的方案是每天用 cron 触发_replicate把两个库复制到同机一个备份库里每周再把备份库的数据目录整体打包上传到对象存储。双保险一个负责快速恢复一个负责跨机房容灾。实际执行的复制命令示意curl -u syncuser:密码 -X POST https://sync.example.com/_replicate \ -H Content-Type: application/json \ -d { source: https://syncuser:密码127.0.0.1:5984/obsidian-livesync-data, target: http://127.0.0.1:5984/backup-obsidian-livesync-data }6.2 恢复演练比备份了更重要只备份不演练等于没备份。我吃过一次亏某天服务器磁盘故障我胸有成竹地去恢复结果发现备份库因为磁盘空间不足早就悄悄写失败了cron 还继续跑着报错。所以我的建议是每两个月至少做一次从备份恢复到临时目录的演练。操作不难恢复一个 CouchDB 数据库然后用 Obsidian 连上去看笔记是否完整可读。整个流程走一遍你才知道备份链路里的凭据、权限、空间约束是否都还正常。这个习惯帮我多次避免灾难。7. 从单机部署到可维护状态运维层面的几个细节服务搭完能跑只是起点真正长时间稳定运行还需要解决几个运维层面的琐碎问题。7.1 日志轮转和磁盘监控CouchDB 默认日志不轮转长期跑下来/opt/couchdb/var/log可能会吃掉大量磁盘。我的处理是直接配置log4js的轮转策略或者用logrotate兜底。ubuntu 上装了 CouchDB 之后默认会带一个 logrotate 配置验证一下是否生效即可ls /etc/logrotate.d/couchdb如果有这个文件基本就不用管了。磁盘监控我是在 crontab 里加了一个简单检查空间低于 10% 时发提醒通知。7.2 系统自动更新与停服窗口规划Ubuntu 的自动安全更新建议开着但 CouchDB 的版本升级要挑时间。我的经验是升级前先看https://docs.couchdb.org/en/stable/whatsnew/index.html的更新日志如果涉及存储引擎或复制协议的大改就等周末没人用笔记的时候再操作。升级前先备份一次数据用前面说的 replicate 方式升级后立即跑一遍 Obsidian 同步确认各端都正常。7.3 多区域多设备同步的表现差异如果设备分散在不同地区连接你服务器的延迟会直接影响同步实时感。我做过一个测试同一篇含图片的笔记在相距较远的两个城市之间同步纯文本内容 1 秒内能到带 5MB 图片时大概需要 5 秒左右这取决于两端网络带宽。对于笔记场景完全可以接受但如果你的 Vault 里有大量几十 MB 的附件实时同步会出现明显的等待需要权衡是否把所有附件都放进 Obsidian 库。8. 写在最后这套方案值不值得折腾说实话如果你只是想在手机和电脑之间同步几十个笔记文件官方同步服务已经够省心没必要自己搭。但如果你对数据隐私有要求、不想把笔记内容交给第三方、或者已经有多台设备且长期依赖 Obsidian 工作那CouchDB Self-hosted LiveSync这套方案是很值得投入时间的选择。它一次搭建长期受益日常使用几乎没有存在感——打开 Obsidian 就是最新内容和官方同步的体验差距很小。我在实际使用中还有一个习惯每隔一段时间会删掉插件重新配置一遍目的不是找麻烦而是保持对整个链路服务器、证书、数据库权限、插件配置的熟悉度防止哪天真出问题时连配置项都忘光了。如果你也想搭这套方案不要急着在自己的主力笔记库上操作先用小库跑通再逐步迁移。这个顺序看起来慢实际是最快的路径。