Syncthing Docker镜像文档

1. 镜像概述和主要用途

1.1 概述

Syncthing是一个开源的连续文件同步程序，旨在在多台计算机之间安全、自动地同步文件。Docker镜像封装了Syncthing应用及其运行环境，提供跨平台一致的部署方式，简化安装流程并隔离应用资源。

1.2 主要用途

• 多设备间文件实时同步
• 跨平台数据共享（Windows/macOS/Linux）
• 去中心化文件备份与同步
• 无需依赖第三方云服务的私有数据同步

2. 核心功能和特性

2.1 核心功能

• 双向实时同步：自动检测文件变更并同步，支持断点续传
• 分布式架构：设备间直接通信，无需中心服务器
• Web管理界面：通过浏览器配置和监控同步状态
• 版本控制：支持文件历史版本管理，防止意外删除

2.2 关键特性

• 数据安全优先：采用TLS加密传输，文件完整性校验，防止数据损坏
• 安全防护：设备认证机制，防止未授权访问和数据泄露
• 易用性设计：直观的Web界面，自动发现局域网设备
• 自动化操作：最小化用户干预，支持后台自动运行
• 跨平台兼容：支持所有主流操作系统，兼容低配置设备
• 隐私保护：数据仅在用户设备间流转，无第三方数据存储

3. 使用场景和适用范围

3.1 适用场景

• 个人用户：多设备（电脑、笔记本、服务器）文件同步
• 家庭环境：家庭成员间共享媒体文件、文档
• 小型团队：项目文件协作同步，替代传统文件服务器
• 备份策略：重要数据多设备分布式备份

3.2 适用范围

• 个人或小型团队（10台设备以内推荐）
• 需要数据隐私保护的场景
• 对同步速度和可靠性有要求的环境
• 跨网络（局域网/互联网）设备同步需求

4. 详细使用方法和配置说明

4.1 环境要求

• Docker Engine 1.13.0+
• Docker Compose（可选，用于复杂部署）
• 至少100MB磁盘空间（不含同步文件）
• 网络连通性（设备间需访问指定端口）

4.2 基本Docker运行命令

bash
docker run -d \
  --name syncthing \
  --hostname=syncthing-device \  # 自定义设备名称（可选）
  -p 8384:8384 \                 # Web管理界面端口
  -p 22000:22000/tcp \           # 设备通信TCP端口
  -p 22000:22000/udp \           # 设备通信UDP端口
  -p 21027:21027/udp \           # 本地发现端口（可选）
  -v /path/to/config:/var/syncthing/config \  # 配置文件持久化
  -v /path/to/sync:/var/syncthing/Sync \      # 默认同步文件夹
  -e PUID=1000 \                 # 运行用户ID（使用`id -u`获取）
  -e PGID=1000 \                 # 运行组ID（使用`id -g`获取）
  -e STGUIADDRESS="0.0.0.0:8384" \  # Web界面绑定地址
  --restart=unless-stopped \     # 自动重启策略
  syncthing/syncthing:latest

4.3 Docker Compose配置示例

创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  syncthing:
    image: syncthing/syncthing:latest
    container_name: syncthing
    hostname: home-sync-server  # 设备名称，在Web界面显示
    ports:
      - "8384:8384"           # Web管理端口
      - "22000:22000/tcp"     # 数据同步TCP端口
      - "22000:22000/udp"     # 数据同步UDP端口
      - "21027:21027/udp"     # 局域网发现端口
    volumes:
      - ./syncthing-config:/var/syncthing/config  # 配置目录
      - ./documents:/var/syncthing/Documents      # 文档同步目录
      - ./photos:/var/syncthing/Photos            # 照片同步目录
    environment:
      - PUID=1000                # 宿主机用户ID
      - PGID=1000                # 宿主机用户组ID
      - STGUIADDRESS=0.0.0.0:8384 # 允许外部访问Web界面
    restart: unless-stopped      # 容器退出时自动重启

启动服务：

bash
docker-compose up -d

4.4 配置参数详解

4.4.1 端口映射

4.4.2 数据卷挂载

提示：如需同步多个文件夹，添加多个-v参数（或在compose文件volumes中配置），并在Web界面中分别创建对应的同步文件夹。

4.4.3 环境变量

4.5 首次配置流程

1. 访问Web界面：启动容器后，通过[***]访问管理界面
2. 安全设置：首次登录需设置管理员用户名和密码（强烈建议）
3. 获取设备ID：在"操作"→"显示ID"中获取当前设备的唯一标识符
4. 添加远程设备：在"设备"页面点击"添加远程设备"，输入对方设备ID和名称
5. 配置同步文件夹：
   • 点击"添加文件夹"，设置文件夹标签和容器内路径（如/var/syncthing/Documents）
   • 在"共享"选项卡中选择要同步的远程设备
   • 确认后文件将自动开始同步

5. 注意事项

• 权限管理：确保宿主机挂载目录权限正确，PUID/PGID应与宿主机目录所有者匹配，避免文件读写失败
• 防火墙配置：跨网络同步需确保22000端口（TCP/UDP）在防火墙中开放
• 数据备份：定期备份config目录，防止配置丢失导致设备配对信息丢失
• 镜像更新：定期更新镜像获取安全补丁和新功能：

  bash
  docker pull syncthing/syncthing:latest
  docker restart syncthing
  

• 性能优化：大量小文件同步可调整"高级设置"中的批处理参数，大文件同步建议使用有线网络

6. 相关资源

• ***文档：Syncthing文档站点
• Docker镜像：Docker Hub - syncthing/syncthing
• GitHub项目：syncthing/syncthing
• 社区支持：Syncthing论坛
• 安全说明：Syncthing安全页面