这是「Docker 好项目」系列的第 23 期。前面 22 期我们一直在把服务搬回自己服务器——照片、音乐、电影、笔记、书签、代码、认证、备份、日志都有了。但有个最基础的活儿一直没管:同一份文件怎么在多台机器之间保持同步。你现在的做法大概率是微信文件传输助手发给自己、U 盘拷一份、或者老老实实手动 scp,改多了就不知道哪台机器上的才是最新的。这期介绍 Syncthing:一个不需要中心服务器、端到端加密、点对点直连的文件同步工具,家里 NAS、公司电脑、云主机、手机可以互相同步任意目录。

痛点开场
先复盘一下现在怎么在多台机器之间搬文件的:
- 微信/QQ 发文件给自己:单文件 100MB 就卡,发完还得两台机器都手动点一遍,删了聊天记录文件就没了,没有任何"目录"概念
- U 盘来回拷:物理上跑一趟不说,最要命的是分不清哪边是最新的。两台机器都改过同一个文件,拷来拷去最后两份都是残缺的
scp/rsync手动传:要知道对端 IP,要能 SSH 进去,每加一台机器就要多配一套;而且它只是"推一次",不是"一直保持一样"- 网盘同步盘:这条路确实省事,但你的文件在别人的服务器上,容量要花钱买,客户端在 Linux 服务器上经常装不上(很多网盘没有 headless 版本)
- 改了一堆小文件,只想同步变化的部分:整目录 tar 一遍再传,传输量永远是目录总大小,跟改了多少无关
文件同步这件事其实有个很成熟的技术方案——Syncthing 从 2013 年开始做,现在 89k stars。它不搞中心云存储,而是让设备之间直接建立加密连接,各自念一份"我的目录长什么样"的索引(block index),比对之后只传差异块。你改了一个 10MB 文件里的 4KB,它就只传那 4KB。

(上图是官方界面截图,Folders 列出每个同步目录的状态,This Device 显示本机速率、监听者、发现节点和运行时长,Remote Devices 显示对端设备的连接状态——后面配置章节会讲怎么读懂这几栏。)
能力边界
能干什么
- 双向同步(send-receive):两端任意改动都会传播到对方,全自动、无中心服务器
- 三种单向模式:
send-only(只发不收)、receive-only(只收不发)、receive-encrypted(对端只能存密文,适合往不可信的主机上放一份加密副本) - 文件监听(fsWatcher):内核 inotify 事件触发,改完几秒内就开始传,不用等定时扫描
- 增量块传输:文件按块做哈希,只传变化的块。改大文件的一小部分不用重传
- 版本控制:支持简单版本(保留 N 个旧版本)、Staggered(按时间间隔保留)、External(自己写脚本处理)
- 中继与打洞:两边都在 NAT 后面连不上时,走公共 relay 转发(内容是端到端加密的,中继看不到明文);也可以自己搭 relay 和发现服务器
- 多平台:Linux / macOS / Windows / FreeBSD / Android / iOS(第三方客户端),官方镜像覆盖 amd64 / arm64 / armv5 / armv7 / arm64v8 等
- REST API + CLI:
/rest/*一整套接口,syncthing cli自带命令行客户端,event 流可以拿来接告警 - 文件版本冲突自动处理:同时改一个文件时,输的一方会被改名成
xxx.sync-conflict-日期-时间-设备ID.后缀,两边内容都保住,不会静默覆盖
不干什么
- 不做云端存储。它没有"服务器上一份、所有人从服务器取"的模式——它同步的是设备与设备之间。至少要有一台设备在线,另一端才拿得到文件
- 不做用户体系和权限。没有账号、没有共享链接、没有"只看不给改"的访客。设备之间是对等信任,加了对方的设备 ID 就等于把目录给它了
- 不做文件版本历史。除了你自己开的 versioning(本地保留副本),它不存历史版本,也没有回收站
- 不能选择"只同步某个子目录"。同步的粒度是整个目录(可以用 ignore 规则排除文件,但那只是不同步,不是选择性拉取)
- 不是备份工具。它镜像的是当前状态,本地删了、对端也会删。要历史归档请用第 21 期 Kopia
- 不做实时协作。同时编辑同一个文档会产冲突副本,不是 Google Docs 那种合并
部署前准备
| 项 | 说明 |
|---|---|
| 镜像 | syncthing/syncthing(Docker Hub),推荐 tag :2——实测 2 == 2.1 == 2.1.6 == latest(manifest digest 完全相同),是标准的滚动 major tag,会自动跟到 2.1.7、2.2……的补丁与新特性版本 |
| 备选源 | ghcr.io/syncthing/syncthing:2(同一镜像,两个 registry 都发) |
| 端口 | 8384/tcp(Web 管理界面)、22000/tcp + 22000/udp(设备间同步协议,TCP 是主通道,UDP 走 QUIC)、21027/udp(局域网广播发现) |
| 数据卷 | /var/syncthing(内含 config/ 配置与密钥 + data/ 数据库)。要同步的目录自己另外挂 |
| 运行用户 | 镜像默认 PUID=1000 / PGID=1000,entrypoint 以 root 起、chown 数据目录后用 su-exec 降权。PUID/PGID 是真生效的(可调整成宿主机上拥有文件的那个用户) |
| 环境变量 | PUID、PGID、UMASK、PCAP、STGUIADDRESS、STHOMEDIR、STNOUPGRADE、STGUIAPIKEY |
| 内置健康检查 | 有。curl -fkLsS -m 2 127.0.0.1:8384/rest/noauth/health \| grep -o OK,间隔 1 分钟 |
| 资源 | 常驻内存 100~200MB 量级,CPU 只在扫描/传输时占用;索引库大小约为被同步数据量的 1~2% |
必须先想清楚的一件事:镜像里 STGUIADDRESS=0.0.0.0:8384,也就是管理界面默认监听所有网卡。同时默认配置的 GUI 地址是 127.0.0.1:8384、没有设置任何用户名密码——所以「Web 界面裸奔」是这个镜像最典型的翻车点。部署完第一件事就是配上认证,细节见下面的踩坑清单。
docker run 一行版
先跑起来看个明白(挂一个测试目录,不动真数据):
docker run -d \
--name syncthing \
--restart unless-stopped \
--hostname syncthing-ecs \
-p 8384:8384 \
-p 22000:22000/tcp \
-p 22000:22000/udp \
-p 21027:21027/udp \
-v /opt/syncthing/config:/var/syncthing \
-v /opt/syncthing/sync:/data/sync \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Asia/Shanghai \
syncthing/syncthing:2
浏览器打开 http://服务器IP:8384 就能看到管理界面。这一版的 GUI 是裸奔的,只在你自己内网或者 SSH 端口转发下试,别放到公网。
docker-compose 推荐版
正式用建议直接上这份(桥接网络 + 认证 + 固定用户 + 健康检查):
services:
syncthing:
image: syncthing/syncthing:2
container_name: syncthing
restart: unless-stopped
# 容器名会显示在界面的设备名称里,建议起个能一眼认出机器的名字
hostname: syncthing-ecs
ports:
# Web 管理界面
- "8384:8384"
# 设备间同步协议:TCP 主通道 + QUIC
- "22000:22000/tcp"
- "22000:22000/udp"
# 局域网广播发现(同一网段里的设备靠它互相找到)
- "21027:21027/udp"
volumes:
# 配置、设备密钥、索引数据库都在这里,必须持久化
- /opt/syncthing/config:/var/syncthing
# 要同步的目录,按你自己的路径改;建议放在数据盘上
- /opt/syncthing/sync:/data/sync
environment:
# 以宿主机上拥有这些文件的用户身份跑,避免同步完文件全变成 root 所有
PUID: 1000
PGID: 1000
# 新文件权限掩码。默认 022 生成 644;团队共享目录可以用 002 生成 664
UMASK: "002"
TZ: Asia/Shanghai
# 容器里的 Syncthing 不能自己升级(升级要靠换镜像),关掉升级检查
STNOUPGRADE: "1"
# 关键:不覆盖 config.xml 里的 GUI 监听地址,
# 否则界面里改"GUI 地址"会写不进去(存了但不生效,重启还原)
STGUIADDRESS: ""
healthcheck:
test: ["CMD-SHELL", "curl -fkLsS -m 2 127.0.0.1:8384/rest/noauth/health | grep -o --color=never OK || exit 1"]
interval: 1m
timeout: 10s
retries: 3
start_period: 30s
起服务:
mkdir -p /opt/syncthing/config /opt/syncthing/sync
docker compose up -d
docker inspect --format '{{.State.Health.Status}}' syncthing
看到 healthy 就说明起来了。接下来去界面里配认证(下一节)。
关于网络模式的选择:官方 README 推荐 network_mode: host,理由是默认桥接网络下 Syncthing 只能看到容器内网 IP,局域网直连可能建立不起来。但 host 模式下它独占宿主机的 8384 / 22000 / 21027,如果这几端口已经被占用(比如你 22000 上跑了别的东西),容器会起不来。上面这份用桥接 + 显式映射端口,对大多数场景够用,也更好和 1Panel 的反代配合;确实遇到「局域网设备死活连不上」时再换 host 模式。
配置项逐项解释
下面这些是日常真正会碰到的,默认值全部对着 v2.1.6 的源码核过:
| 变量 | 默认 | 为什么这么写 |
|---|---|---|
PUID / PGID |
1000 / 1000 |
entrypoint 会 chown 数据目录再降权。设成宿主机上拥有同步目录的那个用户的 uid/gid,否则同步出来的文件属主不对,别的程序读不了 |
UMASK |
未设(继承镜像默认) | 新文件/目录的权限掩码。022 → 文件 644;共享目录用 002 → 664,同组可写 |
PCAP |
未设 | 以 root 起但需要额外能力时用,语法同 setcap(8),例如 cap_chown,cap_fowner+ep。不设时入口脚本会主动 setcap -r 清掉二进制上的能力 |
STGUIADDRESS |
0.0.0.0:8384 |
镜像里硬编码了这个值。它一旦非空就覆盖 config.xml 里的 GUI 地址(源码 guiconfiguration.go 的 IsOverridden())。想让界面里的设置生效,compose 里显式写成空串 "" 或直接不继承这个变量 |
STHOMEDIR |
/var/syncthing/config |
配置和密钥目录。改了它要保证挂载对得上 |
STNOUPGRADE |
未设 | 容器里没法自升级(升级就是换镜像),建议设 1 关掉自动升级检查,省掉到 upgrades.syncthing.net 的轮询 |
STGUIAPIKEY |
未设 | 覆盖 config.xml 里的 API Key。用容器密钥管理时走它,一般不用(API Key 在界面「操作 → 设置 → 图形用户界面」里能看) |
STTRACE |
未设 | 按包开 debug 日志,逗号分隔。排查「为什么连不上对端」时最有用:STTRACE=connections,discovery,beacon |
STNORESTART |
未设 | 让进程不要自杀重启。你自己写 supervisor 时用,compose 场景不需要(restart: unless-stopped 已经兜住了) |
TZ |
UTC | 影响日志时间戳和界面时间显示。同步的文件 mtime 不受它影响,但排查问题时时间对不上会很痛苦,务必设 |
几个默认值背后的坑:
STGUIADDRESS默认是0.0.0.0:8384(监听全网卡),而 GUI 密码默认是空的。这两条加起来就是「任何人知道 IP 就能改你的同步配置」。装完第一件事去界面配账号密码- 默认没有开
STNOUPGRADE。宿主机上装的那个能用界面自升级,容器里的用不了——不关的话日志里会有升级检查失败,无害但吵 PUID默认 1000。如果你的同步目录属于 root,或者属于一个 uid 不是 1000 的账号,同步出来的文件会变成 uid 1000 所有,宿主机上别的服务可能就读不了/var/syncthing这个卷里既有配置也有密钥。config/cert.pem、config/key.pem是这台设备的身份,config/config.xml里存着 GUI 密码的 bcrypt 哈希和设备的私钥信息。卷丢了设备 ID 就变了,所有对端都要重新加一遍设备
1Panel 面板怎么搞
Syncthing 是 1Panel 应用商店里的常客(不同版本的收录情况不一样,以你面板里实际显示为准)。两条路都能走:
路线 A:用应用商店(有的话)
- 应用商店里搜
syncthing→ 安装 - 表单里通常会让你填 HTTP 端口(默认 8384)、同步端口(默认 22000)、PUID/PGID、时区
- 装完后一定要去「容器 → 编排」里看它实际的
docker-compose.yml,确认/var/syncthing挂到了宿主机上的哪个目录——后面备份和排障都要用到这个路径 - 装完立刻去界面配认证(见下一节)。商店模板一般不会给你设密码
路线 B:自己贴编排(推荐,版本可控)
- 容器 → 编排 → 创建编排,名字填
syncthing,把上一节的 compose 贴进去,路径按你自己的目录习惯改 - 改完先别急着起:确认三件事——
STGUIADDRESS: ""写了、PUID/PGID对得上宿主机用户、同步目录挂对了 - 点「启动」,在编排详情里看日志。出现
Ready to synchronize和GUI and API listening on ...就说明起来了 - 防火墙:只放行 8384 是不安全的。正确姿势是 8384 不进公网,走下面的反代 + HTTPS;22000/tcp+udp 和 21027/udp 按需放行(只和家里 NAS 同步的话,两者都走中继也能用,只是慢)
- HTTPS:网站 → 反向代理 → 新建,代理目标
http://127.0.0.1:8384,再申请证书开启 HTTPS
有个容易踩的点:界面里「操作 → 设置 → 图形用户界面」有一个 「使用 HTTPS 访问图形管理界面」 勾选项。在反代后面时不要勾它——勾了容器自己会用自签证书开 HTTPS,反代再套一层就会 502。TLS 交给反代做,容器内部保持明文 HTTP。
首次访问
第一次打开 http://服务器IP:8384,界面上会有两条显眼的提示:
第一条:设置 GUI 认证。 界面顶部会飘一条红色警告「GUI 与 API 未设密码」——源码里这条警告的触发条件是:监听地址不是 127.0.0.1、且没有配用户名密码、且没有勾"不安全的管理员访问"。所以看到它就是明确告诉你:现在谁都能进来改配置。
点 操作 → 设置 → 图形用户界面:
| 字段 | 填什么 |
|---|---|
| 图形管理界面监听地址 | 0.0.0.0:8384(容器里必须这样,否则反代连不上);用反代 + HTTPS 时建议再勾上"使用 HTTPS 访问"的反面——即不要勾 |
| 用户 / 密码 | 必填。设完点保存,页面会要求重新登录 |
| 使用 HTTPS 访问图形管理界面 | 反代后面不勾(见上一节的说明) |
| 主题 | 内置 default / black / dark 等,按喜好 |
| API 密钥 | 自动生成的一串 32 位字符。REST API 和 syncthing cli 都靠它,要接告警或者写脚本时复制走 |
第二条:添加第一台设备 / 第一个目录。
Syncthing 里两个概念:设备(Device)是身份,目录(Folder)是内容,两者通过"共享"关联起来。要同步一个目录,必须三件事同时满足:
- 两端互相添加了对方的设备 ID(一串
XXXXXXX-XXXXXXX-...共 8 组的字符,在「操作 → 显示 ID」里,也能在界面右上角设备名旁边看到) - 两端都建了同名共享的目录 ID
- 目录路径在各自机器上是存在的、可写的
建目录的完整流程(A 机推给 B 机):
A 机:添加文件夹
- 文件夹标签:照片同步
- 文件夹 ID:photo-sync ← 手动指定,不要用随机 ID,两端要一致
- 文件夹路径:/data/sync/photo ← 容器内路径,必须是你挂进去的那个
- 文件夹类型:发送与接收
- 共享 → 勾上 B 机
(如果 B 机还没加,先去「远程设备」用它的设备 ID 添加)
B 机:几秒后界面会弹出
- 「设备 A 想要共享文件夹 photo-sync」→ 点「添加」
- 路径填 /data/sync/photo(可以不一样)
- 类型选「仅接收」的话就变成单向镜像
关于目录类型的选择,这是最容易用错的地方:
| 类型 | 含义 | 什么时候用 |
|---|---|---|
| 发送与接收 | 双向,两边改都传播 | 自己的多台机器互同步 |
| 仅发送 | 只往外发,别人改的不要 | 云主机上放一份"权威副本",不想被远端污染 |
| 仅接收 | 只往里收,本地改的会被覆盖回去 | 备份机、只读镜像节点 |
| 接收加密 | 只收,且存的是密文 | 往不信任的主机上放加密副本(比如放在共享服务器上做异地备份) |
「仅接收」和「发送与接收」不要混用:一端设了仅接收,另一端在本地改了同名的文件,改动会被回滚——它认为对端才是真相。第一次配反了容易以为是同步坏了。
最小可用配置
如果只是想"两台机器之间同步一个目录",这份够用,不用管中继、不用管发现服务器:
services:
syncthing:
image: syncthing/syncthing:2
container_name: syncthing
restart: unless-stopped
hostname: syncthing-a
ports:
- "8384:8384"
- "22000:22000/tcp"
- "22000:22000/udp"
- "21027:21027/udp"
volumes:
- /opt/syncthing/config:/var/syncthing
- /opt/syncthing/sync:/data/sync
environment:
PUID: 1000
PGID: 1000
TZ: Asia/Shanghai
STNOUPGRADE: "1"
STGUIADDRESS: ""
配完之后:
- 界面里设好用户名密码
- 两端互加设备 ID
- 建一个目录,把两端都共享进去
- 往一端扔个文件,看另一端几秒内出现
如果两台机器在同一个局域网(比如你的 Mac 和家里 NAS),21027/udp 的广播发现会让它们直接找到对方,走内网千兆,速度是满的,根本不经过公网。
如果一台在家里、一台在云上,它们会走 DHT/全局发现找到彼此,能打洞就走直连(速度取决于两边上行),打不通就走公共中继(较慢但能用)。这也是为什么云主机上要放行 22000/tcp+udp——直连成功的关键端口。
局域网直连与中继调优
这一节解决"为什么同步这么慢"。
| 现象 | 原因 | 怎么调 |
|---|---|---|
只有 Relay 连接,速度几百 KB/s |
两边都在 NAT 后面,打洞失败 | 至少一端放行 22000/tcp+udp 并且路由器上做端口映射;或者在两端配 alwaysLocalNets 走内网 |
| 同一个局域网里还是走中继 | 广播发现被容器网络隔离了 | 检查是否映射了 21027/udp;桥接模式下如果还不行,改用 network_mode: host |
| 直连上了但速度很慢 | 默认限速、或者对端上行不足 | 界面里「操作 → 设置 → 连接」把 Max Send/Recv Kbps 设为 0(不限速);另外注意 WAN 侧直连的瓶颈通常是上行带宽,不是下行 |
| 想自己搭中继 | —— | 官方提供 syncthing/relaysrv、syncthing/discosrv 镜像,可以自建 relay 和发现服务器,摆脱公共服务依赖 |
想确认当前是直连还是走中继,看界面「远程设备」那一栏里的 Address:172.16.32.11:22000 这种是内网直连;relay://... 开头就是走中继;还有 quic:// 是 UDP 直连。
命令行核对一下当前连接状况(拿 API Key 换):
API="换成你的API密钥"
# 看当前建立的连接和地址类型
curl -s -H "X-API-Key: $API" http://127.0.0.1:8384/rest/system/connections | head -c 800
# 看全局发现有没有找到地址
curl -s -H "X-API-Key: $API" "http://127.0.0.1:8384/rest/system/discovery?device=<对端设备ID>"
用
syncthing cli更顺手(进容器执行即可):bash docker exec -it syncthing syncthing cli --gui-address=http://127.0.0.1:8384 --gui-apikey=<API密钥> show connectionsCLI 支持show(system/connections/usage)、operations(restart/upgrade)、errors(show/clear)、debug几组子命令,写脚本时比裸调 REST 舒服。
告警与通知配置
先说实话:Syncthing 内置没有任何告警通道。 它只有一个事件流(/rest/events),把「设备连上/断开、目录状态变化、发现失败、升级可用、冲突文件产生」等都推出来,但不会主动通知你。社区里做告警的通行做法是接一个外部工具。
三种可行路线:
路线 1:用第 1 期 Uptime Kuma 做保活(最省事)
Uptime Kuma 加一个 HTTP Monitor,URL 填 http://云主机IP:8384/rest/noauth/health,期望响应包含 OK。这个端点不需要鉴权(源码 lib/api/api.go 里注册在 noauth 组,返回 {"status":"OK"}),所以探针不用带密钥。
# 先手工验证一遍
curl -s http://127.0.0.1:8384/rest/noauth/health
# {"status":"OK"}
路线 2:用第 13 期 ntfy 推手机(真正的事件告警)
写一个几十行的脚本挂在 cron 上,拉事件流,命中关键字就推 ntfy:
#!/bin/bash
# /opt/syncthing/watch-events.sh
# 监听 Syncthing 事件流,把冲突、错误、设备掉线推到 ntfy
API="换成你的API密钥"
NTFY="https://ntfy.example.com/syncthing" # 第 13 期搭的那个
while read -r line; do
case "$line" in
*'"type":"FolderErrors"'*|*'"type":"DeviceDisconnected"'*|*'"type":"FolderSummary"'*)
# 只推有意义的:错误、掉线、以及带冲突的目录摘要
if echo "$line" | grep -q '"type":"FolderErrors"' \
|| echo "$line" | grep -q '"type":"DeviceDisconnected"' \
|| echo "$line" | grep -q 'sync-conflict'; then
curl -s -d "$line" -H "Title: Syncthing 事件" -H "Priority: high" "$NTFY" >/dev/null
fi
;;
esac
done < <(curl -sN -H "X-API-Key: $API" "http://127.0.0.1:8384/rest/events?timeout=60")
chmod +x /opt/syncthing/watch-events.sh
# 放进 crontab,掉线自动重连
( crontab -l 2>/dev/null; echo "@reboot /opt/syncthing/watch-events.sh" ) | crontab -
路线 3:用第 19 期 n8n 做流水线
n8n 里用 HTTP Request 节点定时拉 /rest/system/connections 和 /rest/db/status?folder=<目录ID>,用 IF 节点判断「对端 connected 字段为 false」或者「needFiles > 0 持续 10 分钟」,命中就走 ntfy / 企业微信 / 邮件节点。这样能在可视化界面上调规则,不用写代码。
最少要做到的监控(不管用哪条路线):
| 检查项 | 端点 | 判定 |
|---|---|---|
| 进程活着 | /rest/noauth/health |
返回 {"status":"OK"} |
| 对端连着 | /rest/system/connections |
目标设备的 connected 为 true |
| 目录没落后 | /rest/db/status?folder=<ID> |
needFiles / needBytes 长期不为 0 |
| 没有冲突 | /rest/db/status?folder=<ID> |
errors 为空,且目录里没有 *.sync-conflict-* 文件 |
反向代理与 HTTPS
推荐子域名直挂(以 Nginx / 1Panel 的 OpenResty 为例):
server {
listen 443 ssl http2;
server_name sync.example.com;
ssl_certificate /etc/letsencrypt/live/sync.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/sync.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8384;
proxy_http_version 1.1;
# Syncthing 的事件流和长轮询靠这两行
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 关掉缓冲,否则界面状态刷新会延迟
proxy_buffering off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
反代后必须做的两件事:
- 容器里不要勾「使用 HTTPS 访问图形管理界面」。勾了之后容器内部自己开 HTTPS,反代用 http 去连会 502
- 界面里勾上「不安全地跳过 Host 检查」(
insecureSkipHostcheck)。Syncthing 会校验请求的 Host 头,反代改了 Host 之后可能被拒绝访问,这个开关就是为反代场景准备的
不要用子路径(
https://example.com/sync)部署 Syncthing——它对子路径的支持不可靠,界面里的静态资源和 WebSocket 容易指错。要隔离就用子域名。
另一个选择:干脆不暴露 GUI。如果你不需要在外面看界面,只让它在后台默默同步,那就不要做反代,8384 只映射到 127.0.0.1:
ports:
- "127.0.0.1:8384:8384" # 只允许本机访问,要看界面就 SSH 隧道
# 本机开隧道再看界面,最安全
ssh -L 8384:127.0.0.1:8384 user@云主机IP
# 然后浏览器开 http://127.0.0.1:8384
踩坑清单
按被坑概率排序:
- GUI 裸奔。镜像里
STGUIADDRESS=0.0.0.0:8384、默认配置里 GUI 地址是127.0.0.1:8384、密码为空——一个非 localhost 监听且无认证的管理界面。它自己在界面顶部会飘红色警告,但很多人直接无视了。装完立刻配用户名密码,或者把 8384 只绑到 127.0.0.1 - 没设
STGUIADDRESS: "",界面里改 GUI 地址/端口不生效。这个坑非常隐蔽:你在「设置 → 图形用户界面」里把端口改成 8385 保存,config.xml里也写了8385,但重启后依然监听 8384——因为环境变量的优先级更高,config.xml的值被直接覆盖掉了。要么显式设空串,要么就别在界面里改地址 - 容器重建后设备 ID 变了。设备 ID 是从
/var/syncthing/config/key.pem派生的。没有持久化/var/syncthing就等于每次重建都是一台新设备,所有对端都得重新添加、目录全部重新协商。这个目录是必须挂的 - 同步出来的文件属主不对。默认
PUID=1000,如果宿主机上那些目录属于别的用户(比如 root、或者 uid 1001),同步完别的服务读不了。「视频」「照片」这类要给 Jellyfin / Immich 读的目录,PUID/PGID一定要和那些服务跑的用户一致 - 目录类型配反了。一端
仅接收、另一端在本地修改 → 改动被静默回滚,看起来像"同步失灵"。先确认谁该是权威源,再选类型 - 双方目录 ID 不一致。界面里建目录时如果留空让它自动生成,两端会各得一个随机 ID,永远不会匹配上。务必手动指定一个两端相同的
文件夹 ID(英文字母数字连字符,不要用中文) Ignore Permissions在 Windows ↔ Linux 之间没开。跨平台同步(尤其带 macOS)时权限位根本对不上,文件会一直"不同步",日志里刷 permissions 相关的差异。跨平台共享的目录勾上"忽略权限".stfolder标记目录被删。每个共享目录里都有一个隐藏的.stfolder目录,它是「这个目录确实是 Syncthing 在管」的凭证。手动清理时误删了会报folder marker missing,Syncthing 会拒绝对这个目录做任何操作(防止误同步到错误的位置)。别删它,误删就停容器手工建回同名空目录。同理.stignore是忽略规则文件,也别当垃圾清掉- 多台机器同时改同一个文件 → 冲突副本堆积。同时编辑会生成
文件名.sync-conflict-20261007-093000-ABCDEFG.txt,两边内容都在,但文件会越积越多。共享目录里别放需要多人同时编辑的文档(那种场景该用笔记/协作文档,比如第 7 期 Memos) - 相册/媒体库目录直接同步,触发全库重扫。往 Immich / Jellyfin 的库目录里同步大量文件,会让这些服务反复重扫。做法是同步到中转目录,再由外部脚本 move 进库,或者至少同步完成后再手动触发扫描
/rest/events长时间挂住不动。事件流是长连接(?timeout=60表示最多阻塞 60 秒返回),写监控脚本时要用curl -N关掉缓冲,别加--max-time太短- 以为它是备份。它镜像当前状态——本地删了、对端跟着删。要版本历史请开 versioning,或者交给第 21 期 Kopia
- 在容器里点了「检查更新」却永远升不了级。容器场景升级 = 换镜像(
docker compose pull && docker compose up -d)。界面里的自动升级对容器无效,所以建议STNOUPGRADE=1把它关掉
备份
要备份的只有 config 目录,同步的数据本身不算备份(它是对端的一份镜像,不是历史归档):
# 配置 + 密钥:丢了设备 ID 会变,所有对端要重新加
/opt/syncthing/config/
├── config.xml # 全部配置(含 GUI 密码哈希、API Key、设备/目录定义)
├── cert.pem / key.pem # 本设备身份(设备 ID 由它派生)
├── https-cert.pem # 界面自签证书(不用 HTTPS 就无所谓)
├── csr.pem
└── ../data/index-v0.14.0.db # 或 index-*.db,索引数据库
# 真正要备份的:整个 config 目录(几十 KB ~ 几十 MB)
# 用第 21 期 Kopia 快照配置目录
kopia snapshot create /opt/syncthing/config
# 或者临时手动打一份(停容器更稳,SQLite 有 WAL)
docker stop syncthing
tar czf /root/syncthing-config-$(date +%F).tar.gz -C /opt/syncthing config
docker start syncthing
| 东西 | 丢了会怎样 | 要不要备份 |
|---|---|---|
config/config.xml |
所有设备、目录、密码、API Key 全没 | 必须 |
config/key.pem |
设备 ID 变化,对端全部要重新添加 | 必须 |
| 索引数据库 | 首次启动重新全量扫描(大目录可能几十分钟),不会丢数据 | 可选 |
| 同步目录里的文件 | —— | 按它本身的价值决定,别把"同步"当"备份" |
顺手也可以把要保留的目录用 versioning 兜一层:界面里「文件夹 → 高级 → 文件版本控制」选 Staggered,保留 maxAge 内的旧版本,被覆盖/删除的文件会在 .stversions 目录里留一份。这是 Syncthing 里唯一近似"时间机器"的能力。
小结
适合谁
- 有多台机器、想让某个目录始终一致的人:Mac / 家里的 NAS / 云主机 / 手机之间互同步,这是它的主战场
- 不接受把文件放到第三方网盘的人:端到端加密,中继节点看不到内容,也没有"某天服务关停"的风险
- 需要在服务器上同步但不方便装网盘客户端的人:一个容器 + 几个端口,headless 环境完美适配
- 想给不信任的主机放一份加密副本的人:
receive-encrypted模式就是为这个设计的 - 家里 NAS + 云主机互备的人:配合第 21 期 Kopia,或者直接用 Syncthing 做异地副本(注意:是副本不是备份)
不适合谁
- 想找一个"云端硬盘"的人。它没有中心存储,两台设备里必须有一台在线
- 需要用户体系、分享链接、权限分级的人。它就是设备间对等,没有账号概念
- 需要历史版本、回收站、误删恢复的人。那是备份工具的活(第 21 期 Kopia)
- 想选择性拉取目录里某几个子目录的人。粒度和目录结构绑死,
ignore只能排除不能挑选
一句话总结:Syncthing 不解决"文件存在哪",它解决"文件怎么在所有机器上都一样"。它和网盘的区别是:网盘是"我放到云上,各端去取",Syncthing 是"各端互相看着对方,谁变了就传给谁"。前者依赖服务商,后者只依赖你自己的设备。配合第 22 期 Dozzle 看它的日志、第 1 期 Uptime Kuma 保活、第 13 期 ntfy 收告警,就是一个完整可运维的同步节点。
项目地址
- 官网:https://syncthing.net/
- 文档:https://docs.syncthing.net/
- GitHub:https://github.com/syncthing/syncthing
- 镜像:
syncthing/syncthing(Docker Hub)、ghcr.io/syncthing/syncthing(GitHub Container Registry) - 许可:MPL-2.0,89k stars,最新版 v2.1.6(2026-10-06)