Obsidian 自建LiveSync同步服务器配置指南 (CouchDB + Caddy)

Obsidian-self-hosted-liveSync

zifeng 收录于类别 Doc

2026-03-15 2026-03-15 约 2113 字预计阅读 5 分钟次阅读条评论

整理了基于 CouchDB + Caddy + Docker Compose 的 Obsidian 多端同步方案。这套配置能够实现全自动 SSL 证书申请、安全的反向代理以及接近官方案装的实时同步体验。

为什么使用这套方案：

1. 完全免费（前提是你有自己的公网服务器和带解析域名）
2. 效果最接近官方 Obsidian Sync 那样**实时、丝滑、无感**的同步体验
3. 数据完全自主控制，不用担心官方跑路
4. 配置可以导出二维码或者链接，多端部署十分方便

工作原理：

1. 在你的公网服务器上通过 Docker 部署一个 CouchDB 数据库。
2. 在两台 PC 和 iOS 手机的 Obsidian 中安装社区插件 `Self-hosted LiveSync`。
3. 将插件连接到你的 CouchDB 数据库。

优点：

1. 真·实时同步：几乎在你敲下字符的瞬间，其他设备端就会同步更新，体验极其流畅。
2. 端到端加密：插件支持对传输内容进行加密，即使服务器被黑，笔记内容也不会泄露。
3. 冲突处理优秀：由于是基于数据库的块级同步，多设备同时编辑的冲突处理比网盘同步好得多。

难点：

1. IOS端强制https访问，也就是说必须要有SSL证书，或者设置反向代理
2. CORS配置是个大坑

0. 准备工作

服务器：具有公网 IP 的 Linux 服务器（本例使用阿里云轻量应用服务器）。
域名：已解析至服务器 IP 的域名（本例使用 zarchi.top）。
环境：已安装 Docker 及 Docker Compose。

1. 清理旧环境

在部署新方案前，需停止并删除之前手动运行的容器，以释放端口和名称。

Bash

1
2
3
4


# 停止旧容器
sudo docker stop couchdb
# 删除旧容器（挂载的数据不会丢失）
sudo docker rm couchdb

2. 建立目录结构

建议将所有配置文件统一管理，方便后续备份。

Bash

1
2


mkdir -p ~/obsidian-sync
cd ~/obsidian-sync

3. 配置文件编写

3.1 编写 Caddyfile

Caddy 将负责处理 HTTPS 流量并自动申请证书。在此目录下创建 Caddyfile：

代码段

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


obsidian.zarchi.top {
    # 将接收到的请求转发给内网的 CouchDB 容器（5984端口）
    reverse_proxy couchdb:5984

    # ---------------- CORS 跨域规则配置区 ----------------
    
    # 定义一个名为 allowedOrigin 的匹配器（Matcher）
    # 作用：识别请求的来源（Origin）是否属于我们信任的 Obsidian 客户端
    # - app://obsidian.md : iOS/Android 移动端 Obsidian 的特征 Origin
    # - http://localhost : 桌面端可能使用的 Origin
    # - capacitor://localhost : 某些基于 Capacitor 打包的移动端特有 Origin
    @allowedOrigin expression `{http.request.header.Origin}.matches('app://obsidian.md') ||
                        {http.request.header.Origin}.matches('http://localhost') ||
                        {http.request.header.Origin}.matches('capacitor://localhost')
        `
        
        # 如果请求来源匹配上面的规则，动态返回对应的 Access-Control-Allow-Origin 头
        # 解释：因为开启了 Credentials（凭证验证），W3C 规范禁止 Origin 使用通配符 "*"。
        header ?Access-Control-Allow-Origin {http.request.header.Origin}
        
        # 允许客户端携带认证凭证（即账号密码/Token，LiveSync 插件必须开启此项）
        header ?Access-Control-Allow-Credentials "true"
        
        # 统一设置其他必要的 CORS 响应头
        header {
            # 允许的 HTTP 方法（读、写、修改、删除、预检）
            Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
            # 允许客户端发送的自定义请求头（内容类型、授权信息）
            Access-Control-Allow-Headers "Content-Type, Authorization"
            # 预检请求的缓存时间（86400秒 = 24小时），避免频繁发 OPTIONS 请求，提升同步速度
            Access-Control-Max-Age 86400
        }

    # ---------------- 预检请求 (Preflight) 拦截区 ----------------
    
    # 专门捕捉来自移动端 Obsidian 的 OPTIONS 预检请求
    @cors_preflight {
        method OPTIONS
        header Origin app://obsidian.md
    }
    
    # 拦截到上述请求后，直接由 Caddy 返回 "204 No Content" 状态码
    # 解释：不需要把这个试探性的请求发给 CouchDB 去处理了，Caddy 直接放行，极大降低了 iOS 端的同步延迟和握手失败率。
    handle @cors_preflight {
        respond "OK" 204
    }
}

3.2 编写 docker-compose.yml

整合数据库与代理服务。在此目录下创建 docker-compose.yml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


version: '3.8'

services:
  couchdb:
    image: couchdb:latest
    container_name: couchdb
    restart: always
    environment:
      - COUCHDB_USER=admin
      - COUCHDB_PASSWORD=xxx # 你的强密码
    volumes:
      # 映射之前已存在的数据目录，实现数据迁移
      - /home/admin/couchdb/data:/opt/couchdb/data
      - /home/admin/couchdb/etc:/opt/couchdb/etc/local.d
    expose:
      - "5984"

  caddy:
    image: caddy:latest
    container_name: caddy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy_data:/data
      - ./caddy_config:/config
    depends_on:
      - couchdb

4. 启动与验证

4.1 启动服务

Bash

1

sudo docker compose up -d

4.2 检查状态

运行 sudo docker ps 确保两个容器均为 Up 状态。
访问 https://obsidian.zarchi.top/_utils，若能看到 CouchDB 管理界面且浏览器显示“小锁”图标，说明 HTTPS 配置成功。

5. CouchDB 内部初始化 (仅需一次)

创建数据库：点击 Create Database，命名为 obsidian_sync（类型选 Non-partitioned）。
配置 CORS：编写couchdb预设规则

编写CORS规则，在首次运行couchdb之后更改/obsidian-sync/couchdb/etc/docker.ini

更改以下项：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


# ---------------- 数据库底层 CORS 配置 ----------------
[cors]
# 明确告诉数据库：接受来自以下这几个客户端 Origin 的读写请求
origins = app://obsidian.md,capacitor://localhost,http://localhost,https://localhost
# 允许接收包含账号密码/Token 的请求
credentials = true
# 允许接收的请求头字段
headers = accept, authorization, content-type, origin, referer
methods = GET, PUT, POST, HEAD, DELETE
max_age = 3600

# ---------------- HTTP 服务配置 ----------------
[httpd]
# 核心开关：在数据库层面全局开启跨域资源共享（CORS）支持
enable_cors = true
# 当客户端未登录或验证失败时，返回 401 状态码，并提示使用 Basic 模式进行弹窗验证
WWW-Authenticate = Basic realm="couchdb"

修改大小限制：
- 进入 Configuration。
- 搜索并修改 max_http_request_size 为 4294967296 (4GB)。

完成后记得重启caddy和couchdb容器：

1
2


sudo docker compose restart caddy
sudo docker compose restart couchdb

6. 客户端配置 (Obsidian 插件)

在所有终端（PC/iOS）安装 Self-hosted LiveSync 插件并配置：

参数	配置值
Remote Type	CouchDB
URI	`https://obsidian.zarchi.top`
Username	admin
Password	xxx
Database	obsidian_sync

提示：建议在第一台设备配置好后，使用插件内置的 “Copy current setup string” 功能，在其他设备直接 “Import” 即可实现一键配置。

常见问题排查

无法访问域名：请检查云服务器安全组是否放行了 80 和 443 端口。
iOS 连接失败：确保 URI 以 https:// 开头。如果刚解析完域名，可能需要几分钟等待 DNS 生效及证书申请。
DNF 报错：若系统提示 couchdb 仓库 404，请删除 /etc/yum.repos.d/couchdb.repo 并执行 sudo dnf clean all。