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


整理了基于 **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

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

---

## 2. 建立目录结构

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

Bash

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

---

## 3. 配置文件编写

### 3.1 编写 Caddyfile

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

代码段

```json
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`：

```YAML
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

```
sudo docker compose up -d
```

### 4.2 检查状态

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

---

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

登录 Fauxton 后台（`/_utils`）进行以下设置：

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

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

更改以下项：

```TOML
# ---------------- 数据库底层 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"
```
        
3. **修改大小限制**：
    
    - 进入 `Configuration`。
        
    - 搜索并修改 `max_http_request_size` 为 `4294967296` (4GB)。
        
完成后记得重启caddy和couchdb容器：

```bash
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`。