十两东日的随想

④ Syncthing 个人网盘：从 Docker 部署到直连/QUIC、反代与排障全记录

目标：用 Docker Compose 在服务器上部署 Syncthing，通过 Nginx 反向代理 + HTTPS 暴露管理界面，数据通道走 直连 TCP/UDP/QUIC；同时沉淀踩坑和解决方案。

说明：文中已脱敏，示例域名以 sync.example.com 表示，公网地址以 SERVER_IP 表示。默认以 admin 账号、家目录 /home/admin 操作（非 /root）。

【实操教学】

一、目标与设计

  • 管理界面（Web GUI）只在本机回环监听 → 通过 Nginx/443 对外提供：https://sync.example.com

  • 数据同步通道走 22000/TCP + 22000/UDP(QUIC)，实现直连（可绕过中继，加速）。

  • 文件与配置全部持久化到 admin 家目录，升级/重建容器不丢数据。

二、创建目录与获取 UID/GID（写 compose 前先拿到值）

mkdir -p /home/admin/syncthing/{config,data}        # mkdir：创建目录；-p：父目录不存在时一并创建
# config：放 Syncthing 配置
# data：示例资料库（你也可换成其他路径）

id -u admin                                          # id -u：查看用户 UID（User ID）
id -g admin                                          # id -g：查看用户 GID（Group ID）
# 记下这两个数字，下面 PUID/PGID 要用到

术语

  • UID/GID：运行容器时“以哪个系统用户身份读写文件”。用 admin 的 UID/GID，避免生成 root 属主文件导致权限问题。

三、编写

docker-compose.yml

cd /home/admin/syncthing                              # cd：切换目录（change directory）
nano docker-compose.yml                               # nano：打开编辑器

粘贴以下（V2 写法，无 version: 顶级字段）：

services:
  syncthing:
    image: syncthing/syncthing:latest                 # 官方镜像
    container_name: syncthing
    restart: unless-stopped                           # 异常退出自动重启
    environment:
      - PUID=YOUR_UID                                 # 用上一步的 UID，例如 1003
      - PGID=YOUR_GID                                 # 用上一步的 GID，例如 1003
      - TZ=Asia/Shanghai                              # 时区
    volumes:
      - /home/admin/syncthing/config:/var/syncthing   # 配置持久化
      - /home/admin/syncthing/data:/data              # 示例资料库（容器内路径 /data）
    # 管理口仅回环访问 → 通过 Nginx 反代
    ports:
      - "127.0.0.1:8384:8384"                         # Web GUI（回环，不对公网）
    # 数据通道：直连所需（如只走中继，可先注释，后续再启）
    # 若要直连/QUIC，请取消注释这两行，并在云防火墙放行 22000/TCP+UDP
      - "0.0.0.0:22000:22000/tcp"                     # 数据通道 TCP（公网可达）
      - "0.0.0.0:22000:22000/udp"                     # 数据通道 UDP（QUIC）

保存（Ctrl+O 回车）→ 退出（Ctrl+X）。

说明

  • 管理界面只在 127.0.0.1:8384 监听，不会外露；通过 Nginx 的 443 访问。

  • 数据通道用 0.0.0.0 映射 22000（TCP/UDP），用于跨设备直连。

  • 初期只想“能用”，可以先注释 22000 两行，完成反代与基础同步后再放开直连。

四、启动与基本自检

docker compose up -d                                   # up -d：按编排启动并后台运行
docker compose ps                                      # ps：查看状态与端口映射
curl -I http://127.0.0.1:8384                         # -I：只看响应头；200/302 表示 GUI 后端工作正常

五、配置 Nginx 反向代理（宝塔面板）

1）在面板添加站点：sync.example.com，类型选静态。

2）站点 → 反向代理：目标 URL 填 http://127.0.0.1:8384/ → 启用。

3）站点 → SSL：申请 Let’s Encrypt → 强制 HTTPS。

4）确保反代段包含这 6 行“黄金请求头”（避免样式/JS/URL问题）：

proxy_set_header Host              $host;          # 传递原始域名
proxy_set_header X-Real-IP         $remote_addr;   # 传递客户端 IP
proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;        # 传递 https/http 协议
proxy_set_header X-Forwarded-Host  $host;
proxy_set_header X-Forwarded-Port  $server_port;

现在访问 https://sync.example.com，应能看到 Syncthing 的 Web 界面。

六、首登与资料库（Folder）创建

1）首次访问会引导设置 GUI 用户/密码（请使用强密码）。

2）点击 Add Folder（新增资料库）：

  • Folder Label：Notes（举例）

  • Folder Path：/data/Notes（容器内路径；我们映射到了宿主机 /home/admin/syncthing/data/Notes）

  • Advanced → File Versioning：可先关闭（后期再开）

  • 保存后 Syncthing 会在宿主机对应位置创建文件夹。

如果你在 Mac/PC 客户端也加了 Notes 并共享给服务器，很快会开始同步。

七、直连/QUIC 加速（可选但推荐）

1）开启端口映射（你在 compose 里已写）

  • 取消注释（或保留）以下两行：

- "0.0.0.0:22000:22000/tcp"
- "0.0.0.0:22000:22000/udp"

  • 应用变更：

cd /home/admin/syncthing                      # 确保在项目目录
docker compose up -d                          # 让编排按新配置重建
docker compose restart syncthing              # 建议重启容器一次（实践表明更干净）

2）云防火墙放行

  • 允许 22000/TCP 与 22000/UDP（仅实例入站）。80/443/22 保持原状。

3）客户端侧检查（以 Mac 客户端为例）

  • 打开 Syncthing → Actions → Settings → Connections：

    • 勾选 TCP 与 QUIC（默认都是开的）；

    • 保持 NAT traversal（NAT 穿透）开启；

    • 若你有公网受限，可在 Global Discovery 保持开启（发现服务）。

  • 在 Devices → 服务器设备 → Edit：

    • 可在 Addresses 增加 tcp://SERVER_IP:22000, quic://SERVER_IP:22000 强化直达（选填）。

4）验证连接类型

  • 设备视图里，Address/Type 显示 QUIC 或 TCP (WAN) 即表示广域网直连；

  • 如果总是走 Relay（中继），多半是端口未通或有中间设备屏蔽了 UDP。

实战经验：改完端口与规则后，重启容器（docker compose restart syncthing）往往有助于尽快切到 QUIC。

八、常用运维

cd /home/admin/syncthing                         # 切到项目目录
docker compose ps                                # 查看状态/端口映射
docker compose logs -f syncthing                 # 实时日志（Ctrl+C 退出）
docker compose restart syncthing                 # 重启容器（配置/端口变更后建议）
docker compose down                              # 停止并移除容器（数据仍保留在 /home/admin/syncthing）

暂停同步（临时）：

  • Web GUI 某资料库右上角 → Pause；

  • 或暂停某设备连接。

删除服务器端某资料库的文件（谨慎）：

rm -rf /home/admin/syncthing/data/Notes/*        # rm -rf：递归强制删除；*：删除 Notes 下所有内容
# 建议先在 GUI 里暂停该资料库的同步，再做删除，避免一边删一边又被对端同步回来

忽略文件规则 .stignore（放在资料库根目录）：

nano /home/admin/syncthing/data/Notes/.stignore  # 新建或编辑忽略规则
# 例如：
# *.tmp
# node_modules/
# .DS_Store

踩坑与解决方案

  1. 改了配置仍旧 TCP，不走 QUIC

    • 问题点：UDP/22000 未放行、compose 未映射 UDP、客户端设置未启用 QUIC、容器未重启。

    • 解决：同时满足 映射 UDP + 云防火墙 UDP 放行 + 客户端启用 QUIC，并 docker compose restart syncthing。

  2. “创建文件夹失败”/ 权限错误

    • 问题点：宿主机目录属主不对或 PUID/PGID 未设置为 admin。

    • 解决：确认 PUID/PGID；必要时：

chown -R admin:admin /home/admin/syncthing

    • 重启容器后再试。

  2. Web 管理界面走 https，但样式丢失/混合内容

    • 问题点：反向代理未传 X-Forwarded-Proto $scheme 或 Host $host。

    • 解决：在反代段补齐 6 行黄金请求头，强制刷新缓存。

  3. 上传了大文件，想“紧急刹车”

    • 在 Web GUI 暂停该资料库或该设备；

    • 或容器层面 docker compose stop（全局停），删完再 up -d。

  4. .stignore 提示找不到

    • 你把 .stignore 放在了错误位置。它必须位于资料库根目录（例如 /home/admin/syncthing/data/Notes/.stignore），且对该资料库生效。

  5. 反代后 403/500，但本机 127.0.0.1:8384 正常

    • 问题点：Nginx 站点配置冲突、未重载、或 SSL/跳转循环。

    • 解决：检查站点 error_log；确认 80→443 仅做 301 跳转；重载 Nginx。

【深度解析与知识扩展】

  • 为什么管理口只绑回环？

    减少公网暴露面；所有外部访问统一走 443，由 Nginx 做 TLS、访问控制与日志审计。

  • QUIC 的优势与前提

    QUIC 基于 UDP，RTT 低、握手快、弱网表现更好；但前提是 UDP/22000 可达、两端都启用 QUIC 且中间网络不屏蔽。

  • Compose v2 的“声明式”思维

    变更端口/环境变量/卷映射 → docker compose up -d 即“收敛到新状态”；不是“重跑一次”，而是按差异重建。

  • 与 Uptime Kuma 联动

    对 https://sync.example.com 使用 HTTP(s)–关键字 监控；另外加一条 TCP 22000 监控盯住服务本体，两条组合定位更快。

交付核对清单（Checklist）

  • https://sync.example.com 打开正常（反代 + 强制 HTTPS）

  • Web GUI 仅回环监听（ss -tulpen | grep 8384 显示 127.0.0.1:8384）

  • 22000/TCP+UDP 已在云防火墙放行（如需直连）

  • Compose 已映射 22000/tcp+udp（如需直连/QUIC）

  • 客户端显示 QUIC 或 TCP (WAN)（非 Relay）

  • .stignore 生效在正确的资料库根目录

  • 常用命令与日志路径熟悉（便于排障）

 

Previous Article
Next Article

发表回复

Your email address will not be published. Required fields are marked *.

*
*

Copyright © 2025 十两东日的随想. All Rights Reserved.

鄂ICP备2025140583号-1 | 鄂公网安备42011102005804号

近期文章

近期评论

您尚未收到任何评论。

归档

分类