企业官网建设流程全解析

如果你玩 Obsidian 超过三个月，大概率经历过同步这个“老大难”问题的反复折磨。官方同步省心但价格不低，Git 同步总有一种“随时要手动救场”的不安，WebDAV 方案又时不时给我冒出一个隐藏字符冲突。两周前，我把主力笔记库切到了 vrtmrz 维护的 obsidian-livesync，后端用自托管 CouchDB，手机端、电脑端、平板端三端一起跑。今天这篇不吹不黑，把这两周里的部署过程、参数调优、踩坑记录、实测数据全部摆出来，顺便说说我为什么最终保留它作为唯一的 Obsidian 同步方案。

1. 折腾同步的两周：为什么我从官方同步转投自托管 LiveSync

1.1 官方同步为什么被我排除

Obsidian 官方同步其实做得并不差，端到端加密、版本历史、选择性同步这些都有，我最初也用了三个月。真正让我放弃的不是功能，而是两个很现实的问题。

第一是费用。官方同步按年订阅，对于我这种同时维护三个笔记库、里面还塞了大量 PDF 附件和图片的人来说，容量需求一上去，价格就变得不太划算。第二是自由度。官方同步的后端对你完全封闭，出了冲突只能靠插件自己的逻辑处理，你无法干预底层数据。我这个人对数据有很强的掌控欲，笔记库里有五年积累的素材，一旦同步逻辑出错，连回滚都只能依赖官方提供的版本历史，这种“数据在别人手里”的感觉始终让我不踏实。

所以从去年开始，我就在寻找一种自托管、数据完全在自己手上、同时同步延迟又足够低的方案。

1.2 我用过的替代方案，以及为什么最终选了 LiveSync

在 obsidian-livesync 之前，我先试了 Obsidian Git、Remotely Save、Self-hosted LiveSync 的早期版本，各有一番体验。这里直接列个对比表，省得大家重复踩我走过的路。

Git 方案我的感受是“适合做备份，不适合做主力”，因为每次推送都要等几十秒，手机端想要快速记一条闪念，根本没有耐心等着操作完。Remotely Save 上手很快，但遇到过两次双端同时修改后，其中一边的内容直接变成了旧版本，而且没有可靠的恢复路径。

obsidian-livesync 最吸引我的地方，是它使用 CouchDB 的_changes机制做双向复制。它的插件会把本地所有改动实时推送给 CouchDB，同时监听 CouchDB 的变化，把其他设备的改动拉回本地。这个机制不依赖定时任务，而是即时触发，所以多端同步的延迟可以做到非常低。更关键的是，数据不经过任何第三方中转，服务器只有你自己能访问。

2. CouchDB 部署记录：从 Docker 命令到 HTTPS 反向代理的完整链路

2.1 CouchDB 版本选择：为什么我直接用 4.x

obsidian-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:password@couchdb.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，持续半小时也没变化。

我按照下面的顺序排查：

1. 先确认服务器端口通不通：在外网环境用telnet 你的域名 443测试是否通。
2. 再确认 CouchDB 是否活着：浏览器访问https://couchdb.example.com/_up，返回正常。
3. 用浏览器直接访问https://couchdb.example.com/obsidian_livesync并带上账号密码，返回数据正常，说明 CouchDB 本身没问题。
4. 最后回到插件设置页，发现 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”，出现冲突时一眼就能判断哪边是最近编辑的。这个细节在团队协作、多设备并行的场景下，真的能省掉不少判断时间。