Syncthing Docker 镜像文档

镜像概述和主要用途

本镜像是基于 tianon/docker-syncthing 项目构建的 Docker 化 Syncthing 应用，提供开源的连续文件同步功能。Syncthing 是一个去中心化的 P2P 文件同步工具，旨在安全、高效地实现多设备间的文件实时同步，无需依赖第三方服务器。

核心功能和特性

去中心化 P2P 同步：直接在设备间建立加密连接同步文件，无需中心服务器，保障数据隐私
跨平台兼容：支持 Linux、Windows、macOS、Android 等多种操作系统，实现多设备无缝协作
文件版本控制：自动保留文件历史版本，支持恢复误删或修改的文件
加密传输与存储：同步过程采用 TLS 加密，文件元数据和内容传输全程加密
Web 管理界面：通过内置 Web UI（默认端口 8384）可视化配置同步节点、文件夹和权限
增量同步：仅传输文件变更部分，减少带宽占用，提升同步效率

使用场景和适用范围

个人文件同步：跨设备（电脑、手机、平板）同步文档、照片、音乐等个人数据
团队协作共享：小型团队实时同步项目文件，替代传统 FTP 或网盘，降低数据泄露风险
异地备份方案：将重要文件同步至异地设备，实现分布式备份，提高数据可靠性
边缘设备同步：物联网或嵌入式设备间的配置文件、日志数据同步

使用方法和配置说明

基础依赖

Docker 19.03+ 或 Docker Compose 2.0+
设备间网络互通（需开放同步端口，或配置端口转发穿透防火墙）

核心配置参数

1. 数据卷挂载

本地路径	容器路径	用途说明
`/path/to/config`	`/var/syncthing/config`	存储 Syncthing 配置文件（节点信息、证书等）
`/path/to/data`	`/var/syncthing/Sync`	待同步的文件目录（可自定义多个文件夹）

2. 端口映射

容器端口	协议	用途说明
8384	TCP	Web 管理界面端口（需外部访问时映射）
22000	TCP/UDP	设备间同步主端口（P2P 通信必备）
21027	UDP	本地网络设备发现端口（可选，用于自动发现局域网节点）

3. 环境变量

变量名	示例值	用途说明
`PUID`	`1000`	运行容器的用户 ID（避免权限问题，需与宿主机用户 ID 一致）
`PGID`	`1000`	运行容器的用户组 ID（同上）
`STNOUPGRADE`	`1`	禁用 Syncthing 自动更新（建议通过 Docker 镜像更新替代）

部署示例

1. Docker Run 命令

bash
docker run -d \
  --name syncthing \
  --restart unless-stopped \
  -p 8384:8384 \
  -p 22000:22000/tcp \
  -p 22000:22000/udp \
  -p 21027:21027/udp \
  -v /home/user/syncthing/config:/var/syncthing/config \
  -v /home/user/documents:/var/syncthing/Sync \
  -e PUID=1000 \
  -e PGID=1000 \
  tianon/syncthing:latest

2. Docker Compose 配置

创建 docker-compose.yml 文件：

yaml
version: '3.8'
services:
  syncthing:
    image: tianon/syncthing:latest
    container_name: syncthing
    restart: unless-stopped
    ports:
      - "8384:8384"       # Web UI
      - "22000:22000/tcp" # 同步主端口(TCP)
      - "22000:22000/udp" # 同步主端口(UDP)
      - "21027:21027/udp" # 本地发现端口
    volumes:
      - ./config:/var/syncthing/config  # 配置目录（宿主机当前目录下的 config 文件夹）
      - ./data:/var/syncthing/Sync      # 同步数据目录
    environment:
      - PUID=1000       # 替换为宿主机用户 ID（通过 `id -u` 查看）
      - PGID=1000       # 替换为宿主机用户组 ID（通过 `id -g` 查看）
      - STNOUPGRADE=1   # 禁用应用内自动更新（推荐通过 Docker 镜像更新）

启动命令：docker-compose up -d

初始化配置

容器启动后，通过 http://<宿主机IP>:8384 访问 Web UI
首次登录需设置管理员密码（路径：设置 > GUI > 密码）
添加同步节点：在“远程设备”页面输入目标设备的设备 ID（其他设备的 Syncthing 配置中获取）
配置同步文件夹：指定本地路径（容器内 /var/syncthing/Sync 或自定义挂载路径），并共享给目标节点

注意事项

权限管理：确保宿主机挂载目录的权限与容器内 PUID/PGID 匹配，避免文件读写失败（可通过 chown -R 1000:1000 /path/to/data 调整）
端口开放：若设备位于防火墙或 NAT 后，需手动转发 22000/TCP/UDP 端口，否则可能无法与外部节点建立连接
备份配置：定期备份 /path/to/config 目录，避免节点信息丢失导致同步中断
镜像更新：通过 docker pull tianon/syncthing:latest 获取最新镜像，替代应用内自动更新以确保容器兼容性