Obsidian 多端同步：用 Self-hosted LiveSync 自建实时同步教程

我做这套同步方案，核心目的很简单：

电脑端写文章，手机端能实时查看和补充；手机端临时修改，回到电脑也不会丢。

最后采用的方案是：

• 服务器部署 CouchDB。
• 用 nginx 提供 HTTPS 入口。
• Obsidian 安装 Self-hosted LiveSync 插件。
• 电脑端先完成初始化。
• 手机端通过 Setup URI 加入同步。

这套方案的重点不是把笔记搬到云端，而是让本地 Markdown Vault 在多台设备之间可靠同步。

后续（个人域名）统一需要修改为你自己的域名信息

一、核心架构

当前同步链路可以概括为：

各组件职责如下：

我现在服务器上的真实入口是：

个人域名

浏览器直接访问会返回 401，这是正常现象，说明 CouchDB 开启了认证。真正同步时，Self-hosted LiveSync 会携带数据库账号访问。

二、先明确：同步不是备份

Self-hosted LiveSync 解决的是多端实时同步，不是备份。

如果在一台设备上误删文件，同步系统可能会把删除同步到其它设备。因此正式配置前，先备份整个 Vault：

• .md 笔记文件。
• 图片、附件、assets 目录。
• .obsidian 配置目录。
• 模板、脚本、自定义样式。

同步负责多端一致，备份负责出事后恢复，这两件事不能混在一起。

三、服务器端部署

我的服务器是 Debian VPS，相关服务通过 Docker Compose 管理。Obsidian 同步服务放在：

/opt/obsidian-livesync/
  docker-compose.yml
  .env
  couchdb-data/
  couchdb-etc/

目录说明：

我当前服务器上的 CouchDB 容器名是：

couchdb-for-ols

当前 docker-compose.yml 的核心结构是：

services:
  couchdb:
    image: couchdb:latest
    container_name: couchdb-for-ols
    user: 5984:5984
    environment:
      COUCHDB_USER: ${COUCHDB_USER}
      COUCHDB_PASSWORD: ${COUCHDB_PASSWORD}
    volumes:
      - ./couchdb-data:/opt/couchdb/data
      - ./couchdb-etc:/opt/couchdb/etc/local.d
    ports:
      - "5984:5984"
    restart: unless-stopped

启动服务：

cd /opt/obsidian-livesync
docker compose up -d
docker compose ps

初始化 CouchDB：

curl -s https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/main/utils/couchdb/couchdb-init.sh | \
hostname=http://127.0.0.1:5984 \
username=<YOUR_COUCHDB_USER> \
password=<YOUR_COUCHDB_PASSWORD> \
bash

需要注意三点：

• couchdb-data/ 是核心数据目录，迁移和备份时优先处理它。
• 当前 5984 端口直接对公网开放，后面建议改成只绑定本机。

四、配置 HTTPS 入口

我现在是用固定域名加 nginx 反向代理：

个人域名 -> nginx -> 127.0.0.1:5984 -> CouchDB

nginx 配置文件位置：

/home/web/conf.d/个人域名.conf

核心配置逻辑如下：

upstream couchdb_obsidian_backend {
    server 127.0.0.1:5984;
    keepalive 32;
}

server {
    listen 80;
    server_name 个人域名;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name 个人域名;

    ssl_certificate /etc/nginx/certs/个人域名_cert.pem;
    ssl_certificate_key /etc/nginx/certs/个人域名_key.pem;

    location / {
        proxy_pass http://couchdb_obsidian_backend;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_read_timeout 180s;
        proxy_send_timeout 180s;
        client_max_body_size 1000m;
    }
}

这部分的重点是：

• 手机端需要稳定 HTTPS。
• proxy_buffering off 适合附件同步和长轮询。
• client_max_body_size 1000m 避免大附件被 nginx 拦截。
• 客户端最终只填写 个人域名，不直接填写服务器 IP。

五、电脑端配置第一台设备

先在电脑端配置，因为电脑端更适合输入密码、检查日志和复制 Setup URI。

流程如下：

1. 在 Obsidian 安装 Self-hosted LiveSync。
2. 打开插件设置里的 Setup wizard。
3. 填写远程数据库信息。
4. 测试连接并检查数据库配置。
5. 设置加密和同步策略。
6. 生成并复制 Setup URI。

远程数据库填写：

这里要注意：ob_source 不是 Self-hosted LiveSync 固定默认值，而是我当前这套同步库使用的数据库名。

我在服务器上查到当前 CouchDB 里有这些库：

_replicator
_users
ob_blog
ob_job
ob_knowledge
ob_source
obsidiannotes

其中：

• _users 和 _replicator 是 CouchDB 自身使用的系统库，不要删除。
• ob_source 是当前文章里这套 Obsidian 同步链路使用的库。
• 其它 ob_ 开头的库可以理解为不同 Vault 或不同用途的同步库。
• obsidiannotes 是官方示例里常见的库名风格，不代表必须使用它。

** 一个 Vault 建议对应一个独立数据库名。** 这样后续迁移、清理、排查冲突时会更清楚。

填完后先检查数据库配置：

如果提示 CORS、权限或数据库设置有问题，先按向导修复，不要急着同步。

数据库的简单增删查

下面这些命令适合在服务器上执行。先进入部署目录并读取 .env 里的账号密码：

cd /opt/obsidian-livesync
set -a
. ./.env
set +a

查询所有数据库：

curl -u "$COUCHDB_USER:$COUCHDB_PASSWORD" \
  http://127.0.0.1:5984/_all_dbs

查询某个数据库的基本信息：

curl -u "$COUCHDB_USER:$COUCHDB_PASSWORD" \
  http://127.0.0.1:5984/ob_source

新增一个数据库：

curl -X PUT -u "$COUCHDB_USER:$COUCHDB_PASSWORD" \
  http://127.0.0.1:5984/ob_new_vault

删除一个数据库：

curl -X DELETE -u "$COUCHDB_USER:$COUCHDB_PASSWORD" \
  http://127.0.0.1:5984/ob_new_vault

** 删除数据库会直接删除这个 Vault 在远程同步库里的数据。** 执行删除前至少确认三件事：

• 这个库不是当前正在使用的正式同步库。
• 本地 Vault 已经完整备份。
• couchdb-data/ 或整套 /opt/obsidian-livesync/ 已经做过服务器备份。

六、加密和同步策略

我这里采用比较保守的设置：

• 开启端到端加密。
• 开启路径混淆。
• 电脑端作为第一台设备初始化远程数据库。
• 手机端作为第二台设备加入。

这里有三类密码，不要混用：

完成后复制 Setup URI：

Setup URI 包含后续设备接入信息，不要公开保存。我的做法是：临时传给手机，导入完成后删除。

七、手机端加入同步

手机端不要手动逐项填配置，直接用 Setup URI。

流程如下：

1. 手机安装 Obsidian。
2. 安装 Self-hosted LiveSync 插件。
3. 新建一个空 Vault，或先备份已有 Vault。
4. 打开命令面板，执行 Open setup URI。
5. 粘贴电脑端生成的 Setup URI。
6. 输入 Setup URI 密码。
7. 选择作为第二台或后续设备加入。
8. 等待远程数据库同步到手机本地。

如果手机上已有同名库，不建议直接合并。更稳妥的方式是先备份，再用空库从远程拉取。

八、验证流程

配置完不要马上接入正式写作库，先做验证。

客户端验证：

1. 电脑端新建 LiveSync 测试.md。
2. 手机端确认能收到。
3. 手机端修改内容，电脑端确认能同步回来。
4. 插入一张小图片，确认附件能同步。

九、备份与加固

日常使用边界：

• Self-hosted LiveSync 只负责实时同步。
• CouchDB 只做同步中枢，不当最终备份。
• Vault 要定期做本地备份。
• /opt/obsidian-livesync/couchdb-data/ 要定期备份。
• 不要让云盘、Git、LiveSync 同时对同一个 Vault 做实时双向同步。

服务器侧重点备份：

简单备份命令：

cd /opt
tar -czf obsidian-livesync-backup-$(date +%F).tar.gz obsidian-livesync

更稳妥的备份方式是先停容器，再打包：

cd /opt/obsidian-livesync
docker compose down
cd /opt
tar -czf obsidian-livesync-backup-$(date +%F).tar.gz obsidian-livesync
cd /opt/obsidian-livesync
docker compose up -d

这会带来短暂停机，但能降低数据库文件写入中的不一致风险。

十、常见问题

1. 只有服务器 IP，没有域名可以吗？

桌面端测试可以，手机端长期使用不推荐。手机端更适合使用带有效证书的 HTTPS 域名。

2. 手机端同步慢怎么办？

先检查三件事：

• 手机能否访问 HTTPS 地址。
• 插件里的数据库配置检查是否通过。
• 首次同步的附件是否过多。

第一次同步大库会慢一些，后续增量同步会轻很多。

4. 误删文件怎么办？

先暂停继续同步，再从本地备份、服务器备份或 CouchDB 历史中恢复。不要在多台设备上继续反复编辑同一个库。

十一、总结

这套方案最终解决的是一个问题：让 Obsidian Vault 在电脑和手机之间稳定实时同步，同时保持数据仍然属于自己。

我的使用分工是：

• 电脑端负责长文写作和结构整理。
• 手机端负责查看、临时补充和碎片记录。
• CouchDB 负责同步中枢。
• nginx 负责 HTTPS 入口。
• 备份系统负责出事后的恢复。

最后记住一句话就够了：

同步负责流动，备份负责恢复。两者分开设计，知识库才真正稳定。

参考来源

• Self-hosted LiveSync 官方中文说明：https://github.com/vrtmrz/obsidian-livesync/blob/main/README_cn.md
• Self-hosted LiveSync 自建服务器文档：https://github.com/vrtmrz/obsidian-livesync/blob/main/docs/setup_own_server.md
• Self-hosted LiveSync 快速配置文档：https://github.com/vrtmrz/obsidian-livesync/blob/main/docs/quick_setup_cn.md