Synch

不使用 Cloudflare 自行託管 Synch

使用 Docker Compose 或一般 systemd 在自己的硬體上執行 Synch 伺服器，不需要 Cloudflare 或第三方服務。

如果你完全不想使用 Cloudflare，Synch 伺服器也可以作為一般 Node.js 程序執行。本指南介紹如何在自己的硬體上執行 Synch——例如家用實驗室 NAS、小型 VPS、Incus/LXC 容器，或任何能夠執行長時間程序並公開連接埠的環境——你可以選擇使用 Docker Compose 或 systemd。

所有資料都會儲存在磁碟上：每個 vault 一個 SQLite 檔案，另有一個用於帳戶和 vault 中繼資料的小型應用程式資料庫。不需要 D1、Durable Objects 或 R2，只需將檔案儲存在你自己控制的目錄中。

如果你更希望部署到免費的 Cloudflare 帳號，請參閱 Cloudflare 自行託管指南。

部署前準備

無論選擇哪種方式，你都需要讓 Obsidian 裝置能夠存取伺服器。你可以只在區域網路中使用，也可以透過網際網路存取，以便在離家時同步。如果選擇後者，請在 reverse proxy 後設定 TLS；伺服器本身只提供一般 HTTP。

使用 Docker Compose 部署

你需要先安裝 Docker 和 Docker Compose。

  1. 複製儲存庫並進入 API 目錄：

    git clone https://github.com/hjinco/synch.git
cd synch/apps/api

  2. 複製範例環境檔案：

    cp .env.example .env

  3. 編輯 .env 並填入以下值：

    • PUBLIC_URL - 用戶端存取此伺服器時使用的位址。例如，在區域網路中可以使用 http://192.168.1.50:8787，在 reverse proxy 後可以使用 https://synch.your-domain.example。它必須完全相符，包括 scheme 和連接埠，因為系統會用它驗證傳入要求的 origin。

    • BETTER_AUTH_SECRET 和 SYNC_TOKEN_SECRET - 兩個彼此獨立的隨機 secret。分別使用以下指令產生：

      openssl rand -hex 32

    • AUTH_ALLOWED_EMAILS（必填）- 以逗號分隔可建立帳戶的確切電子郵件地址。

      AUTH_ALLOWED_EMAILS=you@example.com,family@example.com

      比對時會忽略字母大小寫與前後空白。此設定只限制新帳戶，因此從清單移除地址後，現有使用者仍可登入。

  4. 啟動伺服器：

    docker compose up -d

重新啟動和升級後，vault 與 blob 資料都會保存在 synch-data Docker 磁碟區中。遷移到新主機時，請同時複製此磁碟區和 .env 檔案。

Blob 儲存

預設情況下，加密的檔案內容會儲存在同一個資料磁碟區的磁碟中。如果希望使用 AWS S3、MinIO、R2 等 S3 相容儲存貯體，請在啟動前取消 .env 中 BLOB_STORAGE=s3 設定區塊的註解並填入相應值。

升級

git pull
docker compose up -d --build

資料庫遷移會在啟動時自動執行。

不使用 Docker，使用 systemd 執行

伺服器只是一個 Node.js 程序（src/self-host.ts），透過 tsx 執行。Docker 只是方便的選擇，並非必要。如果你已經在使用 VM（例如 Incus/LXC 容器），又不想增加 Docker 相依性，這種方式會很適合。

在 Debian/Ubuntu 上，install.sh 可以自動完成以下步驟。複製儲存庫後，執行 cd apps/api && sudo ./install.sh。之後執行 git pull 時，可以安全地再次執行它來更新並重新啟動服務。手動設定時，請按照以下步驟操作：

  1. 安裝 Node.js 24 和建置工具鏈。如果沒有適用於你的 VM 架構或 libc 的預先建置二進位檔，這些工具用於建置 better-sqlite3 的原生模組：

    # Debian/Ubuntu
sudo apt install -y nodejs python3 make g++
sudo corepack enable

  2. 複製儲存庫並安裝 production 相依套件：

    git clone https://github.com/hjinco/synch.git /opt/synch
cd /opt/synch/apps/api
pnpm install --frozen-lockfile --filter @synch/api... --prod

  3. 將 .env.example 複製為 .env，並按照上面 Docker Compose 步驟中的說明填寫設定。

  4. 安裝並啟動範例 systemd unit：

    sudo useradd --system --home /var/lib/synch-api --create-home synch
sudo cp synch-api.service.example /etc/systemd/system/synch-api.service
# 如果沒有使用 /opt/synch 或 synch 使用者，請編輯 unit 中的路徑/User/Group
sudo systemctl daemon-reload
sudo systemctl enable --now synch-api

  5. 檢查服務是否正常執行：

    curl http://localhost:8787/health
sudo journalctl -u synch-api -f

升級（systemd）

cd /opt/synch
git pull
cd apps/api
pnpm install --frozen-lockfile --filter @synch/api... --prod
sudo systemctl restart synch-api

僅繫結到 localhost

預設情況下，伺服器會監聽 0.0.0.0（所有介面）。Docker Compose 發布連接埠時需要此設定。如果你希望將 systemd 部署放在本機 reverse proxy（例如 tailscale serve、nginx 或 Caddy）後面，並且不希望伺服器直接暴露在區域網路或公共介面上，請在 .env 中設定 HOST=127.0.0.1。範例 systemd unit 和 install.sh 已經為你設定了這一點。

修改後，將 PUBLIC_URL 更新為用戶端實際連接的位址（reverse proxy 的位址，而不是 127.0.0.1），然後重新啟動服務。better-auth 使用 PUBLIC_URL 驗證傳入要求的 origin。

連接 Obsidian

  1. 開啟 Obsidian。
  2. 前往 Settings。
  3. 開啟 Synch 設定。
  4. 在 Self-hosted server 中貼上伺服器的 PUBLIC_URL。結尾不要加上 /。
  5. 按一下 Save。
  6. 繼續按照平常的方式登入並設定 vault。