Syncthing · 去中心化的连续文件同步程序 · 中文部署与使用全指南

项目仓库： https://github.com/syncthing/syncthing

开源协议：MPL v2 · 实现语言：Go · 容器镜像：syncthing/syncthing · 同步协议：BEP · 默认 GUI 端口：8384 · 同步端口：2200/TCP · 发现端口：21027/UDP · 容器内运行用户：UID/GID 1000（可用 PUID/PGID 改）

1 项目简介

Syncthing（仓库名 syncthing/syncthing）是一个连续文件同步程序：在两台或多台计算机之间持续同步文件。它用开放的 BEP（Block Exchange Protocol）协议，把你的多台设备连成一个去中心化的同步集群——不经过第三方中心化服务器，数据端到端加密直连。

官方把目标按重要性排序：安全防数据丢失 > 防攻击者窃取 / 篡改 > 易用 > 自动 > 处处可运行 > 服务个人用户。

1.1 核心信息一览

1.2 适用场景

• 多台电脑 / 服务器 / 手机之间持续同步文件夹，不依赖公有云盘。
• 想让数据在自己设备间直连、端到端加密，不经过第三方中转。
• 个人或家庭跨设备备份、同步文档、相册、代码目录。

1.3 能力边界（官方口径）

• 核心目标是保护数据不被损坏、不被窃听 / 篡改；个人用户优先。
• 官方强烈建议 Docker 用 host 网络模式：默认桥接网络下 Syncthing 只能看到容器内网 172.17.0.0/16 地址，会破坏局域网直连、传输速率下降。
• 安全漏洞请邮件 security@syncthing.net，不要发到论坛或 issue。

2 功能特性

• 连续同步：多设备间实时同步变更。
• 端到端加密：基于 TLS / BEP，不经过第三方服务器。
• 去中心化：无中心服务器，设备间直连；打洞失败时才走中继。
• Web GUI：浏览器管理设备、文件夹、忽略规则。
• 多平台：Windows / macOS / Linux 及社区 GUI 封装。
• 签名发布：Release 二进制 GPG 签名，macOS/Windows 二进制还做代码签名；内置自动升级机制（部分发行渠道禁用）。
• 跨编译：go run build.go 即可产出二进制。

3 官方界面预览

封面为 Syncthing 官方文字标识。Web GUI（默认 http://127.0.0.1:8384）用于管理设备与文件夹。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• 任意一台要参与同步的设备；Docker 方式需 Docker 环境。
• 准备好要同步的目录（容器内挂到 /var/syncthing）。

5.2 端口

官方建议容器用 host 网络模式，让 Syncthing 自己决定监听接口与端口。

6 方式一：Docker 部署（官方）

docker pull syncthing/syncthing
docker run --network=host -e STGUIADDRESS= \
    -v /wherever/st-sync:/var/syncthing \
    syncthing/syncthing:latest

compose 等价：

---
version: "3"
services:
  syncthing:
    image: syncthing/syncthing
    container_name: syncthing
    hostname: my-syncthing
    environment:
      - PUID=1000
      - PGID=1000
      - STGUIADDRESS=
    volumes:
      - /wherever/st-sync:/var/syncthing
    network_mode: host
    restart: unless-stopped
    healthcheck:
      test: 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

6.1 环境变量

7 方式二：源码构建

# 从 Release 解压源码或 git clone 后
go run build.go
# 二进制产物在 ./bin

详细构建指南见官方文档 dev/building.html。后台常驻示例见仓库 etc/ 目录（systemd 等）。

8 配置项说明

• 配置与数据库：首次启动后在 GUI 或配置目录生成；默认 GUI 监听 127.0.0.1:8384。
• GUI 安全：镜像默认监听 0.0.0.0:8384；若改让 GUI 对外可达，务必设置用户名密码并启用 TLS（官方明确要求）。
• 设备（Device）：每台设备有唯一 ID，互相添加设备 ID 并共享文件夹才能同步。
• 忽略规则：.stignore 排除不需要同步的文件。

9 常用运维命令

# 拉取更新
docker pull syncthing/syncthing
# 重启 / 日志
docker compose up -d
docker logs -f syncthing
# 健康检查（compose 里已内置）
curl -fkLsS -m 2 127.0.0.1:8384/rest/noauth/health

10 常见故障排查

• 局域网同步慢 / 打洞失败：默认桥接网络下 Syncthing 只看到容器内网地址，改用 network_mode: host。
• GUI 对外暴露风险：默认仅监听 127.0.0.1；要对外访问必须配密码 + TLS，别把 8384 裸奔公网。
• 文件权限不对：用 PUID/PGID 对齐宿主机目录属主。
• 设备互相找不到：确认 2200/TCP 与 21027/UDP 放行；手动配置设备地址兜底。
• 升级来源：用发行版包管理或官方镜像；内置自动升级在部分渠道被禁用。

11 风险与合规说明

• MPL v2 许可；数据端到端在你自己设备间，不存在第三方云，但仍需自行备份——同步不是备份，误删会同步到所有设备。
• GUI 对外暴露必须鉴权 + TLS，否则等同把同步数据管理权交给网络。
• 安全漏洞报告走 security@syncthing.net，勿在 issue 公开。
• 本文命令、端口、环境变量来自官方 README 与 README-Docker，随版本可能调整，以官方文档为准。