Obsidian LiveSync 自建同步教程：飛牛 NAS Docker 部署 CouchDB 完整指南

前言

Obsidian 的同步方案有很多種。

最省心的是官方 Obsidian Sync，打開就能用，手機和電腦都照顧得很好。缺點也很直接，它是訂閱制服務，如果你已經有 NAS，可能會覺得每年再為同步付一筆費用有點浪費。

也有人會選擇 iCloud、堅果雲、OneDrive、百度網盤同步空間（中文） 這類網盤同步。它們的優點是上手簡單，缺點是多設備同時編輯時容易出現衝突，移動端體驗也不一定穩定。尤其是 Obsidian 這種由大量 Markdown 文件、配置文件和插件數據組成的資料庫，普通網盤同步經常會遇到延遲、重複文件、配置不同步等問題。

用 Remotely Save 接 WebDAV、S3 或網盤，通常是先準備一個雲端位置，再把同一組連接信息填到每臺設備裡，上手路徑比較清楚。它的體驗很依賴後端服務的穩定性，比如堅果雲這類 WebDAV 服務，頻繁請求時可能遇到接口限制或 503 報錯；換成其他網盤，又可能遇到不同系統支援不一致的問題。設備越多，系統越雜，這些細節越容易被放大。

Self-hosted LiveSync 走的是另一條路。它通過 CouchDB 在多臺設備之間同步改動，不需要把整個 Vault 當成一堆文件交給網盤處理。你可以把 CouchDB 部署在自己的 NAS 上，讓 Mac、Windows、手機都連接到這臺 NAS。它支援端到端加密，同步速度也很快，適合已經有 NAS、願意折騰一點配置的人。

很多人會用 Git 同步 Obsidian，因為它能保留歷史、方便回退，也適合做版本管理和備份。把它放進日常多端寫作以後，commit、push、pull 會變成使用流程的一部分。電腦端還好，到了手機和平板上，配置、性能和衝突處理的成本都會更明顯。LiveSync 更關心多設備持續同步，讓幾臺設備圍繞同一個同步服務交換變化。

這篇文章會用飛牛 NAS 的 Docker 應用來演示。雖然截圖基於飛牛，但只要你的 NAS 支援 Docker，比如群暉、綠聯、威聯通，也可以參考同一套思路。

這套方案不算簡單，它需要你理解 Docker、端口、CouchDB、局域網地址和插件配置。配置錯一步，就可能連接失敗，甚至把某臺設備上的舊數據覆蓋到服務器。因此，正式操作前請先備份你的 Obsidian Vault。

本文會先跑通局域網同步，也就是電腦和 NAS 在同一個網絡下的同步。公網同步、手機端 HTTPS 訪問、FN Connect 這類遠程訪問問題，會放在後面單獨處理。

局域同步

先從最穩定的局域網同步開始。

所謂局域網同步，就是你的電腦、手機和 NAS 都在同一個家裡或辦公室網絡裡。Obsidian 不再把筆記傳到第三方雲盤，而是把數據同步到 NAS 上運行的 CouchDB。Mac、Windows、手機再從這個 CouchDB 讀取和寫入數據。

這個方案的好處是速度很快，也更可控。NAS 在你自己的網絡裡，數據不會經過額外的雲盤服務；LiveSync 還可以開啟端到端加密，即使 CouchDB 裡保存了同步數據，也不能直接讀出你的筆記內容。

Syncthing 更像設備之間的點對點文件同步，適合願意維護設備連接和目錄配對的人。LiveSync 則把 CouchDB 放在中間，Mac、Windows、手機都連到同一個同步中心。部署門檻會更高，但後面接入新設備、檢查同步狀態、判斷數據方向時，路徑會更清楚。

但它的限制也很明顯，只做局域網同步時，設備必須連回同一個網絡。你在外面用手機流量，或者電腦不在家裡的網絡裡，就訪問不到這臺 NAS。後面會單獨討論公網同步和遠程訪問，這一節先把本地同步跑通。

飛牛部署 CouchDB

先打開 fnOS 自帶的 Docker 應用，切換到「鏡像倉庫」。

在搜索框裡輸入 couchdb，找到官方的 couchdb 鏡像。

點擊右側的下載按鈕。標籤保持默認的 latest 就可以。

確認後，飛牛會開始創建下載任務。

下載完成後，切換到「本地鏡像」，找到剛剛下載好的 couchdb。

點擊右側的啟動按鈕，開始創建容器。

容器名稱可以直接寫成 couchdb。

資源限制不用打開，CPU 和內存保持自動即可。

建議勾選「開機自動開啟」，這樣飛牛重啟後，CouchDB 也會自動啟動。

然後點擊「下一步」。

接下來會進入「高級設置」。

這一頁看起來有很多選項，但真正需要我們手動配置的主要是端口設置、存儲位置和環境變量。其他地方保持默認即可。

在配置存儲位置之前，先到飛牛的「文件管理」裡創建 CouchDB 要用的文件夾。

建議路徑放在 docker 文件夾下面，比如：

docker/obsidian-couchdb/

然後在裡面創建兩個子文件夾：

data
local.d

data 用來保存 CouchDB 的數據，local.d 用來保存 CouchDB 的配置文件。

文件夾名稱儘量只用英文、數字和普通短橫線。不要使用中文、空格或複製出來的特殊橫線，否則後面創建容器時可能會出現「參數錯誤：容器的存儲位置」。

回到 Docker 的高級設置，先展開「存儲位置」。

這裡要添加兩條路徑映射：

/docker/obsidian-couchdb/data    -> /opt/couchdb/data
/docker/obsidian-couchdb/local.d -> /opt/couchdb/etc/local.d

左邊是飛牛裡的文件夾，右邊是容器裡的路徑。

這裡不要手動輸入左邊的路徑，請點擊輸入框右側的文件夾圖標，在彈出的文件選擇窗口裡手動點選剛剛創建好的 data 和 local.d 文件夾，這樣最終的路徑才是正確的。

如果手動輸入路徑，很容易因為目錄不存在、短橫線不對或路徑格式不對，導致創建容器時報錯。

接下來準備 CouchDB 的配置文件。

可以先在電腦本地新建一個普通文本文件，把下面這段內容複製進去：

[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"
enable_cors = true

[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

保存後，把文件名改成：

local.ini

注意後綴必須是 .ini，不要保留成 local.ini.txt。

然後把 local.ini 上傳到剛剛創建的 local.d 文件夾裡。

上傳完成後，local.d 裡面應該能看到這個 local.ini 文件。

回到 Docker 的高級設置，展開「環境變量」。

這裡添加兩條環境變量：

COUCHDB_USER=你的用戶名
COUCHDB_PASSWORD=你的強密碼

用戶名可以自己取，密碼建議用一串足夠長的強密碼。不要使用 admin、123456 這類太容易猜到的組合。

端口設置這裡也要檢查一下。

CouchDB 在容器內部默認使用 5984 端口。為了減少後面配置時的混亂，建議本地端口也直接使用 5984：

本地端口：5984
容器端口：5984
協議：TCP

這樣後面訪問的地址就是：

http://飛牛的局域網 IP:5984/_utils

如果你的 NAS 上已經有其他服務佔用了 5984，也可以把本地端口改成別的數字，比如：

本地端口：9100
容器端口：5984
協議：TCP

這種情況下，後面 Obsidian 裡填寫的地址也要跟著改成 http://飛牛的局域網 IP:9100。

重點在於容器端口必須保持 5984。你可以改左邊的本地端口，但不要把右邊的容器端口也改成 9100。

確認頁裡重點檢查幾件事：

• 容器名稱是 couchdb
• 開機自動開啟是「是」
• 存儲位置已經映射到 /opt/couchdb/data 和 /opt/couchdb/etc/local.d
• 環境變量裡已經有 COUCHDB_USER 和 COUCHDB_PASSWORD
• 端口映射的容器端口是 5984

確認無誤後，勾選「創建後啟動」，點擊「創建容器」。

創建成功後，回到 Docker 的「容器」頁面。

如果 couchdb 左側顯示綠色圓點，並且能看到 CPU、內存佔用，就說明 CouchDB 容器已經運行起來了。

到這裡，飛牛上的 CouchDB 服務已經部署完成。

下一步就可以回到 Obsidian，安裝並配置 Self-hosted LiveSync 插件。

在 Mac 上安裝插件

回到 Obsidian，打開「設置」裡的「第三方插件」。

如果你之前沒有打開第三方插件，需要先關閉安全模式，然後進入社區插件市場。社區插件的安裝方式都差不多，如果需要完整流程，可以先看這篇：Obsidian 最新全平臺插件安裝教程。這裡繼續演示和 LiveSync 有關的部分。

在插件市場搜索：

livesync

找到 Self-hosted LiveSync，點擊「安裝」。

安裝完成後，點擊「啟用」。

第一次啟用時，插件可能會彈出翻譯提示。這裡點 OK 就可以，不影響後續配置。

接下來會進入 Self-hosted LiveSync 的初始化嚮導。

這裡選擇「我是第一次進行設置」，然後點擊「是的，我要配置新的同步」。

下一步會讓你選擇連接方式。

這裡不要選 Setup URI。Setup URI 通常是官方腳本或已經配置好的設備生成的一整串連接信息。我們現在是自己在飛牛上手動部署 CouchDB，所以選擇「手動輸入服務器信息」。

選好後，點擊「我知道服務器詳情，讓我手動輸入」。

接下來是端到端加密設置。

建議開啟端到端加密，並設置一個單獨的加密密碼（不是 CouchDB 的登錄密碼）。後面在其他電腦或手機上接入同一個同步庫時，也必須輸入同一個加密密碼。這個密碼一旦忘記，服務器上的數據即使還在也無法解密，建議保存在密碼管理器裡。

往下看，還會看到 Obfuscate Properties 選項。

這個選項的作用是把遠程服務器裡能看到的文件路徑、文件大小、創建時間、修改時間等屬性也做一層混淆。開啟後，即使有人能看到 CouchDB 裡的原始數據，也更難直接看出你的文件結構。

這裡建議勾選。

設置完成後，點擊 Proceed。

接下來選擇服務器類型。

這裡選擇 CouchDB，然後點擊「繼續進行 CouchDB 設置」。

然後填寫 CouchDB 連接信息。

如果你現在只是在 Mac 上測試，可以先使用飛牛的局域網地址，例如：

http://飛牛局域網 IP:5984

比如我的測試地址是：

http://192.168.31.158:5984

這裡會看到一條提醒，說 Obsidian Mobile 只能使用 HTTPS 連接。這一點很重要，但現在我們先把電腦端流程跑通。手機端需要 HTTPS 或其他遠程訪問方案，後面再單獨處理。

下面三項按你在飛牛 Docker 裡設置的 CouchDB 信息填寫：

用戶名：COUCHDB_USER
密碼：COUCHDB_PASSWORD
數據庫名稱：obsidian_db

數據庫名稱可以自己取，但不要使用大寫字母、空格和特殊字符，也不要以下劃線開頭。為了後續教程統一，我這裡使用：

obsidian_db

Use Internal API 先不要勾選。只有遇到瀏覽器跨域問題，並且普通方式無法連接時，再考慮它。

填好後，先點擊 Detect and Fix CouchDB Issues。

如果檢測通過，下方會顯示 All checks passed successfully!。確認通過後，再點擊 Test Settings and Continue。

如果出現下面這種提示，說明連接已經配置成功，插件準備把當前設備裡的庫作為第一份同步數據上傳到服務器。

點擊 Restart and Initialise Server。

隨後可能會出現 Fetch Remote Configuration Failed。

第一次配置一個全新的服務器時，這個提示通常是正常的。因為遠端還沒有任何 LiveSync 配置可讀取。

這裡點擊 Skip and proceed，繼續往下走。

接下來插件會重啟同步流程，右上角會出現一串黑色提示。

這些提示大概會包含：

Local Database Reset
SYNC DATABASE AND STORAGE
遠程數據庫已創建或連接

只要沒有持續報錯，可以繼續等待下一步彈窗。

修復 LiveSync 推薦配置

完成基礎連接後，插件可能會啟動「配置診斷」。

這個診斷會檢查當前庫的 LiveSync 設置是否適合跨設備同步。這裡直接點擊「確定」。

後面會連續出現幾個修復項。建議按插件推薦全部點擊「修復」。三個修復項都處理完後，插件會再次提醒你確認服務器數據。

用當前設備初始化服務器

下面這個窗口表示，插件將刪除服務器上現有的 LiveSync 同步數據，然後用當前設備裡的 Obsidian 庫重新生成一份服務器數據。

如果你是第一次配置一個空的 CouchDB 數據庫，這是正常流程。

但如果這個 CouchDB 裡已經有你正在使用的同步數據，就不要隨便點。因為它會把服務器端原來的同步數據覆蓋掉。

在本教程裡，我們使用的是一個全新的測試庫，所以可以繼續。

這裡需要勾選三個確認項：

• 我知道其他手機或電腦上的更改可能會丟失
• 我知道其他設備需要重新設置同步信息
• 我知道這個動作執行後無法撤銷

下面還會問你是否已經備份。

如果你是在正式庫裡操作，建議先複製整個 Vault 文件夾做一份備份，再選擇「I have created a backup of my Vault」。

如果你和我一樣是在測試庫裡演示，也可以選擇「I understand the risks and will proceed without a backup」。

確認後，點擊 I Understand, Overwrite Server。

隨後可能會出現一個提示，說本機設置和服務器設置略有不同，插件已經用服務器設置補齊了不兼容的部分。這裡點 OK。

如果繼續出現：

Do you want to send all chunks before replication?

第一次初始化服務器時，建議點「是」。這樣插件會先把當前庫的數據塊發送到服務器，再開始後續同步。

如果出現數據庫大小通知，自建飛牛 CouchDB 可以先選擇 2GB（標準）。這個設置只是提醒用的上限，不代表立刻佔用 2GB 空間。

到這裡，Mac 這臺設備上的 Self-hosted LiveSync 就已經配置完成了。

後續可以在插件設置頁裡看到同步狀態。第一次同步完成後，右上角的同步提示不再持續報錯，就說明當前設備已經能把數據寫入飛牛上的 CouchDB。

在 Windows 上接入已有同步

目前我們已經完成的是第一臺設備，也就是 Mac 端的初始化。Windows 端不要再重新初始化服務器，它要做的是加入 Mac 已經建立好的同步配置。

先回到已經配置好的 Mac，打開 Self-hosted LiveSync 的設置頁，進入帶有小巫師圖標的「快速設置」頁面。

在「設置其他設備」裡，點擊「將當前設置複製為設置 URI」右側的「複製」。

如果前面開啟了端到端加密，插件會讓你輸入一個密碼來保護即將複製出來的 Setup URI。為了避免混亂，可以直接使用前面端到端加密時的同一個密碼。後面在 Windows 或手機上導入這段 URI 時，也要輸入同一個密碼。

複製成功後，插件會提示 Your Setup URI is ready to be copied，這時 Setup URI 已經在剪貼板裡。

把這段 Setup URI 發到 Windows。可以用局域網傳輸、聊天工具、剪貼板同步，或者臨時保存成文本文件。注意這段 URI 裡面包含連接服務器所需的信息，不要發到公開地方。

回到 Windows，先安裝並啟用 Self-hosted LiveSync。首次嚮導裡選擇「我要將設備加入現有同步配置」，然後點擊「是的，我要把這臺設備加入現有同步」。

接下來選擇導入方式。

這裡建議選擇「使用 Setup URI」。這種方式會把服務器地址、數據庫名稱、用戶名等設置一次性帶過來，出錯概率比手動重新輸入低。

把剛才從 Mac 複製出來的 Setup URI 粘貼進去，再輸入對應密碼。

如果下方出現 The Setup-URI is valid and ready to use，說明這段 URI 可以使用。然後點擊 Test Settings and Continue。

連接通過後，插件會提示準備從服務器獲取同步數據。

這裡點擊 Restart and Fetch Data。這一步會讓 Windows 從服務器下載最新同步數據，並用服務器上的數據重建本機的 LiveSync 本地數據庫。

隨後可能會出現「重置此設備上的同步」確認頁。這裡要根據 Windows 這個庫的實際狀態選擇：

• 如果 Windows 是一個全新的空庫，或者裡面只有剛剛新建的少量空文件，選第二項：This Vault is empty, or contains only new files that are not on the server.
• 如果 Windows 是從 Mac 完整複製過來的庫，內容幾乎和服務器一致，選第一項：The files in this Vault are almost identical to the server's.
• 如果 Windows 這邊已經編輯過很多文件，而且不確定和服務器是否一致，才選第三項：There may be differences between the files in this Vault and the server.

第三項最謹慎，但也最容易產生大量衝突記錄，因為插件會重新檢查每個文件的元數據。你這次測試時選第三項也可以，它適合「我不確定本地和服務器是否完全一致」的情況。正式教程裡，更建議讀者根據上面三種情況選擇，不要一律選第三項。

無論選哪一項，繼續前都建議先備份 Windows 裡的 Vault。確認後點擊 Reset and Resume Synchronisation。

如果接入後發現沒有自動同步，打開 Self-hosted LiveSync 設置頁，進入「同步設置」，確認「同步預設」已設為 LiveSync 同步 並點擊「應用」。更多排查見後面的「同步失敗解決方案」。

在安卓和 iPhone 上接入同步

安卓和 iPhone 的接入邏輯和 Windows 一樣，安裝並啟用 Self-hosted LiveSync，首次嚮導選擇「我要將設備加入現有同步配置」，用 Setup URI 或二維碼導入。

建議先在電腦上完整走一遍接入流程，熟悉步驟後再操作手機。電腦端設置頁裡可以複製 Setup URI，也可以打開二維碼讓手機直接掃描。

同步外掛和 Obsidian 設定

上面的步驟解決的是筆記文件同步。外掛、主題、快捷鍵、Obsidian 設定這些內容，不會自動跟著普通筆記同步完全一致。

Self-hosted LiveSync 裡有兩個容易混淆的功能：

• Hidden Files Sync：更偏向隱藏文件同步，不是同步外掛設定的主要入口。
• Customization Sync：用來同步 Obsidian 設定、主題、程式碼片段和外掛配置。

如果你希望 iPhone 上也盡量拿到電腦端的外掛和設定，應該配置 Customization Sync。

先打開 Self-hosted LiveSync 設定頁，進入帶小巫師圖標的頁面，確認「啟用高級功能」和「啟用高級用戶功能」都已經打開。沒開這兩個開關，有些高級同步入口可能看不到。

然後切換到插頭圖標的 Customization sync 頁面。

這裡建議先給當前設備設定一個容易識別的設備名，比如 M5Max、MacBook、iPhone。後面在其他設備上選擇要套用哪一台設備的配置時，就不會混淆。

接著打開「啟用自定義同步」。

繼續往下看，把下面幾個選項也打開：

• 「自動掃描自定義設定」
• 「定期掃描自定義設定」
• 「通知自定義設定」

然後點擊頁面底部的 Open，打開 Customization Sync (Beta3) 窗口。

彈出的窗口如下。後面步驟裡提到的 Scan changes、Sync once、Refresh、Select All Shiny 和 Apply All Selected 都能在這張圖裡看到。

在第一台設備，也就是你已經配置好的 Mac 或 Windows 上，順序是：

1. 點擊 Scan changes。
2. 掃描完成後點擊 Sync once，把這台設備上的設定同步到遠端。
3. 等右上角同步狀態回到 ↑ 0 ↓ 0。

在第二台設備，比如 iPhone 上，順序是：

1. 先正常同步一次筆記。
2. 按照相同的順序，打開 Customization Sync (Beta3) 窗口。
3. 點擊 Refresh。
4. 點擊 Select All Shiny。
5. 點擊 Apply All Selected。
6. 重啟 Obsidian。

這裡有兩個坑需要注意。

第一，不要把外掛設定同步誤認為 Hidden Files Sync。如果目標是同步外掛列表、主題、快捷鍵和外掛數據，主要看 Customization Sync。

第二，如果你執行過 Reset Synchronisation on This Device 之類的重置操作，LiveSync 可能會臨時關閉 Customization Sync。重置完成後，要回到這裡重新打開「啟用自定義同步」，再重新 Scan changes 和 Sync once。

同步失敗解決方案

如果某臺設備接入後沒有自動同步，先不要急著重置數據庫。

最常見的原因，是不同設備上的同步預設不一致。建議在所有平臺的下圖所示位置，把「同步預設」統一設置為 LiveSync 同步，然後點擊「應用」。

這個預設會啟用 LiveSync 常用的實時同步配置，適合大多數人直接使用。

如果仍然不同步，再按下面順序檢查：

1. 確認當前設備能打開 CouchDB 地址，比如 http://飛牛局域網 IP:5984。
2. 確認數據庫名稱、用戶名、密碼和第一臺設備完全一致。
3. 確認端到端加密密碼一致。
4. 確認這臺設備沒有同時開著 iCloud、OneDrive、堅果雲等其他同步方案，避免兩個同步工具同時改同一個 Vault。
5. 打開 LiveSync 的日誌，看是否有網絡、鑑權、CORS 或衝突相關報錯。

在執行「Reset」「Overwrite」「Fetch」這類操作前，一定先備份整個 Vault 文件夾。方向判斷參照「在 Windows 上接入已有同步」一節的原則，第一臺設備用當前數據覆蓋服務器，後續設備從服務器獲取數據，不確定時先備份再選更謹慎的衝突檢查。

公網同步

因為飛牛目前還不支援統一網關訪問 Docker，因此如果你需要公網同步的話，目前暫不支援這個需求，未來等飛牛支援後我會第一時間更新本文，這裡就暫時留空。

結論

這套方案最大的優點是同步無感、延遲低。LiveSync 只同步發生變化的數據塊，日常寫筆記幾乎沒有等待感。端到端加密加自建 NAS，數據完全在自己手裡；CouchDB 對多設備版本衝突的處理也比普通網盤更可靠，簡單衝突會自動合併，複雜衝突會保留痕跡方便判斷。

但它的配置門檻確實高，最容易出問題的地方集中在 Docker 目錄映射、CouchDB 配置文件、端口、HTTP 和 HTTPS、端到端加密密碼，以及多設備接入時的覆蓋方向。

另外，LiveSync 的數據庫會隨著長期使用變大。官方文檔裡也提到，文件刪除後，已經生成過的數據塊不一定會立刻從數據庫中移除，因為這些數據塊還可能用於歷史版本、衝突處理和其他文件的複用。

換句話說，你在 Vault 裡刪除了文件，CouchDB 的佔用空間不一定馬上下降。

如果你經常刪除、重命名、移動大量文件，數據庫膨脹會更明顯。真正想縮小數據庫體積時，比較可靠的辦法是執行 LiveSync 的重建流程，也就是讓插件根據當前 Vault 文件重新構建本地和遠程同步數據庫。

官方文檔裡提到的做法包括 Rebuild everything，以及在 Vault 根目錄放置 redflag2.md 或 flag_rebuild.md 後重啟 Obsidian，讓插件進入重建流程。

這個操作會重新整理同步數據庫，適合在數據庫異常膨脹、同步狀態混亂、或者確認所有設備都已經同步完成之後使用。執行前一定要備份 Vault，因為它會重建同步關係，過程也可能消耗較多時間和網絡流量。

如果你只是想要一個更省心的同步方案，Remotely Save、飛牛 WebDAV + Remotely Save 或 Obsidian 官方同步會更簡單。它們的可調選項少，出問題時也更容易判斷。LiveSync 更適合願意折騰自建服務、希望數據放在自己 NAS 上、並且能接受排查成本的人。

Remotely Save、Git、Syncthing 和 LiveSync 解決的是不同問題，適合的人也不一樣。Remotely Save 適合想盡快接入雲端存儲的人，Git 適合重視歷史記錄和回退的人，Syncthing 適合願意維護點對點同步的人。LiveSync 更適合已經有 NAS 或服務器，並且希望 Obsidian 在多臺設備之間同步得更及時、更連續的人。

所以我的建議是，先按本文跑通局域網內的一臺 Mac 和一臺 Windows。確認這條鏈路穩定後，再考慮手機端和公網訪問。不要一上來就把所有設備、所有插件配置、所有隱藏文件一起同步進去，這樣一旦出錯，很難判斷問題出在哪裡。

無論你最後選擇哪種同步方案，Vault 能多端同步之後，都可以參考 FLO.W Obsidian 模板安裝教程，給這個庫補上一套現成的項目、任務和筆記結構。