Secure Obsidian LiveSync Server Setup
Deploy a self-hosted Obsidian LiveSync server (CouchDB in Docker behind a Cloudflare Tunnel with zero inbound ports), covering upstream provisioning, Setup URI generation with mandatory end-to-end encryption, a post-deploy security audit, and a tested backup/restore procedure. Use when building a private Obsidian sync backend with no exposed ports.
Obsidian LiveSync 服务端部署
Overview (EN). Stand up a private Obsidian LiveSync backend with no exposed ports: CouchDB bound to loopback inside Docker, reached only through an outbound-only Cloudflare Tunnel, with mandatory end-to-end encryption. Includes upstream provisioning (pinned release), Setup URI generation, a post-deploy security audit, and a backup/restore procedure you actually rehearse. The rest of this document is in Chinese.
架构(推荐形态,安全最佳实践)
CouchDB 容器只绑 127.0.0.1:5984 → cloudflared Tunnel(纯出站,零入站端口)→ CF 边缘 HTTPS 域名。客户端用 Setup URI 一键导入,端到端加密(passphrase + 路径混淆)必须开。
E2E 加密是硬性要求,不是可选项:不开启时数据库里是明文笔记,而隧道运营商(Cloudflare)在边缘终止 TLS,能看到回源明文。
部署步骤
-
目录与权限(uid 必须 5984,否则容器起不来):
bash sudo mkdir -p /opt/obsidian-livesync/{couchdb-data,couchdb-etc} sudo chown -R 5984:5984 /opt/obsidian-livesync/couchdb-{data,etc} sudo chmod 750 /opt/obsidian-livesync路径可换,但下面所有命令要跟着换。
-
凭证:
COUCHDB_USER、COUCHDB_PASSWORD(openssl rand -hex 24生成)写进你已在用的环境变量文件(Hermes 用hermes config env-path给出的文件),权限 600;聊天/脚本/仓库不硬编码。 -
起容器(固定次版本号,避免
latest突然跨大版本;端口必须带127.0.0.1:前缀,否则等于把数据库发布到所有网卡):bash docker run --name couchdb-for-ols -d --restart always -u 5984:5984 \ -e COUCHDB_USER=$COUCHDB_USER -e COUCHDB_PASSWORD=$COUCHDB_PASSWORD \ -v /opt/obsidian-livesync/couchdb-data:/opt/couchdb/data \ -v /opt/obsidian-livesync/couchdb-etc:/opt/couchdb/etc/local.d \ -p 127.0.0.1:5984:5984 couchdb:3.5宿主有 compose 插件时可写成单服务 compose 文件,映射同样是
127.0.0.1:5984:5984;上面的 docker run 在无 compose 的旧版 Docker(如 20.10)上也能用。-p 127.0.0.1:5984:5984是显式回环绑定,不依赖daemon.json里的任何全局设置——因此本流程不会改动 Docker 守护进程配置,也不会影响这台机器上的其他容器。继续前先确认只监听回环:
bash ss -tlnp | grep 5984 # 期望 127.0.0.1:5984,不应出现 0.0.0.0:5984 -
上游脚本初始化(LiveSync 自带 provisioning;固定 release tag,先下载、审阅、再执行;需要 Deno,没有则装发行版包,或下载
deno.land/install.sh审阅后执行):bash curl -fsSL -o /tmp/couchdb-init.sh \ https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/1.0.42/utils/couchdb/couchdb-init.sh less /tmp/couchdb-init.sh # 审阅:确认只读写 127.0.0.1:5984、只动 obsidiannotes sha256sum /tmp/couchdb-init.sh # 记录基线,日后可用于比对(macOS 用 shasum -a 256)确认无误后再执行(同一 shell 会话内设置变量,避免口令进入历史):
bash export hostname=http://127.0.0.1:5984 username=$COUCHDB_USER password=$COUCHDB_PASSWORD database=obsidiannotes bash /tmp/couchdb-init.sh # 成功标志: CouchDB provisioning completed. rm -f /tmp/couchdb-init.sh验证(交互式终端,curl 单独提示输入口令,不把口令放进进程参数):
bash curl -u "$COUCHDB_USER" http://127.0.0.1:5984/_up # 期望 {"status":"ok"} curl -u "$COUCHDB_USER" http://127.0.0.1:5984/_all_dbs # 应含 obsidiannotes无人值守/自动化场景改用权限受限的
~/.netrc(chmod 600)或.curlrc里的--user,不要用curl -u user:pass:变量展开后的值会短暂出现在/proc/<pid>/cmdline,同机其他用户可读。curl 官方文档对此有明确提示。 该脚本会开启require_valid_user、设置 LiveSync 需要的 CORS origins、并建库。 -
Cloudflare Tunnel:
- 装 cloudflared(GitHub release .deb)
cloudflared tunnel login(后台跑,把 URL 给用户浏览器授权,cert.pem 落~/.cloudflared/;URL 有效期短,尽快打开)cloudflared tunnel create obsidian-livesync- 写
~/.cloudflared/config.yml:ingresshostname: <域名>→service: http://127.0.0.1:5984,兜底http_status:404(必须留,否则隧道拒绝启动) credentials-file指向tunnel create实际写出的 JSON;cloudflared service install会把配置和凭证复制到/etc/cloudflared/,手写配置时路径对不上是"隧道起不来"的常见原因cloudflared tunnel route dns obsidian-livesync <域名>(自动加 CNAME)cloudflared service install && systemctl enable --now cloudflared,日志确认 4 条Registered tunnel connection
-
生成 Setup URI(E2E passphrase 生成后也存为
LIVESYNC_PASSPHRASE,并让用户存进密码管理器):bash export hostname=https://<域名> username=$COUCHDB_USER password=$COUCHDB_PASSWORD \ database=obsidiannotes passphrase=$LIVESYNC_PASSPHRASE deno run --allow-env --allow-net \ https://raw.githubusercontent.com/vrtmrz/obsidian-livesync/1.0.42/utils/setup/generate_setup_uri.ts输出的
uri_passphrase只显示一次。Setup URI 本身等同密码:通过不长期留存的渠道交付( spoiler 遮罩)。加第二台设备改为在已配好的设备上 Generate Setup URI,不要复用第一个。
安全审计清单(部署后必查)
ss -tlnp:公网监听只应包含你明确开放的端口;CouchDB 必须是127.0.0.1:5984- 可选加固:
/etc/docker/daemon.json设置"ip": "127.0.0.1"。Docker 默认把发布端口绑到0.0.0.0,这条能兜底防止将来别的容器误发布;但它影响这台机器上所有容器,属全局改动,只在清楚后果时启用。本流程不依赖它。 - 无凭证访问域名 → 401(
require_valid_user=true) _config/cors.origins仅app://obsidian.md,capacitor://localhost,http://localhost;出现*表示任何网页都能在浏览器里直接连这个库~/.cloudflared/目录 700、cert.pem600、tunnel json 400- Erlang 端口 4369/9100 不发布到宿主机
- 信任点说明:CF 边缘终止 TLS 可见明文回源,但 LiveSync E2E 加密已抵消;反过来说,拿到宿主访问权 + CouchDB 口令 = 拿到全部数据
自动备份
CouchDB 的 .couch 文件追加写入,允许在运行期间复制;但官方推荐的顺序是先备份索引、再备份数据库文件,配置目录单独处理,并且普通 tar 不等于"已验证可恢复"。下面按这个顺序拆成三份:设计文档(索引定义)→ 数据目录 → 配置目录。
先建目录并记录索引定义(索引可由设计文档重建,备份定义即可,不必复制索引文件):
BK=/var/backups/livesync-$(date +%F)
mkdir -p "$BK"
curl -u "$COUCHDB_USER" http://127.0.0.1:5984/obsidiannotes/_design_docs > "$BK/design-docs.json"
再复制数据目录并单独打包配置(couchdb-etc 里是 require_valid_user、CORS、admin 等本地配置,恢复时漏掉会得到一个"能启动但行为不对"的库):
tar -C /opt/obsidian-livesync -czf "$BK/couchdb-data.tar.gz" couchdb-data
tar -C /opt/obsidian-livesync -czf "$BK/couchdb-etc.tar.gz" couchdb-etc
sha256sum "$BK"/*.tar.gz "$BK"/*.json > "$BK/SHA256SUMS"
恢复(必须在目标服务停止后执行)
docker stop couchdb-for-ols
# 先把现有数据目录移开,不要就地覆盖——恢复失败时需要能退回
mv /opt/obsidian-livesync/couchdb-data /opt/obsidian-livesync/couchdb-data.bak-$(date +%s)
tar -C /opt/obsidian-livesync -xzf "$BK/couchdb-data.tar.gz"
tar -C /opt/obsidian-livesync -xzf "$BK/couchdb-etc.tar.gz"
chown -R 5984:5984 /opt/obsidian-livesync/couchdb-{data,etc}
docker start couchdb-for-ols
恢复后逐项核对,而不是只看容器起来了:_up 返回 ok;_all_dbs 含 obsidiannotes;文档数与备份前一致;用已配置客户端做一次写入/同步,确认 E2E 解密正常(索引缺失会表现为查询变慢而非报错,容易被忽略)。确认无误后再删 couchdb-data.bak-*。
恢复流程要实测一次——没演练过的备份只是猜测。异地副本用宿主机既有的工具(rclone / restic / Borg)推送;加密副本的口令存在"被备份机器之外"。调度器用系统 cron、systemd timer 或 agent cron 都行,关键是有异地副本和定期恢复演练,而不是具体用哪个调度器。
多远程共存(客户端概念)
插件支持一库多远程档案(Connection settings → Saved connections,连接串 sls+https:// / sls+s3:// / sls+p2p://),但同时只有一个激活主远程;第二远程(如 R2)只能切换后跑 one-shot replication,非自动双写。自动双份用上面的服务端备份更省心。
坑
-p 5984:5984不带127.0.0.1:前缀 = 把数据库发布到公网。隧道会让这个错误难以察觉:一切照常工作。- 不开 E2E 加密,等于把明文笔记留在你可能不完全掌控的宿主上。
- provisioning 脚本以固定 tag 下载到
/tmp、审阅后再执行。升级版本时重新审阅并对比sha256sum。 couchdb:latest迟早会跨大版本。固定couchdb:3.5(或有意升级),升级后重跑安全审计。- 无 compose 的旧版 Docker(如 20.10)用 docker run 即可,不必先装 compose 插件。
- 前台执行
docker compose up/docker run(不带-d)会被监管进程当作长跑任务杀掉;用-d或进程管理器的后台模式。 - tunnel login 的授权 URL 有效期短,让用户尽快打开。
couchdb-init.sh输出大量 npm Download 行属正常,看结尾 "provisioning completed"。- 交付 Setup URI 时不要走会长期留存的渠道:它包含数据库口令和 E2E passphrase。
License and provenance
部署步骤为原创文字。初始化和 Setup URI 脚本由
vrtmrz/obsidian-livesync(MIT)
提供,本 skill 只调用、不内嵌。CouchDB、cloudflared、Deno 各自遵循其自身许可。
本文件以 MIT-0 发布(ClawHub 对所有已发布 skill 采用的许可),license: 字段
在直接读 git 仓库时同样成立。
Related skills
- Downloads
- 174All time
- Security audit
- Review
- Last updated
- 3w ago
- Current version
- v0.1.1
- License
- MIT-0
