用 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 和目录授权处理，端口要按实际网络环境放行。