Fast Note Sync¶
概述¶
Fast Note Sync（簡稱 FNS）是 Synto 與 OLW 兩個方案共用的 Vault 同步服務，專為 Obsidian 類筆記庫提供低延遲、可離線的同步能力。與傳統檔案同步工具不同，FNS 不單傳送檔案內容，還會追蹤變更順序、保留同步歷史，並處理衝突版本。整個服務以單一 Docker 容器運行，適合部署於私有雲或邊緣節點，亦可借助 Cloudflare Tunnel 安全地暴露給互聯網上的客戶端。
架構¶
FNS 架構主要分為四層：API 閘道、同步引擎、元數據儲存及檔案儲存。API 閘道同時提供 REST 與 WebSocket 兩種接入點：REST 用於登入、取得 Vault 清單及版本回溯；WebSocket 則負責即時推送變更，讓已連線的 Synto/OLW 客戶端在毫秒級內收到更新。
同步引擎是服務的核心，它會比對本地與遠端檔案狀態，以 checksum 及 mtime 判斷差異，並將每次變更以交易形式寫入 SQLite 及檔案系統。元數據儲存使用 SQLite，路徑由 FNS_STORAGE 指定；檔案本體則存放於掛載的 Docker Volume。從本機 container inspect 的輸出可見，實際容器同時掛載了 fns_vault 與 fns_metadata 兩個 volume，官方鏡像明確區分資料用途。
網絡層面，容器接入了 cf_network，並無對外開放連接埠；所有對外流量均由 Cloudflare Tunnel 接管，服務本身毋須直接面對公網，同時可獲得 TLS 終止、存取日誌及基本 DDoS 防護。在 cf_network 內，其他容器以服務名稱 fast-note-sync 互相存取，IP 由 Docker 動態分配，不建議依賴固定 IP。
部署¶
官方鏡像為 haierkeys/fast-note-sync-service:latest。由於原本預期的 docker-compose.yml 未有收錄，現場部署以 docker container inspect 的實際資料為準，容器相關參數重點如下：
- 鏡像：
haierkeys/fast-note-sync-service:latest - 網絡：
cf_network（bridge 類型） - 掛載：
fns_vault:/data/vault、fns_metadata:/data/db - 重啟策略：
unless-stopped
若需要由零開始部署，可參考以下指令（按實際環境調整）：
docker run -d --name fast-note-sync \
--network cf_network \
-v fns_vault:/data/vault \
-v fns_metadata:/data/db \
-e FNS_JWT_SECRET="$(openssl rand -hex 32)" \
-e FNS_LOG_LEVEL=info \
haierkeys/fast-note-sync-service:latest
部署完成後，在 cf_network 內以 curl http://fast-note-sync:PORT/healthz 確認健康狀態。容器實際監聽連接埠需以 container inspect 的 Config.ExposedPorts 或 NetworkSettings.Ports 為準；Cloudflare Tunnel 的 ingress 規則必須對應相同連接埠，並以服務名稱轉發。
配置¶
FNS 支援環境變量及設定檔兩種配置方式；小型部署多以環境變量為主。常用項目如下：
FNS_JWT_SECRET：API 認證密鑰，未設定時服務會拒絕啟動。FNS_LOG_LEVEL：日誌詳細度，生產環境建議info，偵錯時用debug。FNS_GIT_SYNC：設為true時，每次同步會自動提交至預設 Git 儲存庫，提供額外版本追蹤。FNS_STORAGE：SQLite 資料庫路徑，例如/data/db/fns.db。
配置修改後需重建容器。請注意，FNS_JWT_SECRET 一旦變更，所有已登入的客戶端都必須重新認證。
維運與監控¶
日常維運應留意以下事項：
- 日誌：使用
docker logs -f fast-note-sync監察同步過程，可加--since 5m過濾近期記錄。 - 健康狀態：鏡像內置
/healthz端點，可交給 cloudflare-tunnel 作為被動健康檢查。 - 更新流程：先
docker pull新鏡像，再以相同 volume 及網絡參數重建容器。 - 磁碟使用：Vault 目錄在大量編輯下可能快速膨脹，建議定期清理
.journal及 Git 物件。
監控方面，可將容器 CPU、記憶體及網絡指標送往 prometheus，再以 grafana 繪製儀表板。SQLite 檔案大小與 Vault 目錄增長趨勢亦應納入容量規劃。
備份 SQLite 時不應直接複製檔案，建議使用：
sqlite3 /data/db/fns.db ".backup '/backup/fns.db'"
Vault 檔案本體則可用 rsync 或 borg 進行定期備份。
常見問題¶
客戶端無法連線：先檢查 Cloudflare Tunnel 的 ingress 規則是否正確，再確認容器仍連接至 cf_network。
同步衝突頻繁：常見於多個用戶端離線過久。FNS 只保留衝突副本，不會自動合併，需人手處理。
容器啟動即退出：多數與 FNS_JWT_SECRET 遺漏或 SQLite 路徑沒有寫入權限有關，查看 docker logs 即可定位。
固定 IP 問題：因 compose 檔案不存在，容器 IP 由 Docker 動態分配；如確有需要，可在 docker run 時手動指定 --ip，但一般建議依賴 Docker DNS 以服務名稱通訊。
相關鏈接¶
來源¶
自動生成（2026-08-19 容器覆蓋率補完第二批）