Obsidian多端同步实战：自建LiveSync全流程配置指南

1. 为什么我最终选择了LiveSync，而不是靠iCloud或Git同步

先聊点实际的。玩Obsidian的人迟早会撞上“多端同步”这道墙，而且大概率会经历一段非常折腾的时期。我自己就是从U盘拷文件、网盘手动上传、Git仓库推送、iCloud同步一路走过来的，每换一种方案都会发现新痛点，直到最后认真把LiveSync插件调通，才觉得这东西终于能安稳用了。

简单说，Obsidian LiveSync是一个基于自建数据库的同步插件，核心逻辑是把你的笔记内容实时同步到你自己的服务端，再通过服务端把变更分发到手机、平板、另一台电脑等多个客户端。它解决的痛点是：极低延迟、无需手动提交、不怕文件冲突、全平台覆盖，最关键的是数据始终在你自己的服务器上，不依赖任何第三方笔记同步服务。

这篇东西适合谁看？如果你正在用或准备用Obsidian做知识库，而且你手里至少有一台服务器（云主机、VPS、家里NAS虚拟出来的Linux都行），同时又不想把笔记托管到别人的云盘上，那这篇配置记录应该能帮你省下大量试错时间。

我现在的实际环境是：主力Windows笔记本、一台常年开机的Linux服务器、iPhone和一部Android备用机，全部通过LiveSync实时同步同一个库，延迟基本在1秒以内。这篇文章我就按自己实际蹚过的路，把整个配置流程、踩过的坑、以及很多文档里根本没写明白的细节，从头到尾捋一遍。

2. 先搞清楚LiveSync的工作原理，否则后面全是黑盒操作

2.1 LiveSync不是加密网盘，也不是文件传输工具

很多人第一次看到LiveSync的介绍，会误以为它就是把Obsidian的库里文件同步到远端，像坚果云那样。其实不太一样。LiveSync的同步对象是“你的操作变更记录”，而不是简单的文件覆盖。

举个例子。你在桌面上改了一个笔记里的某一行字，保存之后，Obsidian会把这次改动生成一个包含具体修改路径和内容的变更事件。LiveSync插件会把这个事件实时推送到你在服务器上部署的同步服务端（默认是CouchDB），服务端再把事件广播给当前在线的其他设备。其他设备收到事件后，在自己本地把同样的修改应用一遍。

这意味着什么？意味着它几乎不产生“整个文件上传下载”的流量，同步的是变化量，所以速度快、流量小，而且天然支持多人同时编辑同一篇笔记而不产生传统意义上的覆盖冲突。这个机制很像代码里的增量同步，只是它作用在笔记文本上。

用生活类比的话，传统网盘同步像是每次你把整本笔记本复印一份送到另一个办公室；而LiveSync是每次你改一行字，就把这一行字用传真发给其他办公室，由对方自己贴到对应页面上。前者简单但笨重，后者轻快但需要所有办公室保持相同的笔记本底稿。

这正是LiveSync能在手机和电脑之间做到近乎实时同步的核心原因。但也正因为这种机制，它对服务端的稳定性、客户端本地库的初始化要求都很高。如果本地库一开始就不完整，或者服务端数据异常，后面同步时可能出现你意想不到的“幽灵修改”或“回滚”。

2.2 为什么方案选型：CouchDB + 自带Caddy，而不是MinIO或WebDAV

LiveSync的配置文件里，可选的同步服务端有不少，最常见的是CouchDB，也有人用MinIO对象存储或者支持WebDAV的网盘。我直接说结论：普通自建用户，优先选CouchDB。

原因有三点。第一，CouchDB天生就是为“多主复制”设计的数据库，它允许离线设备稍后重连时将本地变更合并上去，不会因为离线时间长了就判死或丢数据。第二，LiveSync对CouchDB的适配最完善，很多高级功能比如按前缀过滤同步、端到端加密、结构化导出备份，都与CouchDB深度绑定。第三，CouchDB的部署在Docker里非常成熟，内存占用也不算离谱，1GB内存的VPS完全可以跑得动。

我当时也试过用MinIO，因为它看起来像是“文件存储桶”，似乎更贴合笔记文件这种非结构化数据。但实际体验下来，MinIO在增量同步、变更侦测、冲突处理这些环节上都不如CouchDB顺滑，尤其在多端并发修改同一篇笔记的场景下，MinIO模式很容易产生文件版本分裂，最后还得手工合并，非常痛苦。

至于WebDAV方案，配置虽然最简单，但基本退化成“准实时同步”，而且对弱网环境的容忍度很低，手机锁屏后经常要很久才能触发同步。如果你对同步延迟不敏感，只求能备份，那WebDAV也够用；但如果你想像我一样，手机掏出来打开笔记时内容已经是最新状态，那还是要上CouchDB。

2.3 端到端加密一定要开，不开等于裸奔

LiveSync支持端到端加密，意思是在你的设备上把笔记内容加密后再传给服务端，服务端上存的是密文。即使服务器被入侵，甚至数据库被拖走，对方看到的也只是乱码，无法还原出你的笔记正文。

这里有个关键点：端到端加密的密钥是存在你本地的Obsidian配置里的，不是存在服务器上的。所以你每配置一台新设备，都需要把加密密码或者密钥文件导入进去。如果你忘了密码，服务器上所有密文都无法解密，等于笔记全丢，没有任何后门可走。

我在第一次配置时就踩过这个坑。当时为了省事，想着“反正是自己的服务器，不加密应该也没事”。后来服务器被扫描爆破过一次，虽然没造成实质影响，但那种“私人笔记可能被陌生人看过”的感觉非常难受。从那以后我把所有LiveSync同步的库都开了端到端加密，建议你也别省这一步。

另外开加密之后，同步的HTTP流量里不会出现明文的笔记内容，查日志也只能看到一堆密文块。这对于涉及个人日记、工作文档、账户信息的人来说，是刚需。

3. 配置前你要准备好的东西，以及服务端部署的全过程

3.1 服务器选型与基础环境要求

LiveSync对服务器性能要求其实不高。我用过最低配的机器是1核1G内存的小VPS，跑CouchDB加Caddy反代，平时内存占用大概在300MB上下，CPU几乎没有压力。但有两个硬性条件必须满足：一是服务器需要有公网IP，或者至少能被你的所有设备通过HTTPS访问到；二是你最好有一个域名，因为CouchDB走HTTPS会更省心，直接用IP也能配，但SSL证书的申请和管理会麻烦不少。

所以如果你手里已经有云服务器，直接在上面操作就行。还没有的话，买一台最便宜的入门VPS基本够用，地域选择上优先考虑离你主要活动区域近的节点，延迟会低一些，但说实话只要不是跨大洋，影响并不大。

系统方面，Debian 11/12或者Ubuntu 22.04/24.04 LTS都行。我习惯用Debian，因为更省内存。以下步骤默认你以root身份通过SSH登录服务器，并且已经装好了Docker和Docker Compose插件。如果还没装，一行命令的事，网上教程很多，这里不重复展开。

3.2 使用Docker Compose部署CouchDB与Caddy

LiveSync的官方文档其实推荐过几种部署方式，最简单的是用他们提供的脚本直接拉一个整合容器。但我个人更推荐用Docker Compose手工编排，原因很简单：你能明确知道每个容器是干什么的，升级和迁移时心里有底，不会出现“一键脚本装完却不知道数据存在哪”的局面。

我服务器上的docker-compose.yml结构大概是这样：

yaml复制version: "3.8"

services:
  couchdb:
    image: couchdb:3.3.3
    container_name: couchdb
    restart: always
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=你的高强度密码
    volumes:
      - ./couchdb-data:/opt/couchdb/data
    networks:
      - lsync

  caddy:
    image: caddy:2.8.4
    container_name: caddy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    environment:
      - DOMAIN=sync.example.com
      - ADMIN_USER=admin
      - ADMIN_PASSWORD=你的高强度密码
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy-data:/data
      - ./caddy-config:/config
    networks:
      - lsync

networks:
  lsync:
    driver: bridge

这里有两个细节值得注意。第一个是CouchDB的COUCHDB_USER和COUCHDB_PASSWORD环境变量，只有在容器第一次初始化数据目录时才会生效。如果你之后改了密码想通过环境变量更新，是没用的，必须进容器里用命令改。第二个是Caddy容器需要通过80和443端口对外服务，它负责自动申请和续期SSL证书，同时把sync.example.com的请求反代到couchdb容器的5984端口。

Caddyfile是另一个关键文件，我的是这样：

code复制sync.example.com {
    reverse_proxy couchdb:5984
}

就这两行。Caddy检测到域名后，会自动向证书机构申请HTTPS证书，整个过程不用你干预。第一次启动后等一两分钟，浏览器访问https://sync.example.com，如果能看到CouchDB返回的JSON欢迎页，说明服务端已经通了。

3.3 配置CouchDB数据库与权限

CouchDB服务启动后，不能直接用默认管理员账号连接LiveSync，因为LiveSync需要操作数据库，而且最好只给它一个权限受限的专用账号，避免插件配置错误时把整个数据库搞乱。

我的做法是，在服务器上用curl命令创建单独的用户，并赋予它管理LiveSync相关数据库的权限。实际执行时大致是：

bash复制curl -X PUT https://sync.example.com/_users/org.couchdb.user:lsync \
     -H "Content-Type: application/json" \
     -u admin:你的高强度密码 \
     -d '{"name": "lsync", "password": "lsync专用密码", "roles": [], "type": "user"}'

光创建用户还不够。LiveSync会自动创建以userdb-开头的数据库，比如userdb-xxxxxx，你需要给这个lsync用户赋予这些数据库的管理员权限。最简单粗暴但有效的办法是，在CouchDB的配置里设置数据库的security对象：

bash复制curl -X PUT https://sync.example.com/userdb-你的库哈希 \
     -u admin:你的高强度密码 \
     -H "Content-Type: application/json" \
     -d '{"admins": {"names": ["lsync"], "roles": []}, "members": {"names": ["lsync"], "roles": []}}'

这里说的“库哈希”其实就是LiveSync初始化时会生成的一串随机标识，你要么先在Obsidian里跑一遍初始化流程让它自动建库，要么在CouchDB的Fauxton界面里手动创建一个数据库再把名字填进去。

更省事的方案是：直接在Obsidian里配置LiveSync时填管理员账号，让插件自己完成建库授权。这样最简单，但安全上弱一些。我最终还是改成了专用账号授权的方式，宁可前期多几步，后面更安心。

4. Obsidian端配置LiveSync插件：从安装到第一台设备跑通

4.1 插件安装注意：这个插件不在默认社区列表的中文搜索里

Obsidian的社区插件列表里直接搜LiveSync是可以找到的，但安装时有两个常见问题：一是国内网络访问GitHub Releases经常失败，表现为插件下载到一半就没反应；二是Obsidian中文用户很容易把它和另一个叫“Self-hosted LiveSync”的插件搞混，其实后者才是要装的完整版。

如果你网络环境不好，下载失败，我的经验是先从GitHub Release页面手动下载zip包，然后解压到Obsidian库的.obsidian/plugins/obsidian-livesync目录下，重启Obsidian即可。注意解压后的目录结构必须是插件主文件和main.js、manifest.json在一个层级，放错了Obsidian会识别不了。

插件安装成功后在“已安装插件”列表里能看到它的开关。启用后，左侧栏会出现一个带旋转箭头的小图标，点开就是LiveSync的配置面板。整个配置面板的英文选项对新手极其不友好，我第一次打开时完全不知道先点哪里，后来才摸清操作顺序。

4.2 第一台设备配置：URI、数据库名和加密口令一个都不能少

在Obsidian里配置LiveSync的关键路径是：设置 → Community plugins → Self-hosted LiveSync → Settings。打开面板后，它有几个大分区，其中“Configure”和“Encryption”是你必须操作的。

如果你是全新配置，选择“Setup”选项卡，里面会让你选“Self-hosted LiveSync”的类型，以及填写服务端地址。我实际操作时填的内容大致是：

• URI：https://sync.example.com
• 用户名：lsync
• 密码：lsync专用密码
• 数据库名：留空或填你手动创建的库名（比如mylib）

这里有一个非常容易被忽略的坑：URI末尾不要带斜杠，不要加/couchdb这类的路径前缀，除非你确实在Caddy里做了子路径转发。填错了会出现连接成功但无法同步的情况，因为插件请求的路径和CouchDB实际暴露的路径对不上。

填完基础连接后，插件会有一个“Test Connection”按钮，建议先点一下。如果显示连接成功，再进入下一步。如果你打算开端到端加密，在“Encryption”分栏里设置一个独立的加密密码，和CouchDB账号密码分开，别用同一个。这个密码之后所有设备都要用，必须记牢，最好放在密码管理器里。

4.3 初始化同步：别急着让所有设备一起连

第一台设备配置完后，插件的状态会显示“Connected”，但这只是说它能访问CouchDB了，并不代表你的笔记已经传上去了。你需要在配置面板里找到“Database Setup”或“Create Database”的按钮，点击后插件会往服务器上创建对应的数据库，并询问你是否要上传本地所有笔记作为初始数据。

这里我强烈建议第一次先只让一台设备执行“上传所有本地笔记”，其他设备先别开LiveSync，等这台传完、第二台设备再从空库拉取。如果你一开始就让两台设备同时同步，其中一台本地库片缺失，可能引发大范围的字段级覆盖，修复起来异常麻烦。

我当时犯的错误是直接把主力电脑和手机同时打开了同步，结果手机端因为第一次同步需要拉全量数据，网络又不稳定，数据库里的一部分文档处于半同步状态，之后电脑上每次修改都会触发冲突，问题持续了好几天才彻底理顺。后来我把手机端从库里移除，重新初始化，让它从空库拉一遍全量，才恢复正常。

初始化上传的速度取决于你的网络上行带宽和服务器的下行带宽。几GB的库可能要花十几分钟，期间Obsidian界面可能会有点卡，属正常现象。传输完成后，你在CouchDB的Fauxton界面里能看到数据库的文档数量和本地笔记数量对得上。

5. 多端配置的完整流程：从第二台设备加入同步

5.1 手机端配置前，你需要导出并迁移一个“同步配置”

第二台设备加入LiveSync同步，不能只凭账号密码登录，还需要把第一台设备的加密配置导过去。这一步很多教程轻描淡写带过，但恰恰是关键。

在第一台设备的LiveSync设置里，有一个“Configuration”相关按钮，可以导出当前同步配置。Obsidian会生成一段很长的JSON文本或URI，里面包含服务器地址、加密盐、加密算法参数等信息。你需要通过安全渠道把它发送到新设备上。

我推荐的方式是用系统自带的加密压缩包传输，或者在局域网里直接传输这段文本。千万不要直接截图发到聊天软件里，因为截图里可能完整显示服务器地址和敏感配置，甚至加密参数泄露会让你的端到端加密防护形同虚设。

新设备收到配置后，先在Obsidian里安装LiveSync插件，打开设置面板，找到“Import Configuration”功能，粘贴那段URI，插件会自动填充服务器地址和加密参数。接着再手动输入CouchDB账号密码和加密密码，点连接。

5.2 新设备全量拉取与常见的前期状态检查

新设备连接成功后，LiveSync默认会提示你进行全量拉取。这个阶段手机端进程会持续跑一段时间的网络请求，具体耗时取决于库大小和网络质量。我的经验是10GB左右的库，在5G网络下大约需要15到20分钟，期间手机会发热，这是正常现象，不要锁屏切换应用太频繁，否则可能被系统挂起。

全量拉取完成后，你在新设备上打开某篇笔记，检查内容和电脑端是否一致。此时重点看三个东西：附件图片是否都在、代码块是否完整、标签和双链是否能跳转。如果附件缺失，说明附件同步配置没打开，或者CouchDB中附件存储的路径有问题。如果标签双链异常，多半是本地索引还没建完，等几分钟再尝试。

比较坑的是Obsidian移动端默认会把部分插件功能裁剪，LiveSync在手机上偶尔表现不稳定。我实测下来，Android端的Obsidian对LiveSync支持还算可以，iOS端偶尔会有后台同步不及时的问题，需要把Obsidian App在系统设置里设置为允许后台刷新。如果你用的是国行手机，还要额外关闭电池优化白名单限制，否则锁屏一段时间后同步会完全断掉，打开App才恢复。

6. 同步冲突排查与数据一致性保障方案

6.1 冲突文件是怎么产生的，以及如何尽量避免

LiveSync基于CouchDB的冲突处理机制已经解决了一部分并发问题，但并不是零冲突。通常冲突发生在两台设备都在离线状态修改了同一个文件的同一行，并且没有哪一方能看到另一方的最新版本，等双方重新联网后，CouchDB就会把两个版本都保留下来。

在Obsidian里表现为：笔记内容旁边多了一个“conflicted copy”的副本文件，或者正文底部出现分节的分裂视图。处理起来不复杂，但需要人工判断哪一版是想要的，再合并或删除另一版。

要降低冲突频率，有几个实操建议。首先是不要在同一时间段在多个设备上编辑同一篇笔记，至少不同设备间隔5秒以上。其次是尽量保持设备在线时间，别把手机一锁屏就断网半个小时又突然回来。最后是高强度写作场景，尽量固定在主力设备上，手机端只做查阅和速记，减少并发修改的可能性。

6.2 我的排查方法论：从CouchDB日志到本地配置文件

遇到同步异常，第一步不是去问群友，而是先看CouchDB的容器日志。

bash复制docker logs couchdb --tail 100

如果日志里出现大量401或403错误，基本说明账号密码或权限配置有问题。如果出现超时或连接重置，那就要检查防火墙、Caddy配置以及服务器带宽是否跑满。

日志没问题，再到Obsidian端排查。你可以打开LiveSync的调试日志开关，它会把每次同步的请求和响应记录在开发者控制台。你需要按Ctrl+Shift+I打开开发者工具，切到Console面板，观察是否有红色的同步错误。

有一回我碰到“新手机端一直转圈无法完成全量拉取”，排查后发现问题出在网络环境上——手机和服务器之间的HTTPS握手被某个中间网络设备干扰了。换到另一个网络后，同步立刻恢复正常。这种问题用Wireshark抓包都不一定看得出来，反而是直接换网络环境验证最有效。

6.3 定期备份的终极防线：CouchDB的Dump思路

有了LiveSync不代表你可以不做备份。服务器硬盘损坏、CouchDB数据目录误删、勒索病毒入侵，哪一样都可能让你多年心血化为乌有。所以我在服务器上用crontab每天夜里对CouchDB数据库做一次完整导出，把备份文件保留最近14天。

具体做法是使用CouchDB的备份工具couchdb-dump，或者直接利用CouchDB的HTTP接口导出所有文档。我最开始用curl写脚本逐条导出，效率很低，后来改成用现成的容器镜像做定时备份，稳了很多。

备份脚本大致逻辑：

• 凌晨3点执行docker exec命令，通过couchdb-dump工具将整个数据库导出为JSON文件。
• 将JSON文件压缩打包，上传到另一台服务器或者对象存储服务。
• 清理本地超过14天的备份文件。

这个备份方案已经跑了大半年，没有出过问题。真要遇到服务器彻底挂掉的情况，我可以随时在新的CouchDB实例里导入最新备份，再让所有Obsidian客户端重新连接，最多损失昨晚之后少量增量同步数据，而这部分在每台本地客户端上仍有残留，可以用LiveSync的“verify”功能找回一部分。

7. LiveSync高频疑问与性能优化建议汇总

7.1 为什么我手机上的Obsidian始终无法连接服务器

典型原因有三个：一是服务器防火墙没放行443端口；二是你填写的URI中域名解析不到服务器IP；三是Caddy没有成功申请SSL证书，导致HTTPS握手失败。

最快的验证方法是，在手机浏览器里直接访问你的https://sync.example.com，如果浏览器都打不开，那就不是Obsidian的问题，而是服务器或DNS的问题。如果浏览器能打开CouchDB的欢迎页，但Obsidian连不上，那问题多半出在CouchDB账号权限或Obsidian插件配置上。

7.2 同步速度慢，除了升级服务器还能做什么

影响同步速度的因素大致有三点：单次变更文件大小、服务端地理位置和CouchDB的索引批量写入性能。

升级服务器带宽当然一劳永逸，但很多时候瓶颈在CouchDB的配置。比如CouchDB默认的批量文档提交大小可能不适合大附件场景，我调整了一下CouchDB配置里的最大批量文档数后，同步速度有明显提升。另外如果你的笔记库中大量插入超大图片附件，LiveSync原生的直接同步附件方式会消耗巨大流量，不如将图片附件整体迁移到对象存储，在Obsidian中用附件路径插件引用外部链接。

我自己目前的做法是：文字笔记全部走LiveSync实时同步，超过5MB的多媒体资源放进独立的对象存储桶里，并在笔记中用固定路径区分。这样库体积稳定了，同步速度也快了不少。

7.3 关于Obsidian的收费争议，LiveSync是不是变相替代品

Obsidian本身对个人用户免费，官方也提供收费的Sync服务。有些用户关心的“Obsidian收费”问题，其实是指官方同步服务需要订阅费用。LiveSync这套自建方案的直接价值就是省下这笔订阅费，同时换来更大的数据自主权。

但客观讲，LiveSync的学习成本和维护成本远高于官方Sync。官方Sync几乎零配置，开箱即用；LiveSync要求你懂一点Linux、懂一点Docker、能承受偶尔自己排查故障的麻烦。如果你时间宝贵又不想折腾，订阅官方Sync是完全合理的。如果你享受折腾、重视数据隐私、或者本来就有闲置服务器，那LiveSync绝对值得掌握。

我的态度一直是：工具服务于人，不要在省几块钱和维护成本之间反复横跳。选择适合自己精力的方案，别把笔记系统本身变成需要长期运维的项目。不过对于知识管理重度用户和私有化爱好者来说，LiveSync所提供的自主性和可扩展性，确实很难被替代。

8. 最后的个人经验总结

我从开始折腾LiveSync到现在，至少重新部署过三次，每次都在不同环节踩到新坑。但稳定运行之后的收益非常明显：手机端起笔记时内容永远是最新的，出差在地铁上写的内容回到家打开电脑直接接着改，再也不用记着“今晚记得手动同步一下”这种事。

如果让我给准备上手的朋友一条最核心的建议，那就是：第一次配置时不要追求一步到位。先把服务端CouchDB跑起来，把主力电脑和手机连通，稳定用一周后，再考虑是否开加密、是否优化附件存储方案。一上来就想把所有功能全配齐，只会让你在初期就被各种问题劝退。

另外，任何第三方自建同步方案都需要维护觉悟。偶尔检查一下服务器磁盘、看看CouchDB的日志、确保每天的备份任务正常执行，这些操作累计起来每周不会超过十分钟，却能让你在真正遇到问题时从容应对。

LiveSync这套东西不完美，但它给Obsidian高玩带来的自由度，是官方Sync和各类网盘都给不了的。希望这篇配置记录能帮你少走点我当年走过的弯路，让你也能早日拥有一个多端实时同步、数据握在自己手里的知识库。