Obsidian Sync

💡 快速導航

• 🎯 我為什麼自架同步
• 🧱 整體架構
• 🗄️ CouchDB 與 LiveSync
• 🖥️ Obsidian Client 容器
• 🌐 Quartz 發布邊界
• 💬 Artalk 留言系統
• 💾 備份與還原
• ⚠️ 維運原則與安全邊界
• Home Lab 總覽

這套 Obsidian Sync 不是官方 Obsidian Sync，而是用 Self-hosted LiveSync + CouchDB 來同步我的 Obsidian vault。它同時和 Quartz 發布、留言系統放在同一個 compose stack 裡，形成「寫作、同步、發布、留言」的一整套工作流。

核心原則是：同步資料和公開發布要分開看待。CouchDB 和完整 vault 是私有同步資料；Quartz 只讀取明確放進 host 與 host_en 的公開子樹。

Important

這篇是公開筆記，所以不會公開 CouchDB 帳號密碼、LiveSync URL、vault ID、plugin 設定、同步 token、.env、內網 IP、domain、Artalk 設定、留言資料庫或任何備份檔內容。

---

🎯 我為什麼自架同步

筆記是長期資料，不只是 App 設定

Obsidian vault 對我來說不是單純的文件資料夾，而是長期累積的知識庫、Home Lab 文件、發文草稿和操作紀錄。如果只存在單一裝置，風險太高；如果完全依賴外部同步服務，又少了一層可控性。

自架同步讓我可以：

• 多裝置同步同一個 vault
• 保留資料主控權
• 把同步後的公開內容接到 Quartz 發布流程
• 用自己的備份策略保護 vault 與同步資料庫

同步和發布是兩件事

同步的目標是讓自己的裝置都有完整筆記；發布的目標是只把可公開內容轉成網站。

這兩個邊界必須清楚，否則最危險的不是同步失敗，而是把不該公開的內容發布出去。

---

🧱 整體架構

flowchart TD
    DEV[Obsidian Devices] --> LS[Self-hosted LiveSync]
    LS --> CDB[CouchDB<br/>obsidian-livesync]
    OC[Obsidian Client<br/>container] --> CDB
    OC --> VAULT[(Obsidian Vault)]

    VAULT --> CH[host<br/>Chinese public subtree]
    VAULT --> EN[host_en<br/>English public subtree]
    CH --> QZCN[Quartz Chinese Site]
    EN --> QZEN[Quartz English Site]
    QZCN --> NPM[Nginx Proxy Manager]
    QZEN --> NPM
    QZCN --> ART[Artalk Comments]

Stack 摘要

元件	Container	Image	角色
CouchDB	obsidian-livesync	couchdb:latest	LiveSync 後端資料庫
Obsidian Client	obsidian-client	linuxserver/obsidian:latest	容器化 Obsidian client / Web UI
Quartz 中文站	obsidian-quartz	ghcr.io/jackyzha0/quartz:latest	發布 host 公開子樹
Quartz 英文站	obsidian-quartz-en	ghcr.io/jackyzha0/quartz:latest	發布 host_en 公開子樹
Artalk	obsidian-artalk	artalk/artalk-go:latest	Quartz 留言系統

Note

這套 stack 目前多數 image 使用 latest。這對快速更新方便，但對可重現還原比較弱。長期更穩的做法是逐步改成固定版本 tag，並記錄升級前後檢查結果。

---

🗄️ CouchDB 與 LiveSync

CouchDB 是 Self-hosted LiveSync 的同步後端。Obsidian 裝置透過 LiveSync plugin 和 CouchDB 同步，CouchDB 保存同步所需的資料庫狀態。

我會保護的資料

• CouchDB data volume
• CouchDB config volume
• LiveSync plugin 私有設定
• vault 本體資料

我不會公開的資料

• CouchDB admin 帳號或密碼
• CouchDB hash、salt、cookie、UUID
• .couch database 檔案
• LiveSync URL
• vault ID
• plugin data.json
• 同步密碼、token 或金鑰

LiveSync 相關 log 也不適合直接公開，因為 log 可能包含 vault ID、同步狀態、時間序列和裝置行為線索。

---

🖥️ Obsidian Client 容器

這個 stack 裡也跑了一個容器化 Obsidian client。它的用途是讓 Obsidian 可以在伺服器端持續運作，並透過瀏覽器存取 UI。

容器角色

項目	說明
Image	linuxserver/obsidian:latest
依賴	啟動順序依賴 CouchDB
Config	Obsidian app/plugin 設定
Vault	掛載完整 Obsidian vault
UI	透過瀏覽器存取，不在公開筆記列出實際入口

Obsidian client 的 config、browser cache、local storage、plugin data 都可能包含私有資訊，不應該放進公開筆記或公開備份清單細節。

---

🌐 Quartz 發布邊界

Quartz 和同步服務放在同一個 compose stack，但它們的資料邊界不同。

Full Obsidian Vault
├── host      -> Chinese Quartz site
├── host_en   -> English Quartz site
├── WIP       -> private, not published
├── .trash    -> private, not published
└── .obsidian -> private, not published

Quartz containers 只把公開子樹掛載成 read-only content：

• 中文站讀取 host
• 英文站讀取 host_en

這個設計讓我可以在同一個 vault 裡維護草稿、私有筆記和公開文章，但只有明確放進 publish subtree 的內容會被網站看到。

發布前檢查

• 不連到 WIP/services 等私有筆記
• 不引用 .trash 或舊 log
• 不放實際 domain、IP、帳密、token
• 表格中的 aliased wikilink 要使用 \| 避免 Markdown table 被切欄
• 圖片附件只放已確認可以公開的內容

---

💬 Artalk 留言系統

Artalk 也在同一個 stack 裡，用來提供 Quartz 文章的留言功能。它和 Obsidian sync 本身不是同一件事，但在這套部署中屬於發布工作流的一部分。

Artalk 需要自己的備份範圍：

• config
• database
• logs
• uploaded images

公開筆記不應包含 Artalk raw config、留言資料庫、留言者資訊、email、IP、token、captcha 或 OAuth 相關資料。

---

💾 備份與還原

Obsidian sync stack 的備份不能只看 vault 資料夾。同步資料庫、Obsidian client config、Quartz customization 和留言系統都要分別看待。

需要納入備份的類別

類別	原因
Vault	原始 Markdown、附件、公開與私有筆記
CouchDB data/config	LiveSync 狀態與同步後端
Obsidian config	plugin、theme、workspace 與 client 設定
Compose / .env	啟動方式、volume mapping、環境變數
Quartz config/components/styles	網站客製化，public output 可重建但客製化不可丟
Artalk data	留言資料、設定、上傳圖片

還原時的順序概念

1. 還原 compose 與 volume mapping
2. 還原 CouchDB data/config
3. 還原 Obsidian vault 與 client config
4. 啟動 CouchDB，再啟動 Obsidian client
5. 確認 LiveSync 不產生大量衝突
6. 啟動 Quartz 並確認 host / host_en 發布正常
7. 啟動 Artalk 並確認留言功能正常

Warning

只還原 vault、不還原 CouchDB 狀態，可能導致同步端看到舊狀態或產生衝突。只還原 CouchDB、不還原 vault，也可能造成裝置端和伺服器狀態不一致。這兩者要當成一組來驗證。

---

⚠️ 維運原則與安全邊界

私有資料永遠比發布方便重要

這套系統最容易犯的錯，不是服務跑不起來，而是把私有內容不小心發布出去。因此我會把公開內容集中在 host 與 host_en，避免讓 Quartz 直接掃整個 vault。

不公開 raw config

CouchDB、LiveSync plugin、Obsidian client、Quartz、Artalk、NPM 相關設定都可能包含敏感資訊。公開筆記只描述架構與維運原則，不貼原始設定檔。

更新順序要保守

同步層和發布層都會影響日常使用。升級前我會先確認備份，升級後檢查：

• Obsidian device 是否能同步
• CouchDB 是否正常回應
• Obsidian client 是否可開啟 vault
• Quartz 中文 / 英文站是否重新生成
• Artalk 留言是否還能載入
• NPM / Authelia 入口是否仍正常

---

結論

這套 Obsidian Sync stack 對我來說不只是「筆記同步」。它把個人知識庫、公開 blog、雙語發布和留言系統串成一條工作流。

真正重要的是邊界：CouchDB / LiveSync / vault 是私有同步資料；Quartz 只讀取明確公開的子樹；NPM 和 Authelia 負責入口；備份則要同時保護同步資料、發布設定和留言資料。

延伸閱讀：Home Lab 總覽、Nginx Proxy Manager、Authelia