用 Docker 部署 Syncthing：Compose、連接埠和目錄映射避坑

Syncthing 系列目錄

在 Docker 中部署 Syncthing，很適合 NAS、家用伺服器和 VPS 場景。它可以作為 24 小時在線的同步節點，長期承擔照片、文件、Markdown 筆記或下載目錄的同步任務。

Docker 部署 Syncthing 的重點不是「能不能跑起來」，而是三個問題：

設定目錄要持久化。
需要同步的資料目錄要映射到宿主機。
連接埠和權限要提前處理好。

如果這三點沒有處理好，容器更新後可能遺失設定，Web UI 裡填寫路徑時可能找不到真實目錄，或者同步時出現 Permission denied。

目錄規劃

建議先在伺服器或 NAS 上準備一個獨立目錄，例如：

1
2


mkdir -p ~/syncthing
cd ~/syncthing

這個目錄裡放 docker-compose.yml，並用子目錄保存 Syncthing 設定：

1
2
3


syncthing/
├── docker-compose.yml
└── config/

同步資料目錄可以放在 NAS 或宿主機已有路徑中，例如：

1
2


/volume1/downloads
/volume1/photos

設定目錄和資料目錄要分開。config 保存 Syncthing 自己的設定、密鑰和索引資料庫；downloads、photos 這類目錄才是你要同步的真實資料。

方案一：Docker Compose

更推薦使用 Docker Compose，後續更新、重啟和遷移都更清楚。

在 ~/syncthing/docker-compose.yml 寫入：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


version: "3"

services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: my-nas-syncthing
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/var/syncthing/config
      - /volume1/downloads:/var/syncthing/downloads
      - /volume1/photos:/var/syncthing/photos
    ports:
      - 8384:8384
      - 22000:22000/tcp
      - 22000:22000/udp
      - 21027:21027/udp
    restart: unless-stopped

啟動：

1

docker compose up -d

查看狀態：

1
2


docker compose ps
docker logs -f syncthing

打開 Web UI：

1

http://伺服器IP:8384

首次進入後台後，先設定 GUI 使用者名稱和密碼。

方案二：docker run

如果只是快速測試，也可以直接使用 docker run：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


docker run -d \
  --name syncthing \
  --hostname my-nas-syncthing \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Shanghai \
  -p 8384:8384 \
  -p 22000:22000/tcp \
  -p 22000:22000/udp \
  -p 21027:21027/udp \
  -v /path/to/config:/var/syncthing/config \
  -v /path/to/data1:/var/syncthing/data1 \
  --restart unless-stopped \
  syncthing/syncthing:latest

這裡的 /path/to/config 和 /path/to/data1 必須換成宿主機真實路徑。

例如：

1
2


-v /volume1/docker/syncthing/config:/var/syncthing/config
-v /volume1/photos:/var/syncthing/photos

長期使用時，還是建議改成 Compose 檔案，避免每次重建容器都要重新拼命令。

容器內路徑和宿主機路徑

Docker 新手最容易混淆的是路徑。

比如 Compose 裡寫了：

1
2


volumes:
  - /volume1/photos:/var/syncthing/photos

左邊 /volume1/photos 是宿主機路徑。右邊 /var/syncthing/photos 是容器內路徑。

進入 Syncthing Web UI 新增同步資料夾時，資料夾路徑必須填寫容器內路徑：

1

/var/syncthing/photos

這樣 Syncthing 實際操作的才是宿主機上的：

1

/volume1/photos

如果你在 Web UI 裡填 /volume1/photos，容器內部通常沒有這個路徑，Syncthing 可能會報錯，或者在容器檔案系統裡建立一個你並不想要的新目錄。

設定目錄必須持久化

下面這一行很關鍵：

1

- ./config:/var/syncthing/config

Syncthing 的設定檔、裝置密鑰和索引資料庫都會放在設定目錄裡。如果不把它掛載到宿主機，容器刪除或重建後，裝置 ID 可能變化，原來的裝置配對關係也會失效。

建議把設定目錄放在穩定路徑中，例如：

1

/volume1/docker/syncthing/config

不要把設定目錄放進臨時目錄，也不要和同步資料目錄混在一起。

連接埠和防火牆

常用連接埠如下：

1
2
3
4


8384/TCP   Web UI 管理後台
22000/TCP 裝置間同步流量
22000/UDP QUIC 同步流量
21027/UDP 區域網路發現

如果 Syncthing 部署在家用 NAS 上，通常要檢查：

NAS 自帶防火牆是否放行這些連接埠。
Docker 網橋連接埠是否正確映射。
路由器是否隔離了 Wi-Fi 和有線網路。
手機和電腦是否在同一網段。

如果部署在雲伺服器上，還要檢查雲廠商安全群組。尤其是 22000/TCP 和 22000/UDP，如果沒有放行，其他裝置可能只能透過 relay 連接，速度會明顯變慢。

8384 是管理後台連接埠，不建議直接暴露到公網。如果確實要遠端管理，至少要設定強密碼，最好再配合反向代理、HTTPS、存取控制或 VPN。

權限問題：PUID 和 PGID

如果啟動後 Syncthing 能打開 Web UI，但同步目錄時出現：

1

Permission denied

通常是容器程序沒有宿主機目錄的讀寫權限。

先在宿主機上查看目前使用者的 UID 和 GID：

1

id

輸出類似：

1

uid=1000(user) gid=1000(user) groups=1000(user)

然後把 Compose 裡的環境變數改成對應值：

1
2
3


environment:
  - PUID=1000
  - PGID=1000

同時確認宿主機目錄本身允許這個使用者讀寫：

1

ls -ld /volume1/photos

必要時調整目錄擁有者或權限：

1

sudo chown -R 1000:1000 /volume1/photos

在 NAS 系統上不要盲目遞迴修改整個共享目錄權限，尤其是多人共享目錄。更穩妥的做法是給 Syncthing 單獨準備一個同步目錄，或者在 NAS 權限管理介面給對應使用者授權。

Web UI 首次安全設定

容器啟動後，訪問：

1

http://伺服器IP:8384

首次進入後台，Syncthing 通常會提示設定 GUI 使用者名稱和密碼。這一步不要跳過。

建議：

立即設定 GUI 使用者名稱和強密碼。
不把 8384 暴露到公網。
遠端訪問時優先走 VPN、SSH 隧道或受控反向代理。
如果使用反向代理，確認只代理 Web UI，不要誤開放其他不必要連接埠。

如果管理後台被別人控制，對方就可能新增裝置、修改共享目錄、改變同步關係。Syncthing 的同步資料傳輸是加密的，但管理入口本身仍然需要保護。

在 Web UI 中新增同步目錄

以照片目錄為例，Compose 中已經掛載：

1

- /volume1/photos:/var/syncthing/photos

Web UI 裡新增資料夾時：

Folder Label：可以寫 Photos。
Folder ID：建議使用穩定英文 ID，例如 photos。
Folder Path：填寫 /var/syncthing/photos。
Sharing：選擇要共享給哪些裝置。
Folder Type：按需求選擇 Send & Receive、Send Only 或 Receive Only。

如果這台 Docker 節點是 NAS 中心節點，常見配置是：

普通文件：Send & Receive
手機照片彙整：NAS 上設為 Receive Only
對外分發目錄：NAS 上設為 Send Only

具體選擇要看你的資料流向。不要所有目錄都無腦雙向同步。

更新容器

使用 Compose 時，更新通常是：

1
2


docker compose pull
docker compose up -d

只要設定目錄和資料目錄都正確掛載，更新容器不會遺失裝置 ID、配對關係和同步目錄設定。

更新前可以先備份設定目錄：

1

tar -czf syncthing-config-backup.tar.gz ./config

設定目錄裡包含裝置私鑰，不要把備份檔案隨便上傳到公共位置。

常見問題

Web UI 打不開

先檢查容器是否運行：

1
2


docker ps
docker logs syncthing

再檢查連接埠映射：

1

docker port syncthing

如果容器正常，仍然打不開，檢查宿主機防火牆、NAS 防火牆或雲伺服器安全群組。

新增目錄後提示不存在

檢查你在 Web UI 裡填寫的是不是容器內路徑。

例如宿主機路徑是：

1

/volume1/downloads

容器內路徑是：

1

/var/syncthing/downloads

Web UI 裡應該填後者。

只能透過 Relay，速度很慢

優先檢查：

22000/TCP 是否放行。
22000/UDP 是否放行。
路由器連接埠轉發是否正確。
雲伺服器安全群組是否同時放行 TCP 和 UDP。
本機防火牆是否攔截 Docker 映射連接埠。

Relay 能提高可連接性，但不適合長期承擔大量同步流量。

同步後檔案權限不對

先確認容器運行使用者是否正確，再確認宿主機目錄權限。Linux、NAS、Windows 共享目錄之間的權限模型不同，不要把 Syncthing 當成權限修復工具。

對於跨系統同步，盡量同步普通檔案和目錄，少同步依賴複雜 ACL、擁有者、擴展屬性的系統目錄。

一個更穩的使用方式

如果你的目標是把 NAS 或伺服器作為中心節點，可以這樣設計：

NAS 上用 Docker 跑 Syncthing。
設定目錄掛載到 /volume1/docker/syncthing/config。
每類資料單獨掛載，例如 /volume1/photos、/volume1/notes。
手機、電腦分別新增 NAS 的裝置 ID。
重要目錄在 NAS 端開啟檔案版本。
Web UI 只在內網或 VPN 內訪問。
NAS 本身再做獨立備份，不把同步當作唯一備份。

這樣 Syncthing 負責裝置間同步，NAS 負責長期在線和版本緩衝，真正的備份再交給快照、外接硬碟或異地備份。

總結

Docker 部署 Syncthing 的關鍵，是把「容器生命週期」和「同步資料生命週期」分開。

容器可以隨時更新、重建、遷移；但設定目錄和資料目錄必須穩定保存在宿主機上。Web UI 裡填寫的是容器內路徑，宿主機權限要透過 PUID、PGID 和目錄授權處理，連接埠要按實際網路環境放行。

只要這幾件事配置清楚，Syncthing 很適合作為 NAS、伺服器和個人裝置之間的輕量同步層。