Obsidian 自建同步全攻略：Docker 部署 CouchDB 免订阅多端同步

我之前一直用 memos 记录碎片想法，它轻量、好用，但用久了会遇到两个瓶颈：笔记之间没有真正的"关联"，数据也被锁在它自己的数据库里。后来我转向了 Obsidian——笔记就是本地的 Markdown 文件，双链、插件生态都很强。

接下来的问题是：怎么在电脑、手机、平板之间同步？

官方的 Obsidian Sync 要订阅，价格大约每月几美元（年付更便宜，具体以官网为准）。而我手里正好有一台绿联 NAS，于是用 Docker 部署 CouchDB + Obsidian 社区插件 Self-hosted LiveSync，搭了一套：

实时同步：改完一段话，其他设备通常一两秒内就能看到
端到端加密：服务器上存的是密文，连我自己在数据库里也看不懂
数据完全自己掌握：不依赖任何第三方网盘或订阅
没有订阅费：硬件是现成的 NAS，远程访问只需一个几块钱的域名（见 1.4 节）

这篇文章面向完全没接触过 CouchDB 的新手。我会先讲清楚原理，再一步一步带你配置，最后给出日常注意事项和常见报错的速查表。照着做，一次成功是完全可能的。

一、先搞懂原理：它到底是怎么同步的

很多教程直接让你复制粘贴命令，出了问题就无从下手。花五分钟理解原理，后面所有配置都会"顺理成章"。

1.1 三个角色

角色	是什么	作用
CouchDB	一个开源数据库	部署在 NAS 上，充当"中转站"，保存所有设备同步上来的数据
Self-hosted LiveSync	Obsidian 的社区插件	装在每台设备的 Obsidian 里，负责和 CouchDB 对话
Docker	容器运行环境	让 CouchDB 一条命令就能跑起来，不污染 NAS 系统

1.2 它和"文件同步"有什么不同

普通的网盘同步（iCloud、坚果云、Syncthing 等）是以文件为单位复制的：两台设备改了同一个文件，就容易产生冲突副本。

LiveSync 的做法不一样：

插件在每台设备内置了一个 PouchDB（可以理解为"浏览器里的 CouchDB"）。
PouchDB 和服务端 CouchDB 使用同一套复制协议，同步就是"两个数据库互相对账"。
一篇笔记不会整篇存储，而是被切成许多小块（chunk），每块是一条独立记录。
你只改了一个段落，就只有那一块需要传输；两台设备改了同一篇笔记的不同段落，可以自动合并；改了同一段落，插件会弹出冲突处理界面，两个版本都保留，不会悄悄丢内容。
实时模式下，插件会保持与 CouchDB 的长连接，监听数据库的变化，所以才能做到秒级同步。

一句话总结：每台设备都有一份完整的本地数据，NAS 上的 CouchDB 是大家对账的"中转站"。这也意味着——你的每一台设备本身就是一份完整副本。

1.3 为什么这套方案值得折腾：同类方案对比

方案	费用	是否实时	冲突处理	备注
Obsidian Sync（官方）	订阅制	是	好	最省心，但要持续付费
Remotely Save	免费（需自备网盘/WebDAV/S3）	否，定时同步	较简单（以较新文件为准）	配置简单，但不是实时
Git	免费	否，需手动提交	文件级	手机端体验较差，不适合新手
iCloud/网盘/Syncthing	免费或低价	近实时	文件级，易出冲突副本	iCloud 仅限苹果生态；Syncthing 在 iOS 上缺少官方客户端
Self-hosted LiveSync	免订阅（自备服务器）	是	分块合并，不丢内容	需要自己搭建和维护

1.4 "零成本"到底指什么？

我想老实说清楚，避免你被标题误导：

没有订阅费：这是真的。
你需要已有一台能 24 小时开机的设备：本文用 NAS，其他如旧电脑、树莓派、VPS 也行。
手机在外面同步需要一个受信任证书的 HTTPS 地址。最省钱的做法是用域名（6 位数字的 .xyz 域名一年只要几块钱），再用 Lucky 配置 DDNS 与反向代理。如果你只在家里局域网使用，可以完全不花钱。

二、方案总览：架构、准备清单、网络方案怎么选

2.1 最终架构

  手机 Obsidian ─┐
  平板 Obsidian ─┼──(HTTPS)──► 反向代理（负责证书） ──► CouchDB 容器 ──► NAS 硬盘
  电脑 Obsidian ─┘                                          ▲
        │                                                   │
        └── 每台设备本地都有一份完整笔记库（PouchDB） ◄──────┘ 实时对账

2.2 准备清单

一台支持 Docker 的 NAS 或任何 Linux 主机（本教程以绿联 NAS为例）
电脑和手机上已安装 Obsidian
（手机外网同步需要）一种 HTTPS 访问方案，见 2.3

开始之前请先备份现有笔记库（包括隐藏的 .obsidian 文件夹）。另外，同一个笔记库只能交给一种同步方式管理，不要让 LiveSync 和 iCloud、网盘、Syncthing、Obsidian Sync 同时处理同一个库，否则会互相覆盖。

2.3 网络方案怎么选

手机在外面（4G/5G）要连回家里的 NAS，必须解决两件事：能到达和 HTTPS 受信任。官方明确说明：移动端不支持 http:// 地址，也不支持自签名证书。

解决方案：域名 + DDNS + 反向代理 + 正规证书（适合有公网 IP 或公网 IPv6 的家宽用户，手机无需安装任何额外软件）

三、第一步：在 NAS 上用 Docker 部署 CouchDB

3.1 规划目录

在 NAS 上新建一个专门的文件夹，路径因 NAS 系统而异。务必放在有 RAID 或有快照保护的存储卷上，因为这里存的是你的全部笔记。（本文以绿联 NAS 为例）

在 NAS 上新建一个专门的文件夹

3.2 创建 Docker 项目

打开 Docker - 创建项目，编写 docker-compose.yml

创建 Docker 项目

services:
  couchdb:
    image: couchdb:3
    container_name: couchdb
    restart: unless-stopped
    ports:
      - "5984:5984"
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=请替换为你的强密码
    volumes:
      - ./data:/opt/couchdb/data
      - ./etc:/opt/couchdb/etc/local.d

逐行解读：

image: couchdb:3：使用官方镜像的 3.x 版本。不建议用 latest，避免某天镜像大版本升级后重启容器，数据库悄悄变了。
container_name: couchdb：容器名称。
ports: "5984:5984"：把 CouchDB 的 5984 端口开放到 NAS（仅供局域网调试，远程访问请看 4.2 节）。
restart: unless-stopped：NAS 重启或容器异常退出后自动拉起。
COUCHDB_USER：管理员账号。
COUCHDB_PASSWORD：管理员密码。请务必使用强密码并保存好，每台设备都要用。
./data:/opt/couchdb/data：把数据库文件保存在 NAS 上。没有这行，容器一删数据就没了。
./etc:/opt/couchdb/etc/local.d：CouchDB 读取配置文件的目录。后面插件“一键修复”写入的服务器配置通常会保存在这里，没有这行，容器重建后配置可能丢失。

然后点击部署。

3.3 国内网络环境加速技巧

若拉取官方镜像超时，可优先在 NAS 的 Docker 设置里配置镜像加速；或把 image: couchdb:3 替换为国内镜像源地址（例如 docker.xuanyuan.me/library/couchdb:3）。第三方镜像源的可用性会变化，请以你实际能拉取的为准。

四、第二步：创建数据库并验证服务端

4.1 启动容器与后台初始化验证

1、启动容器成功后，在浏览器输入 http://NAS-IP:5984/_utils/，用管理员账号登录 Fauxton 管理后台。

2、登录后，点击右上角 Create Database，创建一个名为 obsidian 的独立数据库（名称必须小写）。

4.2 让手机也能连——配置 HTTPS 访问（可选）

部署 Lucky 配置 DDNS 与反向代理，实现 IPv6 + HTTPS 远程访问内网设备。如果只在局域网内使用，可以跳过此步骤。

安全提醒：配置完成后，路由器/防火墙只放行 HTTPS 端口，不要把 CouchDB 的 5984 明文端口直接暴露到公网。

五、第三步：电脑端（主设备）Obsidian 接入与一键调优

建议第一台选择电脑，因为后面生成给手机用的"配置链接"也在电脑上完成。

5.1 安装插件

1、打开电脑端 Obsidian，新建仓库。

2、进入设置 -> 第三方插件，退出受限模式，在社区插件市场搜索并安装 Self-hosted LiveSync（作者 vrtmrz）并启用。

3、打开插件设置，快速设置 -> 重新运行引导向导，会进入设置向导（Setup wizard）。

首先，请选择最符合你当前情况的选项。 我是第一次进行设置
你希望如何配置服务器连接？手动输入服务器信息
端到端加密：开启并设置一个加密口令（Passphrase）
建议同时开启 路径混淆（Path Obfuscation），这样连文件名/路径也会被加密。
ID generation：保持默认 Generate a random ID key
请选择你要连接的服务器类型。CouchDB

请务必理解这三条：

加密口令必须在所有设备上一致。口令不一致的设备无法解密数据。
口令丢了就找不回来，数据库里的数据将永远无法解密（笔记在你各设备的本地副本里仍然是明文可读的）。请把口令保存到密码管理器里。
它和后面的"Setup URI 口令"是两个不同的东西，不要混为一谈。

CouchDB 配置：

字段	填什么	示例
URL	CouchDB 的地址	局域网：`http://NAS-IP:5984` 外网：`https://xxx.xxx.com:8443`
Username	前面设置的管理员用户名	admin
Password	前面设置的管理员密码	（你的密码）
Database name	4.1 节创建的数据库名，必须小写	`obsidian`

建议勾选 使用内部 API，以规避部分跨域（CORS）和浏览器限制。然后点击检查服务器要求，如果问题检测日志中出现错误，逐项点击修复。

直到所有检查均已通过，再依次点击：创建或链接到数据库并继续、重启并初始化服务器。

5.2 选择同步模式并完成首次上传

在同步设置（Sync Settings）里选择 LiveSync（实时同步）模式。

首次配置时，插件会让你选择如何初始化数据库。第一台设备的含义是：把本地的笔记库上传到服务器，作为"基准版本"。按向导提示完成初始上传即可（根据所选，可能需要选择"以本地为准重建远程数据库"之类的选项，请按向导对"第一台设备"的说明操作）。

建议同时启用 在编辑器中显示状态（Show status inside editor）：在编辑器右上角能看到同步状态（上传/下载的数量），一眼就知道有没有在同步。

等状态显示空闲、没有待处理项目，就代表首次同步完成了。笔记较多时第一次会花几分钟到更久，请耐心等待，不要中途强制退出。

5.3 验证第一台设备

在 Obsidian 里新建一篇笔记，写几个字。
打开 https://你的域名:端口/_utils（或局域网地址），登录后进入 obsidian 数据库。
你会看到数据库里的文档数量增加了。因为开启了端到端加密，内容是密文，看不懂是正常的，这恰恰说明加密生效了。

六、第四步：添加更多设备（含手机）多端联动

6.1 在已配置好的设备上生成"配置链接"（Setup URI）

手动在每台设备上重新填一遍很容易出错。LiveSync 提供了更稳妥的方式：

在已配置好的第一台设备上，进入插件设置的 设置其他设备，点击 将当前设置复制为设置URL。
弹出对话框，让你设置一个用于加密设置链接（URI）的密码/口令 The passphrase to encrypt the setup URI，输入后确认。
链接会被复制到剪贴板。它是一个以 obsidian://setuplivesync?settings=... 开头的长字符串，里面包含了连接信息并用该口令加密。
设置 URI 可用性：按需选择：Time-bound（限时）、Compatible (no time limit)兼容（无时间限制）

生成前请先确认：电脑端填写的 URL 已经是手机也能访问的 HTTPS 外网地址。Setup URI 会原样带上这个地址，如果还是局域网的 http://NAS-IP:5984，手机导入后将无法连接。

安全提醒：这个链接相当于"邀请码"，请通过可信渠道发送到新设备（如 AirDrop、自己与自己的聊天、加密笔记），口令不要和链接放在同一条消息里。用完之后不再需要它。

6.2 在新设备（以手机为例）上导入

手机上安装 Obsidian。
新建一个空的笔记库（名字随意，建议与电脑上一致）。不要把已经有旧内容的笔记库当作新设备去同步，否则可能和服务器上的数据合并出乱象。
进入设置，关闭受限模式，安装并启用 Self-hosted LiveSync。
打开插件设置，进入 快速设置，点击 使用设置URL连接，粘贴刚才的链接，输入 Setup URI 口令。
在选项中选择 Join this device。
按提示输入端到端加密口令（如果被要求），等待同步完成。

完成后，在电脑上改一篇笔记，几秒钟后手机上就能看到；反过来也一样。

提示：手机系统会限制应用在后台运行，所以手机端的实时同步通常只在打开 Obsidian 的时候进行，这不是故障。编辑完重要内容后，退出前请确认状态栏已显示同步完成。

6.3 手机端首次同步策略选择

导入 Setup URI 后，插件会询问首次同步的策略。手机是全新的空库，按下面选择：

数据拉取策略：选择 Overwrite all with remote files（用远程 NAS 上的文件覆盖手机本地空库）。
历史冗余文件处理：选择 Delete local files if not on remote（清理手机初始示例文件，保证多端绝对一致）。
输入与电脑端一致的端到端加密口令并开始下载。

警告：以上两项会让手机本地文件以服务器为准，只能用于全新的空笔记库。已经有内容的笔记库不要这样选，否则本地独有的文件会被删除。

七、日常注意事项与常见问题速查

7.1 日常注意事项

同步不等于备份。在一台设备上误删笔记，删除操作也会同步到所有设备。建议定期备份 NAS 上的 data 目录（可配合 NAS 的快照或备份功能），并偶尔把笔记库复制一份到其他位置。
一个笔记库只用一种同步方式，不要和 iCloud、网盘、Syncthing、Obsidian Sync 同时管理同一个库。
冲突处理：两台设备同时修改了同一段落时，插件会弹出冲突界面，两个版本都会保留，由你选择。
大规模整理（批量改名、批量移动大量文件）时，让一台设备操作，等其他设备同步完成后再继续。

7.2 常见问题速查

现象	可能原因	解决办法
`401 Unauthorized`	账号或密码错误；反向代理改写了认证头	核对 URL、Username、Password；检查反向代理没有丢掉 `Authorization` 请求头
电脑能连，手机连不上	手机必须使用受信任证书的 HTTPS；Setup URI 里仍是局域网 http 地址	用手机流量打开 `https://你的域名:端口/_utils` 验证；确认生成 Setup URI 时用的是 HTTPS 地址
提示数据库不存在（404）	没有创建数据库，或名称含大写字母	回到 4.1 节创建，名称必须小写
解密失败、内容乱码	各设备的端到端加密口令不一致	所有设备使用同一个口令
大文件同步失败或中途断开	反向代理限制了请求体大小，或超时时间过短	在反向代理中放宽请求体大小与超时限制
手机上改了，电脑迟迟看不到	手机应用被系统挂起	打开手机 Obsidian，等待同步完成
容器反复重启	数据目录权限不对	执行 `docker logs couchdb` 查看日志，按提示修正目录权限

八、总结

理解原理：每台设备本地一份完整库，CouchDB 是中转站，同步是数据库对账。
部署 CouchDB：用 Docker Compose 启动容器，并创建数据库。
配置 HTTPS：手机端的硬性要求，用 DDNS + 反向代理 + 正规证书实现。
配置电脑端：安装插件，检查并修复服务器配置，开启端到端加密，完成首次上传。
添加其他设备：用 Setup URI 一键配置，新设备用空库从服务器拉取。

科学上网