CouchDB + Caddy 服务端部署

本文是 Self-hosted LiveSync 系列的服务端部署篇。完成这篇之后，继续阅读 Self-hosted LiveSync 插件配置与维护。

准备工作

一台已安装 Docker 和 Docker Compose 的 VPS（1G 内存起步，推荐 2G）
一个已解析到该 VPS 的域名，且 VPS 上已单独安装 Caddy，80、443 端口可用

第一步：创建目录结构和配置文件

当前 VPS 使用 ~/docker/couchdb，其中 data 存放数据库，local.ini 放在 couchdb 目录根部：

mkdir -p ~/docker/couchdb/data

创建 CouchDB 配置文件：

nano ~/docker/couchdb/local.ini

写入以下内容：

[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"

[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

几个关键点：

single_node=true：单节点部署时自动创建系统数据库
enable_cors 要放在 [chttpd]；origins 是 LiveSync 官方示例使用的三个来源
max_http_request_size 调大，避免大批量同步请求被截断

第二步：启动 CouchDB

创建 compose.yml：

nano ~/docker/couchdb/compose.yml

写入以下内容，替换用户名和密码：

services:
  couchdb:
    image: couchdb:3
    container_name: couchdb-livesync
    environment:
      - COUCHDB_USER=你的用户名
      - COUCHDB_PASSWORD=你的强密码
    ports:
      - "127.0.0.1:5984:5984"
    volumes:
      - ./data:/opt/couchdb/data
      - ./local.ini:/opt/couchdb/etc/local.d/local.ini
    restart: unless-stopped

127.0.0.1:5984:5984 只允许 VPS 本机访问 CouchDB，外部设备通过 Caddy 的 HTTPS 地址连接。couchdb:3 会跟随 CouchDB 3.x 更新；升级前先备份 ~/docker/couchdb/data。如果容器提示数据目录无写入权限，运行 sudo chown -R 5984:5984 ~/docker/couchdb/data 后重启。

启动服务：

cd ~/docker/couchdb
docker compose up -d

第三步：配置 VPS 上的 Caddy

在现有 /etc/caddy/Caddyfile 中添加一个站点块：

couchdb.xcz.life {
    reverse_proxy 127.0.0.1:5984
}

这个域名直接转发到 CouchDB，Caddy 会自动申请并续期 HTTPS 证书。

检查配置并重新加载：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

第四步：验证服务

浏览器打开 CouchDB 登录地址，使用 Compose 中设置的 CouchDB 用户名和密码登录。未登录时要求输入账号密码（HTTP 401）是正常的；登录后能进入管理界面，说明 HTTPS、反向代理和账号可用。接下来用 LiveSync 自带的连接测试检查数据库和 CORS。

如果网页显示 502，先在 ~/docker/couchdb 目录运行 docker compose ps 检查 CouchDB 容器是否运行；容器已停止时运行 docker compose up -d。

服务端部署完成，接下来前往 Self-hosted LiveSync 插件配置与维护配置 Obsidian 插件。