Obsidian LiveSync 自建同步教程：飞牛 NAS Docker 部署 CouchDB 完整指南

前言

Obsidian 的同步方案有很多种。

最省心的是官方 Obsidian Sync，打开就能用，手机和电脑都照顾得很好。缺点也很直接，它是订阅制服务，如果你已经有 NAS，可能会觉得每年再为同步付一笔费用有点浪费。

也有人会选择 iCloud、坚果云、OneDrive、百度网盘同步空间 这类网盘同步。它们的优点是上手简单，缺点是多设备同时编辑时容易出现冲突，移动端体验也不一定稳定。尤其是 Obsidian 这种由大量 Markdown 文件、配置文件和插件数据组成的资料库，普通网盘同步经常会遇到延迟、重复文件、配置不同步等问题。

用 Remotely Save 接 WebDAV、S3 或网盘，通常是先准备一个云端位置，再把同一组连接信息填到每台设备里，上手路径比较清楚。它的体验很依赖后端服务的稳定性，比如坚果云这类 WebDAV 服务，频繁请求时可能遇到接口限制或 503 报错；换成其他网盘，又可能遇到不同系统支持不一致的问题。设备越多，系统越杂，这些细节越容易被放大。

Self-hosted LiveSync 走的是另一条路。它通过 CouchDB 在多台设备之间同步改动，不需要把整个 Vault 当成一堆文件交给网盘处理。你可以把 CouchDB 部署在自己的 NAS 上，让 Mac、Windows、手机都连接到这台 NAS。它支持端到端加密，同步速度也很快，适合已经有 NAS、愿意折腾一点配置的人。

很多人会用 Git 同步 Obsidian，因为它能保留历史、方便回退，也适合做版本管理和备份。把它放进日常多端写作以后，commit、push、pull 会变成使用流程的一部分。电脑端还好，到了手机和平板上，配置、性能和冲突处理的成本都会更明显。LiveSync 更关心多设备持续同步，让几台设备围绕同一个同步服务交换变化。

这篇文章会用飞牛 NAS 的 Docker 应用来演示。虽然截图基于飞牛，但只要你的 NAS 支持 Docker，比如群晖、绿联、威联通，也可以参考同一套思路。

这套方案不算简单，它需要你理解 Docker、端口、CouchDB、局域网地址和插件配置。配置错一步，就可能连接失败，甚至把某台设备上的旧数据覆盖到服务器。因此，正式操作前请先备份你的 Obsidian Vault。

本文会先跑通局域网同步，也就是电脑和 NAS 在同一个网络下的同步。公网同步、手机端 HTTPS 访问、FN Connect 这类远程访问问题，会放在后面单独处理。

局域同步

先从最稳定的局域网同步开始。

所谓局域网同步，就是你的电脑、手机和 NAS 都在同一个家里或办公室网络里。Obsidian 不再把笔记传到第三方云盘，而是把数据同步到 NAS 上运行的 CouchDB。Mac、Windows、手机再从这个 CouchDB 读取和写入数据。

这个方案的好处是速度很快，也更可控。NAS 在你自己的网络里，数据不会经过额外的云盘服务；LiveSync 还可以开启端到端加密，即使 CouchDB 里保存了同步数据，也不能直接读出你的笔记内容。

Syncthing 更像设备之间的点对点文件同步，适合愿意维护设备连接和目录配对的人。LiveSync 则把 CouchDB 放在中间，Mac、Windows、手机都连到同一个同步中心。部署门槛会更高，但后面接入新设备、检查同步状态、判断数据方向时，路径会更清楚。

但它的限制也很明显，只做局域网同步时，设备必须连回同一个网络。你在外面用手机流量，或者电脑不在家里的网络里，就访问不到这台 NAS。后面会单独讨论公网同步和远程访问，这一节先把本地同步跑通。

飞牛部署 CouchDB

先打开 fnOS 自带的 Docker 应用，切换到「镜像仓库」。

在搜索框里输入 couchdb，找到官方的 couchdb 镜像。

点击右侧的下载按钮。标签保持默认的 latest 就可以。

确认后，飞牛会开始创建下载任务。

下载完成后，切换到「本地镜像」，找到刚刚下载好的 couchdb。

点击右侧的启动按钮，开始创建容器。

容器名称可以直接写成 couchdb。

资源限制不用打开，CPU 和内存保持自动即可。

建议勾选「开机自动开启」，这样飞牛重启后，CouchDB 也会自动启动。

然后点击「下一步」。

接下来会进入「高级设置」。

这一页看起来有很多选项，但真正需要我们手动配置的主要是端口设置、存储位置和环境变量。其他地方保持默认即可。

在配置存储位置之前，先到飞牛的「文件管理」里创建 CouchDB 要用的文件夹。

建议路径放在 docker 文件夹下面，比如：

docker/obsidian-couchdb/

然后在里面创建两个子文件夹：

data
local.d

data 用来保存 CouchDB 的数据，local.d 用来保存 CouchDB 的配置文件。

文件夹名称尽量只用英文、数字和普通短横线。不要使用中文、空格或复制出来的特殊横线，否则后面创建容器时可能会出现「参数错误：容器的存储位置」。

回到 Docker 的高级设置，先展开「存储位置」。

这里要添加两条路径映射：

/docker/obsidian-couchdb/data    -> /opt/couchdb/data
/docker/obsidian-couchdb/local.d -> /opt/couchdb/etc/local.d

左边是飞牛里的文件夹，右边是容器里的路径。

这里不要手动输入左边的路径，请点击输入框右侧的文件夹图标，在弹出的文件选择窗口里手动点选刚刚创建好的 data 和 local.d 文件夹，这样最终的路径才是正确的。

如果手动输入路径，很容易因为目录不存在、短横线不对或路径格式不对，导致创建容器时报错。

接下来准备 CouchDB 的配置文件。

可以先在电脑本地新建一个普通文本文件，把下面这段内容复制进去：

[couchdb]
single_node = true
max_document_size = 50000000

[chttpd]
require_valid_user = true
max_http_request_size = 4294967296
enable_cors = true

[chttpd_auth]
require_valid_user = true
authentication_redirect = /_utils/session.html

[httpd]
WWW-Authenticate = Basic realm="couchdb"
enable_cors = true

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

保存后，把文件名改成：

local.ini

注意后缀必须是 .ini，不要保留成 local.ini.txt。

然后把 local.ini 上传到刚刚创建的 local.d 文件夹里。

上传完成后，local.d 里面应该能看到这个 local.ini 文件。

回到 Docker 的高级设置，展开「环境变量」。

这里添加两条环境变量：

COUCHDB_USER=你的用户名
COUCHDB_PASSWORD=你的强密码

用户名可以自己取，密码建议用一串足够长的强密码。不要使用 admin、123456 这类太容易猜到的组合。

端口设置这里也要检查一下。

CouchDB 在容器内部默认使用 5984 端口。为了减少后面配置时的混乱，建议本地端口也直接使用 5984：

本地端口：5984
容器端口：5984
协议：TCP

这样后面访问的地址就是：

http://飞牛的局域网 IP:5984/_utils

如果你的 NAS 上已经有其他服务占用了 5984，也可以把本地端口改成别的数字，比如：

本地端口：9100
容器端口：5984
协议：TCP

这种情况下，后面 Obsidian 里填写的地址也要跟着改成 http://飞牛的局域网 IP:9100。

重点在于容器端口必须保持 5984。你可以改左边的本地端口，但不要把右边的容器端口也改成 9100。

确认页里重点检查几件事：

• 容器名称是 couchdb
• 开机自动开启是「是」
• 存储位置已经映射到 /opt/couchdb/data 和 /opt/couchdb/etc/local.d
• 环境变量里已经有 COUCHDB_USER 和 COUCHDB_PASSWORD
• 端口映射的容器端口是 5984

确认无误后，勾选「创建后启动」，点击「创建容器」。

创建成功后，回到 Docker 的「容器」页面。

如果 couchdb 左侧显示绿色圆点，并且能看到 CPU、内存占用，就说明 CouchDB 容器已经运行起来了。

到这里，飞牛上的 CouchDB 服务已经部署完成。

下一步就可以回到 Obsidian，安装并配置 Self-hosted LiveSync 插件。

在 Mac 上安装插件

回到 Obsidian，打开「设置」里的「第三方插件」。

如果你之前没有打开第三方插件，需要先关闭安全模式，然后进入社区插件市场。社区插件的安装方式都差不多，如果需要完整流程，可以先看这篇：Obsidian 最新全平台插件安装教程。这里继续演示和 LiveSync 有关的部分。

在插件市场搜索：

livesync

找到 Self-hosted LiveSync，点击「安装」。

安装完成后，点击「启用」。

第一次启用时，插件可能会弹出翻译提示。这里点 OK 就可以，不影响后续配置。

接下来会进入 Self-hosted LiveSync 的初始化向导。

这里选择「我是第一次进行设置」，然后点击「是的，我要配置新的同步」。

下一步会让你选择连接方式。

这里不要选 Setup URI。Setup URI 通常是官方脚本或已经配置好的设备生成的一整串连接信息。我们现在是自己在飞牛上手动部署 CouchDB，所以选择「手动输入服务器信息」。

选好后，点击「我知道服务器详情，让我手动输入」。

接下来是端到端加密设置。

建议开启端到端加密，并设置一个单独的加密密码（不是 CouchDB 的登录密码）。后面在其他电脑或手机上接入同一个同步库时，也必须输入同一个加密密码。这个密码一旦忘记，服务器上的数据即使还在也无法解密，建议保存在密码管理器里。

往下看，还会看到 Obfuscate Properties 选项。

这个选项的作用是把远程服务器里能看到的文件路径、文件大小、创建时间、修改时间等属性也做一层混淆。开启后，即使有人能看到 CouchDB 里的原始数据，也更难直接看出你的文件结构。

这里建议勾选。

设置完成后，点击 Proceed。

接下来选择服务器类型。

这里选择 CouchDB，然后点击「继续进行 CouchDB 设置」。

然后填写 CouchDB 连接信息。

如果你现在只是在 Mac 上测试，可以先使用飞牛的局域网地址，例如：

http://飞牛局域网 IP:5984

比如我的测试地址是：

http://192.168.31.158:5984

这里会看到一条提醒，说 Obsidian Mobile 只能使用 HTTPS 连接。这一点很重要，但现在我们先把电脑端流程跑通。手机端需要 HTTPS 或其他远程访问方案，后面再单独处理。

下面三项按你在飞牛 Docker 里设置的 CouchDB 信息填写：

用户名：COUCHDB_USER
密码：COUCHDB_PASSWORD
数据库名称：obsidian_db

数据库名称可以自己取，但不要使用大写字母、空格和特殊字符，也不要以下划线开头。为了后续教程统一，我这里使用：

obsidian_db

Use Internal API 先不要勾选。只有遇到浏览器跨域问题，并且普通方式无法连接时，再考虑它。

填好后，先点击 Detect and Fix CouchDB Issues。

如果检测通过，下方会显示 All checks passed successfully!。确认通过后，再点击 Test Settings and Continue。

如果出现下面这种提示，说明连接已经配置成功，插件准备把当前设备里的库作为第一份同步数据上传到服务器。

点击 Restart and Initialise Server。

随后可能会出现 Fetch Remote Configuration Failed。

第一次配置一个全新的服务器时，这个提示通常是正常的。因为远端还没有任何 LiveSync 配置可读取。

这里点击 Skip and proceed，继续往下走。

接下来插件会重启同步流程，右上角会出现一串黑色提示。

这些提示大概会包含：

Local Database Reset
SYNC DATABASE AND STORAGE
远程数据库已创建或连接

只要没有持续报错，可以继续等待下一步弹窗。

修复 LiveSync 推荐配置

完成基础连接后，插件可能会启动「配置诊断」。

这个诊断会检查当前库的 LiveSync 设置是否适合跨设备同步。这里直接点击「确定」。

后面会连续出现几个修复项。建议按插件推荐全部点击「修复」。三个修复项都处理完后，插件会再次提醒你确认服务器数据。

用当前设备初始化服务器

下面这个窗口表示，插件将删除服务器上现有的 LiveSync 同步数据，然后用当前设备里的 Obsidian 库重新生成一份服务器数据。

如果你是第一次配置一个空的 CouchDB 数据库，这是正常流程。

但如果这个 CouchDB 里已经有你正在使用的同步数据，就不要随便点。因为它会把服务器端原来的同步数据覆盖掉。

在本教程里，我们使用的是一个全新的测试库，所以可以继续。

这里需要勾选三个确认项：

• 我知道其他手机或电脑上的更改可能会丢失
• 我知道其他设备需要重新设置同步信息
• 我知道这个动作执行后无法撤销

下面还会问你是否已经备份。

如果你是在正式库里操作，建议先复制整个 Vault 文件夹做一份备份，再选择「I have created a backup of my Vault」。

如果你和我一样是在测试库里演示，也可以选择「I understand the risks and will proceed without a backup」。

确认后，点击 I Understand, Overwrite Server。

随后可能会出现一个提示，说本机设置和服务器设置略有不同，插件已经用服务器设置补齐了不兼容的部分。这里点 OK。

如果继续出现：

Do you want to send all chunks before replication?

第一次初始化服务器时，建议点「是」。这样插件会先把当前库的数据块发送到服务器，再开始后续同步。

如果出现数据库大小通知，自建飞牛 CouchDB 可以先选择 2GB（标准）。这个设置只是提醒用的上限，不代表立刻占用 2GB 空间。

到这里，Mac 这台设备上的 Self-hosted LiveSync 就已经配置完成了。

后续可以在插件设置页里看到同步状态。第一次同步完成后，右上角的同步提示不再持续报错，就说明当前设备已经能把数据写入飞牛上的 CouchDB。

在 Windows 上接入已有同步

目前我们已经完成的是第一台设备，也就是 Mac 端的初始化。Windows 端不要再重新初始化服务器，它要做的是加入 Mac 已经建立好的同步配置。

先回到已经配置好的 Mac，打开 Self-hosted LiveSync 的设置页，进入带有小巫师图标的「快速设置」页面。

在「设置其他设备」里，点击「将当前设置复制为设置 URI」右侧的「复制」。

如果前面开启了端到端加密，插件会让你输入一个密码来保护即将复制出来的 Setup URI。为了避免混乱，可以直接使用前面端到端加密时的同一个密码。后面在 Windows 或手机上导入这段 URI 时，也要输入同一个密码。

复制成功后，插件会提示 Your Setup URI is ready to be copied，这时 Setup URI 已经在剪贴板里。

把这段 Setup URI 发到 Windows。可以用局域网传输、聊天工具、剪贴板同步，或者临时保存成文本文件。注意这段 URI 里面包含连接服务器所需的信息，不要发到公开地方。

回到 Windows，先安装并启用 Self-hosted LiveSync。首次向导里选择「我要将设备加入现有同步配置」，然后点击「是的，我要把这台设备加入现有同步」。

接下来选择导入方式。

这里建议选择「使用 Setup URI」。这种方式会把服务器地址、数据库名称、用户名等设置一次性带过来，出错概率比手动重新输入低。

把刚才从 Mac 复制出来的 Setup URI 粘贴进去，再输入对应密码。

如果下方出现 The Setup-URI is valid and ready to use，说明这段 URI 可以使用。然后点击 Test Settings and Continue。

连接通过后，插件会提示准备从服务器获取同步数据。

这里点击 Restart and Fetch Data。这一步会让 Windows 从服务器下载最新同步数据，并用服务器上的数据重建本机的 LiveSync 本地数据库。

随后可能会出现「重置此设备上的同步」确认页。这里要根据 Windows 这个库的实际状态选择：

• 如果 Windows 是一个全新的空库，或者里面只有刚刚新建的少量空文件，选第二项：This Vault is empty, or contains only new files that are not on the server.
• 如果 Windows 是从 Mac 完整复制过来的库，内容几乎和服务器一致，选第一项：The files in this Vault are almost identical to the server's.
• 如果 Windows 这边已经编辑过很多文件，而且不确定和服务器是否一致，才选第三项：There may be differences between the files in this Vault and the server.

第三项最谨慎，但也最容易产生大量冲突记录，因为插件会重新检查每个文件的元数据。你这次测试时选第三项也可以，它适合「我不确定本地和服务器是否完全一致」的情况。正式教程里，更建议读者根据上面三种情况选择，不要一律选第三项。

无论选哪一项，继续前都建议先备份 Windows 里的 Vault。确认后点击 Reset and Resume Synchronisation。

如果接入后发现没有自动同步，打开 Self-hosted LiveSync 设置页，进入「同步设置」，确认「同步预设」已设为 LiveSync 同步 并点击「应用」。更多排查见后面的「同步失败解决方案」。

在安卓和 iPhone 上接入同步

安卓和 iPhone 的接入逻辑和 Windows 一样，安装并启用 Self-hosted LiveSync，首次向导选择「我要将设备加入现有同步配置」，用 Setup URI 或二维码导入。

建议先在电脑上完整走一遍接入流程，熟悉步骤后再操作手机。电脑端设置页里可以复制 Setup URI，也可以打开二维码让手机直接扫描。

同步插件和 Obsidian 设置

上面的步骤解决的是笔记文件同步。插件、主题、快捷键、Obsidian 设置这些内容，不会自动跟着普通笔记同步完全一致。

Self-hosted LiveSync 里有两个容易混淆的功能：

• Hidden Files Sync：更偏向隐藏文件同步，不是同步插件设置的主要入口。
• Customization Sync：用来同步 Obsidian 设置、主题、代码片段和插件配置。

如果你希望 iPhone 上也尽量拿到电脑端的插件和设置，应该配置 Customization Sync。

先打开 Self-hosted LiveSync 设置页，进入带小巫师图标的页面，确认「启用高级功能」和「启用高级用户功能」都已经打开。不开这两个开关，有些高级同步入口可能看不到。

然后切换到插头图标的 Customization sync 页面。

这里建议先给当前设备设置一个容易识别的设备名，比如 M5Max、MacBook、iPhone。后面在其他设备上选择要套用哪一台设备的配置时，就不会混淆。

接着打开「启用自定义同步」。

继续往下看，把下面几个选项也打开：

• 「自动扫描自定义设置」
• 「定期扫描自定义设置」
• 「通知自定义设置」

然后点击页面底部的 Open，打开 Customization Sync (Beta3) 窗口。

弹出的窗口如下。后面步骤里提到的 Scan changes、Sync once、Refresh、Select All Shiny 和 Apply All Selected 都能在这张图里看到。

在第一台设备，也就是你已经配置好的 Mac 或 Windows 上，顺序是：

1. 点击 Scan changes。
2. 扫描完成后点击 Sync once，把这台设备上的设置同步到远端。
3. 等右上角同步状态回到 ↑ 0 ↓ 0。

在第二台设备，比如 iPhone 上，顺序是：

1. 先正常同步一次笔记。
2. 按照相同的顺序，打开 Customization Sync (Beta3) 窗口。
3. 点击 Refresh。
4. 点击 Select All Shiny。
5. 点击 Apply All Selected。
6. 重启 Obsidian。

这里有两个坑需要注意。

第一，不要把插件设置同步误认为 Hidden Files Sync。如果目标是同步插件列表、主题、快捷键和插件数据，主要看 Customization Sync。

第二，如果你执行过 Reset Synchronisation on This Device 之类的重置操作，LiveSync 可能会临时关闭 Customization Sync。重置完成后，要回到这里重新打开「启用自定义同步」，再重新 Scan changes 和 Sync once。

同步失败解决方案

如果某台设备接入后没有自动同步，先不要急着重置数据库。

最常见的原因，是不同设备上的同步预设不一致。建议在所有平台的下图所示位置，把「同步预设」统一设置为 LiveSync 同步，然后点击「应用」。

这个预设会启用 LiveSync 常用的实时同步配置，适合大多数人直接使用。

如果仍然不同步，再按下面顺序检查：

1. 确认当前设备能打开 CouchDB 地址，比如 http://飞牛局域网 IP:5984。
2. 确认数据库名称、用户名、密码和第一台设备完全一致。
3. 确认端到端加密密码一致。
4. 确认这台设备没有同时开着 iCloud、OneDrive、坚果云等其他同步方案，避免两个同步工具同时改同一个 Vault。
5. 打开 LiveSync 的日志，看是否有网络、鉴权、CORS 或冲突相关报错。

在执行「Reset」「Overwrite」「Fetch」这类操作前，一定先备份整个 Vault 文件夹。方向判断参照「在 Windows 上接入已有同步」一节的原则，第一台设备用当前数据覆盖服务器，后续设备从服务器获取数据，不确定时先备份再选更谨慎的冲突检查。

公网同步

因为飞牛目前还不支持统一网关访问 Docker，因此如果你需要公网同步的话，目前暂不支持这个需求，未来等飞牛支持后我会第一时间更新本文，这里就暂时留空。

结论

这套方案最大的优点是同步无感、延迟低。LiveSync 只同步发生变化的数据块，日常写笔记几乎没有等待感。端到端加密加自建 NAS，数据完全在自己手里；CouchDB 对多设备版本冲突的处理也比普通网盘更可靠，简单冲突会自动合并，复杂冲突会保留痕迹方便判断。

但它的配置门槛确实高，最容易出问题的地方集中在 Docker 目录映射、CouchDB 配置文件、端口、HTTP 和 HTTPS、端到端加密密码，以及多设备接入时的覆盖方向。

另外，LiveSync 的数据库会随着长期使用变大。官方文档里也提到，文件删除后，已经生成过的数据块不一定会立刻从数据库中移除，因为这些数据块还可能用于历史版本、冲突处理和其他文件的复用。

换句话说，你在 Vault 里删除了文件，CouchDB 的占用空间不一定马上下降。

如果你经常删除、重命名、移动大量文件，数据库膨胀会更明显。真正想缩小数据库体积时，比较可靠的办法是执行 LiveSync 的重建流程，也就是让插件根据当前 Vault 文件重新构建本地和远程同步数据库。

官方文档里提到的做法包括 Rebuild everything，以及在 Vault 根目录放置 redflag2.md 或 flag_rebuild.md 后重启 Obsidian，让插件进入重建流程。

这个操作会重新整理同步数据库，适合在数据库异常膨胀、同步状态混乱、或者确认所有设备都已经同步完成之后使用。执行前一定要备份 Vault，因为它会重建同步关系，过程也可能消耗较多时间和网络流量。

如果你只是想要一个更省心的同步方案，Remotely Save、飞牛 WebDAV + Remotely Save 或 Obsidian 官方同步会更简单。它们的可调选项少，出问题时也更容易判断。LiveSync 更适合愿意折腾自建服务、希望数据放在自己 NAS 上、并且能接受排查成本的人。

Remotely Save、Git、Syncthing 和 LiveSync 解决的是不同问题，适合的人也不一样。Remotely Save 适合想尽快接入云端存储的人，Git 适合重视历史记录和回退的人，Syncthing 适合愿意维护点对点同步的人。LiveSync 更适合已经有 NAS 或服务器，并且希望 Obsidian 在多台设备之间同步得更及时、更连续的人。

所以我的建议是，先按本文跑通局域网内的一台 Mac 和一台 Windows。确认这条链路稳定后，再考虑手机端和公网访问。不要一上来就把所有设备、所有插件配置、所有隐藏文件一起同步进去，这样一旦出错，很难判断问题出在哪里。

无论你最后选择哪种同步方案，Vault 能多端同步之后，都可以参考 FLO.W Obsidian 模板安装教程，给这个库补上一套现成的项目、任务和笔记结构。