42_124/CT124_ObsidianLiveSync操作手冊_20260710.md

CT124 Obsidian LiveSync(自架 CouchDB 同步後端)— 操作手冊

主機:CT124（192.168.42.124，Ubuntu 24.04 LXC）　|　位置:/opt/livesync 用途:給 obsidian-livesync 外掛用的自架即時同步後端(CouchDB),多裝置同步 Obsidian vault

---

一、基本資訊

• 版本:CouchDB 3.5（couchdb:3.5,實跑 3.5.2)。obsidian-livesync 外掛本身裝在各裝置的 Obsidian「社群外掛」,不在這台。
• 容器:livesync_couchdb(restart: unless-stopped,network livesync_default)
• 埠:5984 → 5984(僅 LAN,純 HTTP,無對外、不走 NPM)
• 資料庫(給 Obsidian 用):obsidiandb;系統 DB _users/_replicator/_global_changes 已建
• 帳密:CouchDB 管理員 livesync / 密碼在 /opt/livesync/.env(COUCHDB_PASSWORD,亦存密碼管理器)
• 未掛 Watchtower:DB 不做自動更新,避免主版本跳動弄壞資料;更新一律手動(見四)。
• 官方:https://github.com/vrtmrz/obsidian-livesync　|　CouchDB 設定文件:docs/setup_own_server.md

二、操作

cd /opt/livesync
docker compose up -d                          # 啟動 / 套用設定
docker compose ps
docker compose logs -f couchdb
curl -sf http://127.0.0.1:5984/_up && echo OK  # 健康檢查

三、Obsidian 外掛設定(各裝置)

1. Obsidian → 設定 → 社群外掛 → 搜尋 Self-hosted LiveSync → 安裝並啟用。
2. 外掛設定用 Setup wizard / Remote Database,填:
   • URI:http://192.168.42.124:5984(內網) 　或跨網段經 Headscale tailnet:http://ip-192-168-42-124.internal.lotimmy.com:5984
   • Username / Password:見 /opt/livesync/.env
   • Database name:obsidiandb
   • End-to-End Encryption:建議開啟並設 passphrase(資料在 CouchDB 內即為密文;各裝置要填同一組 passphrase)。
3. 先在一台把 vault 推上去(Initialize / Rebuild everything),其餘裝置再 Fetch 拉下來。

四、資料與備份 / 更新

項目	位置
CouchDB 資料	./data(→ 容器 /opt/couchdb/data)
CouchDB 設定(持久化)	./local.d/docker.ini(REST 改的設定寫在這)
帳密	./.env

# 備份(檔案層,停服務較保險)
cd /opt/livesync && docker compose stop \
  && tar -czf livesync-data-$(date +%F).tar.gz data local.d .env docker-compose.yml \
  && docker compose start

# 更新(手動;先確認有近期備份)
cd /opt/livesync
# 視需要改 docker-compose.yml 的 image tag,再:
docker compose pull && docker compose up -d

obsidian-livesync 長期使用會累積歷史修訂,DB 會膨脹。在外掛內定期執行 Compact database 或 Rebuild everything 可回收空間。

五、初始化設定(重建時參考)

新容器起來後,曾對 CouchDB 套用 obsidian-livesync 要求的參數(node _local),重建時照跑:

cd /opt/livesync; set -a; . ./.env; set +a
COUCH=http://127.0.0.1:5984; AUTH="$COUCHDB_USER:$COUCHDB_PASSWORD"
for db in _users _replicator _global_changes; do curl -s -u "$AUTH" -X PUT "$COUCH/$db"; done
put(){ curl -s -u "$AUTH" -X PUT "$COUCH/_node/_local/_config/$1" -H "Content-Type: application/json" -d "$2"; }
put chttpd/require_valid_user '"true"'
put chttpd_auth/require_valid_user '"true"'
put httpd/enable_cors '"true"'
put chttpd/enable_cors '"true"'
put chttpd/max_http_request_size '"4294967296"'
put couchdb/max_document_size '"50000000"'
put cors/credentials '"true"'
put cors/origins '"app://obsidian.md,capacitor://localhost,http://localhost"'
curl -s -u "$AUTH" -X PUT "$COUCH/obsidiandb"

驗證:匿名 curl :5984/obsidiandb 應回 401,帶帳密應回 200。

六、注意事項

• 僅 LAN、純 HTTP:密碼以明文在網路上傳輸,只在信任的內網/Headscale tailnet 使用。務必在外掛開啟 E2E 加密,vault 內容才不會以明文落地 CouchDB。
• 手機同步的坑:Obsidian 手機版要求後端有「有效 SSL 憑證」,純 HTTP 或自簽多半連不上。
  • 本台 Tailscale 接的是自架 Headscale(tailnet 網域 internal.lotimmy.com),不支援 tailscale cert/tailscale serve --https(無憑證簽發)。因此桌面版可直接用(HTTP over LAN/tailnet),手機版無法只靠 tailnet 走通。
  • 要支援手機,需把 :5984 掛到 NPM 反代 + 真實憑證的網域(如 couchdb.lotimmy.com)——這會讓服務對外,與目前「僅 LAN」的取捨相反,要時再開。NPM 反代需 client_max_body_size 放大、關 proxy_buffering。
• 不要把 couchdb:3.5 改成 :latest 自動更新:CouchDB 主版本升級可能需要遷移,DB 應手動、有備份地升。
• 這台的 Docker 若掛,連鎖影響見 CT124_故障復原_20260529.md;但本服務僅 LAN、不經 NPM,不受 443/NPM 影響。