企业官网建设流程全解析

用了两周的 obsidian-livesync，我算是把这个插件从配置到日常使用完整走了一遍。先说结论：如果你愿意花一个下午折腾，它能给你一套完全自控、实时增量同步、且不依赖任何第三方云盘的 Obsidian 同步方案。这个项目在 GitHub 上叫 vrtmrz/obsidian-livesync，核心思路就是自己搭一个 CouchDB 数据库，让 Obsidian 通过插件直接和数据库同步。相比官方同步服务、iCloud、Git 这类方案，它的优势在于数据全程掌握在自己手里，同步是秒级的，而且离线也能正常写作，网络恢复后自动合并。

这篇文章我打算把这两周的完整体验写出来，包括为什么选它、底层到底怎么工作、从零部署的每一步、实际用下来的感受，以及我踩过的坑。如果你是 Obsidian 重度用户、喜欢自托管、或者对笔记数据隐私比较敏感，这篇内容应该能帮你少走不少弯路。

1. 为什么我会盯上 obsidian-livesync

1.1 官方同步之外的现实选择

我的 Obsidian 库目前有 2400 多篇笔记，包含大量截图和 PDF 附件，总体积接近 1.6GB。之前一直用官方 Sync 服务，每月付费，同步倒是省心，但有几个问题一直让我不太舒服：数据全部放在别人服务器上，虽然官方说有加密，但密钥掌握在谁手里我并不知道；另外就是国内网络环境下，官方同步服务的延迟时好时坏，经常手机上改完一条笔记，回到电脑前要等好几秒才反应过来。

中间也试过 iCloud 同步方案，Windows 端体验实在一般，偶尔还会出现文件冲突副本，文件名后面多一串乱码。Git 方案我也用过一阵子，适合有版本管理需求的场景，但实时性基本谈不上，每次同步都要手动 commit、push，手机端操作更是麻烦，而且 Obsidian 的.obsidian配置目录经常被卷入冲突里，处理起来让人头大。

所以当我看到 obsidian-livesync 这个项目时，第一反应是：这玩意能不能替代官方 Sync？仔细看完文档后我确认，它走的不是“把整个笔记库塞进云盘”的老路，而是用 CouchDB 作为后端存储，通过插件在客户端和数据库之间做增量同步。这意味着每次只传输变化的部分，不是整个文件，同步效率天然比云盘方案高一个量级。

1.2 我想要的同步边界：隐私、速度、可控性

对我来说，一个理想的同步方案需要满足三个条件。第一是隐私，笔记是个人思维的沉淀，里面有日记、想法、未公开的项目记录，我不希望它们经过任何我不信任的第三方服务。第二是速度，日常使用中同步应该是隐形的，不应该每次切换设备都能感觉到“哦，它还在同步”。第三是可控性，出了问题我能自己排查，数据备份我能自己决定策略，而不是只能等官方修复。

obsidian-livesync 恰好踩中了这三点。它让我自己选择数据库部署在哪里，数据在传输过程中还可以开启端到端加密，即使数据库被别人拿到，没有密钥也读不出内容。速度方面，因为服务器位置和配置都是自己控制，只要带宽和硬件不太差，同步延迟可以做到一两秒内。这种可控感是任何闭源服务都给不了的。

2. 部署前必须搞清楚的几个核心概念

2.1 这套同步机制到底是怎么转起来的

obsidian-livesync 的本质，可以理解为“Obsidian 客户端与 CouchDB 数据库之间的双向实时复制”。CouchDB 是一种面向文档的 NoSQL 数据库，它的设计目标之一就是多主复制。什么意思？就是你在任意一台设备上做的修改，都会同步给其他所有设备，不存在“谁是主服务器”的概念，任何一台设备离线了，其他设备照样工作。

Livesync 插件做的事情是监听本地 Obsidian 库里的文件变化，把变化的内容打包成数据库文档，通过 HTTP 请求发给 CouchDB。CouchDB 会把文档广播给所有订阅了这个数据库的客户端。反过来，当其他设备修改了同一篇笔记，CouchDB 也会把更新推送到你当前这台设备的插件里，插件再把内容写回本地文件。

所以整个链路里，CouchDB 扮演的是“中转站 + 存储中心”的角色。它不关心你的笔记是不是 Markdown 文件，它只处理一个个 JSON 文档。Livesync 插件负责把 Markdown 文件映射成 JSON 文档，同步完成后再把 JSON 还原成 Markdown。这就是为什么它能做到增量同步，因为它同步的粒度是“文档”，不是“文件”。

2.2 为什么选择 CouchDB，而不是 MySQL、Redis 或直接同步文件

这个问题我一开始也没想明白，后来查了一些资料才理解。如果只把 CouchDB 当作一个简单的 KV 存储，那确实用 MySQL、PostgreSQL 也能做。但 CouchDB 真正的核心能力是MVCC（多版本并发控制）和冲突处理。每一份文档都有_rev版本号，每次修改都会生成新版本，数据库保留历史版本。当两台设备同时修改同一篇笔记时，CouchDB 不会直接覆盖，而是把其中一个版本标记为冲突，交给客户端去解决。

这种设计对“笔记同步”这种场景非常合适。因为 Obsidian 用户经常会在手机和电脑之间交替工作，冲突是大概率事件。如果用传统的文件同步方案，两个设备同时改一个文件，后写入的一方会直接覆盖先写入的内容，数据就丢了。而 CouchDB 至少会把两个版本都保留下来，让用户有机会选择保留哪个。

Redis 之类的内存型数据库显然不合适，笔记数据需要持久化，不能重启就丢。Livesync 之所以绑定 CouchDB，还有一个原因是它有_changes接口，客户端可以持续监听数据库变化，实现真正的实时推送，不需要轮询或者 WebSocket 自定义协议，省去了大量协议设计工作。

2.3 部署一套环境需要准备哪些组件

完整跑起来需要四块东西：CouchDB 数据库服务、反向代理（用于 HTTPS）、Obsidian 客户端插件、以及可选的对象存储（用于存放大型附件）。

CouchDB 推荐直接上 Docker，省去手动管理依赖的麻烦。反向代理我用了 Caddy，因为它能自动申请和续期 HTTPS 证书，配置极简。插件自然是 obsidian-livesync 本体，直接在 Obsidian 社区插件市场搜索 Livesync 就能装。需要注意的是，插件本身只同步文本内容，图片和 PDF 这类二进制附件如果体积不大，可以以 base64 形式内嵌到数据库文档里；但如果你的库里有大量大文件，建议配置 S3 兼容对象存储来存放附件，避免数据库迅速膨胀。

3. 实操记录：从零部署一套自己的同步环境

3.1 服务器端准备与硬件选型

先说我用的环境：一台 2 核 2G 内存的轻量云服务器，系统是 Ubuntu 22.04，带宽 5Mbps。这个配置跑 CouchDB 绰绰有余。如果你的笔记库不大，1G 内存的机器也能跑。我自己还有一台 NAS，后续打算把数据库迁到内网，进一步降低延迟。

部署前建议先更新系统依赖：

sudo apt update && sudo apt upgrade -y

然后确认 Docker 已经安装。如果还没有，可以用官方脚本装：

curl -fsSL https://get.docker.com | sh sudo systemctl enable docker && sudo systemctl start docker

3.2 用 Docker 部署 CouchDB

我选择了 CouchDB 3.x 最新稳定版镜像。这里有一个关键配置：COUCHDB_USER和COUCHDB_PASSWORD是初始化管理员账号的环境变量，一定要设成强密码。CouchDB 默认就是需要认证的，不要图省事跳过。

准备一个docker-compose.yml：

version: "3.8" services: couchdb: image: couchdb:3.3.3 container_name: couchdb restart: unless-stopped ports: - "5984:5984" environment: - COUCHDB_USER=admin - COUCHDB_PASSWORD=your-strong-password volumes: - ./data:/opt/couchdb/data

启动服务：

mkdir -p couchdb-livesync && cd couchdb-livesync # 编写 docker-compose.yml 后执行 docker compose up -d

启动之后，可以用浏览器访问http://服务器IP:5984/_utils，如果能看到 CouchDB 的网页管理界面，说明服务已经起来了。这时先别急着用，还需要创建数据库并配置跨域权限。

3.3 配置数据库、CORS 和镜像同步

Livesync 插件默认会使用一个名为obsidian的数据库，但这个名字可以随便改，比如mynotes。建议在管理界面手动创建好，避免插件第一次连接时因为权限问题报错。

CORS 是必须配置的，否则浏览器插件无法跨域请求 CouchDB。Livesync 插件会在配置阶段自动尝试设置 CORS，但我实际操作中发现，有时候因为网络原因或者版本差异，自动配置并不总能成功。更稳妥的做法是直接在 CouchDB 的配置文件里手动加上 CORS 规则。

我把local.ini末尾追加了以下配置（也可以通过管理界面的 Config 页面添加）：

[httpd] enable_cors = true [cors] origins = app://obsidian.md, capacitor://localhost, http://localhost credentials = true methods = GET, PUT, POST, HEAD, DELETE headers = accept, authorization, content-type, origin, referer max_age = 3600

改完配置后重启容器：

docker restart couchdb

这里有个容易忽略的点：CouchDB 的 CORS 配置如果不对，插件界面上会一直显示“connecting”，但没有任何具体报错。我一开始就是卡在这里，排查了很久才发现是origins里漏了app://obsidian.md这个来源。不同客户端的 Origin 不一样，桌面端是app://obsidian.md，移动端是capacitor://localhost，两个都要列上。

3.4 配置反向代理和 HTTPS

直接用 IP + 端口访问也是能用的，但插件文档里强制要求 HTTPS，尤其是在 Obsidian 桌面端。原因很简单，浏览器环境下的安全策略不允许在 HTTPS 页面里请求 HTTP 资源。所以反代这一层躲不掉。

Caddy 是我强烈推荐的工具，它的配置简单到只需要几行：

your-domain.com { reverse_proxy localhost:5984 }

把your-domain.com换成你自己的域名，并提前把域名的 DNS 解析到服务器 IP。Caddy 会自动申请 Let's Encrypt 证书，全程不用手动干预。安装 Caddy：

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list sudo apt update sudo apt install caddy

把配置写入/etc/caddy/Caddyfile后，重启 Caddy：

sudo systemctl restart caddy

我实际配置完成后，用curl https://你的域名/测试，能看到 CouchDB 返回的 JSON 信息，说明反代已经生效。整个过程中 HTTPS 证书的申请是自动完成的，这也是 Caddy 比 Nginx 省心的地方。

3.5 Obsidian 插件端的配置步骤

服务器端就绪后，开始配置插件。在 Obsidian 里打开第三方插件市场，搜索livesync，安装后启用。配置界面非常直观，有几项必须要填：

• URI：填你的数据库地址，格式是https://你的域名/数据库名
• Username / Password：CouchDB 的管理员账号密码
• Encryption：如果开了端到端加密，需要设置一个密钥。建议开启，因为数据库里存的是同步后的明文，万一服务器被入侵，至少数据是加密的。

填写完这些，插件会先做一次连通性测试，然后提示你进行“初始化同步”。这里有一个关键选项：第一次同步时，是选择把当前设备的内容推送到数据库，还是从数据库拉取内容。如果你已经有一台设备上的笔记是全的，那就在这台设备上选择“推送”，其他设备再选择“拉取”。

初始化完成之后，插件会在界面右下角显示同步状态。正常情况下，几乎看不到它工作的痕迹，因为增量同步是在后台静默完成的。我用手机端打开同一个笔记库测试，电脑上保存后大概一两秒，手机上就提示内容已经更新了。

4. 两周使用后的真实感受

4.1 同步速度与稳定性

最直观的感受就是快，是真的快。以前用官方同步，在浏览器和电脑之间切换，经常要等进度条转一圈；现在基本是“无感同步”。我特意做了一个小实验：在电脑上新建一篇 500 字的 Markdown 笔记，然后立刻拿起手机打开 Obsidian，大概 1.5 秒左右，手机端已经能看到新笔记出现。

稳定性方面，这两周没有遇到过数据丢失、文件损坏的问题。我有一次在地铁里用手机写笔记，信号断断续续，写完后文字本地保存，等到有网络的地方，插件自动把修改推上去了。整个过程不需要我手动操作，这种离线优先的设计非常符合移动场景的需求。

数据库体积我也持续观察了一周。我通过配置对象存储后，CouchDB 数据目录每天增长大约 1~2MB，其中大部分是文档的历史_rev版本。这个增长速度完全在我的接受范围内，毕竟不需要频繁清理。

4.2 多设备工作流的变化

我现在是电脑 + 手机双设备使用。电脑上负责长文写作和资料整理，手机上负责碎片化收集和灵感记录。以前用云盘同步的时候，最怕遇到一件事：在手机上看过一篇笔记，回到电脑上打开是旧版本。现在基本没有这个问题，因为同步的粒度是“文档”，只要改动了，立刻推送。

我常用的一个场景是：在电脑上阅读 PDF 文献，划重点、写批注，同时手机端起一个“临时收件箱”的笔记，把突然想到的观点记下来。回到家打开电脑，这些内容已经在笔记库里了。整个流程非常顺滑，不会有那种“我需要手动点一下同步”的负担。

插件还支持“按需同步”模式。就是说，数据库里的所有文档不会全部下载到本地，而是只拉取当前打开笔记目录下的内容。这个功能对于笔记库特别大的用户很实用，可以缩短启动时间和减少磁盘占用。但我个人更倾向于全量同步模式，因为我会在手机离线时查阅历史笔记，按需同步模式下这部分数据可能不在本地。

4.3 和官方同步、iCloud、Git 方案的实际对比

为了更直观地说明它好在哪，我整理了一张对比表格：

从表格可以清楚看到，obsidian-livesync 最大的优势在于“数据自控 + 实时同步”这个组合。代价就是部署初期需要投入一些时间。如果你只有一台设备用 Obsidian，根本不需要同步方案；如果你有跨设备需求但不想折腾，官方 Sync 依然是省心的选择；但如果你对数据隐私有要求，又希望获得接近官方服务的同步体验，那 livesync 几乎是唯一的开源方案。

5. 遇到的问题与排查记录

5.1 插件一直显示“connecting”或“disconnected”

这个问题我上面提到过，大概率是 CORS 配置问题。排查思路是：先用浏览器直接访问数据库地址，确认能正常返回 JSON；然后在 Obsidian 插件的设置界面，点“Test Connection”按钮，看具体报错信息。如果报错里提到 CORS，就去检查 Caddy 或 CouchDB 的 CORS 配置。

另外一个常见原因是防火墙没有放行 5984 端口。如果你的服务器有安全组，记得在控制台里放行 TCP 5984。不过配置了反代之后，其实可以只放行 80 和 443 端口，然后让 Caddy 把请求转发到本机的 5984。这样暴露的服务更少，也更安全。

5.2 数据库体积增长过快怎么办

CouchDB 默认保留每个文档的历史版本，这是为了处理冲突和同步恢复。但如果你的笔记更新非常频繁，数据库体积会越来越大。Livesync 文档里建议定期执行“数据库压缩”和“清理历史修订”。

我设置了一个定时任务，每周自动压缩一次数据库：

curl -X POST https://用户名:密码@你的域名/obsidian/_compact curl -X POST https://用户名:密码@你的域名/obsidian/_view_cleanup

手动执行的话，也可以直接在 CouchDB 管理界面的数据库操作菜单里点 Compact 按钮。这里要注意，压缩数据库和清理历史版本是不可逆的，执行前最好先做一个数据库备份。

5.3 同一篇笔记在两台设备上同时编辑，产生冲突

这是我在这次使用中真实遇到过的问题。我习惯一边用电脑写日记，一边用手机补充一些想法，有时候两条编辑线程同时进行，笔记内容就产生了分叉。Livesync 的处理方式是：不覆盖，保留两个版本，并在文件名或文档属性里标记冲突。

冲突发生后，Obsidian 笔记库里会出现类似2024-06-15-conflict-20240615T123456.md的文件。我需要手动打开这两个文件，决定保留哪个版本，或者手动合并内容，然后把不需要的那个删除。这个过程虽然需要手动介入，但至少数据不会悄无声息地消失。所以我建议：如果需要多人同时编辑同一篇笔记，还是要养成“先拉取再编辑”的习惯，减少冲突概率。

5.4 手机端同步不生效，总是要打开 App 才同步

Livesync 在移动端的表现确实不如桌面端那么积极。因为系统限制，移动端 App 在后台会很快被挂起，插件无法持续维持与 CouchDB 的长连接。我目前的策略是：把 Obsidian 加入系统的后台应用白名单，同时打开允许后台刷新选项。另外在插件设置里把“同步频率”调高，让它在 App 活跃时尽量多的同步数据。

如果你只是偶尔在手机上查看笔记，需求其实不大；但如果你像我一样，经常用手机做灵感速记，建议在设置里开启“自动在应用打开时同步”。这样每次打开 App 时，会先做一次快速同步，至少保证你看到的是最新内容。

6. 一些经验总结和后续的优化方向

6.1 什么样的人适合用这套方案

这两周用下来，我觉得 obsidian-livesync 并不是适合所有人的方案。它更适合这几类人：一是对数据隐私有明确要求的人，不愿意把笔记放在第三方云服务上；二是喜欢折腾自托管的人，本身就有服务器或 NAS，也愿意花时间维护；三是跨设备使用频率高、需要实时同步的人。

反过来，如果你只是用 Obsidian 记记日记、写写周报，而且主要在一台设备上使用，那这套方案对你来说纯粹是增加维护负担。官方同步虽然要付费，但胜在零配置、省心。Git 方案虽然实时性差，但如果你的使用场景偏版本管理，它依然有不可替代的价值。选什么方案，取决于你对“数据控制权”和“省心程度”的权重分配。

6.2 后续我打算做的几件事

目前这套环境已经跑得很稳，但我还有一些优化打算。第一是把 CouchDB 的自动备份做起来，方案是每天凌晨用 CouchDB 的_replicate接口把obsidian数据库复制到一个备份数据库里，再把备份数据库定期导出到对象存储。第二是把端到端加密彻底验证一遍，确认密钥丢失后的恢复流程是否顺滑，避免关键时刻发现没法解密。第三是尝试在 NAS 上再搭一个 CouchDB 实例，做异地容灾，这样即使云服务器挂了，家里的数据库还能顶上。

我也会持续关注项目更新，目前 Livesync 仍然保持较高的维护频率，社区的 Issue 反馈也及时。如果有新版本，我会在验证稳定后再升级，避免因为版本更新破坏现有同步环境。

最后再分享一个小技巧：如果同步过程中发现某个文件一直无法同步，先检查这个文件的文件名里是否包含特殊字符。CouchDB 的文档 ID 不能包含某些字符，Livesync 虽然会自动做处理，但偶尔遇到特别离谱的文件名还是会出问题。我遇到过文件名里带%的笔记，同步一直失败，后来改成普通文件名就解决了。这种问题官方文档里不好找，属于实际使用中才会踩到的细节。