Syncthing 常见问题与排障
学习目标
- 掌握 Syncthing 常见错误的识别方法。
- 掌握网络连接问题的排查步骤。
- 掌握同步冲突与数据恢复的处理流程。
- 了解日志分析与诊断工具的使用。
- 建立系统化的故障排查思维。
前置条件
- 已完成 01_局域网同步仓库实战 的实践操作。
- Syncthing 已安装并尝试过配对与同步。
故障排查通用原则
在遇到 Syncthing 问题时，按以下层次依次排查：
┌─────────────────────────────────────┐
│ 1. 服务状态检查 │
│ • Syncthing 是否在运行？ │
│ • Web UI 是否能打开？ │
├─────────────────────────────────────┤
│ 2. 网络连通性检查 │
│ • 设备是否在同一局域网？ │
│ • 防火墙是否放行？ │
│ • 能否直连？ │
├─────────────────────────────────────┤
│ 3. 配置一致性检查 │
│ • 设备 ID 是否正确？ │
│ • 文件夹 ID 是否匹配？ │
│ • 共享权限是否正确？ │
├─────────────────────────────────────┤
│ 4. 日志分析 │
│ • 查看 Web UI 的最近日志。 │
│ • 使用诊断工具。 │
└─────────────────────────────────────┘
1. 安装与启动问题
问题：Syncthing 无法启动
可能原因与解决方案：
| 原因 | 解决方案 |
|---|---|
| 端口被占用（8384/22000/21027） | 修改 Syncthing 配置中的端口号，或结束占用端口的进程 |
| 权限不足 | 以管理员身份运行（Windows），或使用 sudo（Linux） |
| 配置文件损坏 | 停止 Syncthing，备份并删除配置目录，重新启动生成默认配置 |
配置目录位置：
- Windows：
%LOCALAPPDATA%\Syncthing\ - macOS：
~/Library/Application Support/Syncthing/ - Linux：
~/.config/syncthing/ - Android：
/sdcard/Android/data/com.github.catfriend1.syncthingfork/files/（实际路径可能因设备而异，可在 Syncthing-Fork 设置 → 关于中查看）
删除配置目录会丢失所有设备配对信息
删除配置目录前请先备份，或在删除前记录设备 ID 和共享配置。重新启动后 Syncthing 会生成新的设备 ID，需要重新配对。
问题：Web UI 无法访问
-
确认 Syncthing 进程正在运行：
- Windows：检查任务管理器中是否有
syncthing.exe或SyncTrayzor.exe。 - macOS/Linux：终端运行
ps aux | grep syncthing。 - Android：检查通知栏是否有 Syncthing-Fork 的运行图标（常驻通知 “Syncthing 正在运行”）。
- Windows：检查任务管理器中是否有
-
确认监听地址正确：
- 默认地址为
127.0.0.1:8384。 - 如果修改过，在 Syncthing 日志中查看实际监听的地址。
- 默认地址为
-
检查是否有其他程序占用了 8384 端口：
# Windows netstat -ano | findstr :8384 # macOS / Linux lsof -i :8384
2. 网络连接问题
问题：设备无法互相发现
排查步骤：
-
检查局域网连通性：
# 在设备 A 上 ping 设备 B 的 IP 地址 ping 192.168.1.x如果 ping 不通，检查：
- 两台设备是否连接到同一路由器/交换机。
- 是否开启了客户端隔离（AP Isolation）功能（常见于公共 Wi-Fi 或访客网络）。
-
检查 Syncthing 端口：
- Syncthing 使用 TCP 22000（数据传输）和 UDP 21027（本地发现）。
- 确认防火墙已允许这些端口通过专用网络：
- Windows：控制面板 → Windows Defender 防火墙 → 允许应用通过防火墙 → 确保 Syncthing 的 专用 已勾选。
- macOS：系统设置 → 网络 → 防火墙 → 添加 Syncthing 为例外。
- Linux：
sudo ufw allow 22000/tcp && sudo ufw allow 21027/udp - Android：系统防火墙通常不需配置。如果连接异常，检查 Syncthing-Fork 是否被省电策略限制（设置 → 应用 → Syncthing-Fork → 电池 → 选 无限制），以及是否授予了附近设备权限（Android 12+，用于局域网设备发现）。
-
检查路由器设置：
- 如果路由器启用了 AP 隔离 或 客户端隔离，同一 Wi-Fi 下的设备无法互相访问。请在路由器管理后台关闭该功能。
-
手动添加设备地址（如果不能自动发现）：
- 在 Web UI → 远程设备 → 编辑设备 → 地址 字段。
- 添加静态地址：
tcp://192.168.1.x:22000（将 x 替换为目标设备的 IP）。 - 这样可以绕过本地发现，直接连接指定地址。
问题：通过中继而非直连
症状：Web UI 显示连接地址为 relay://...，同步速度较慢。
解决方案：
- 确认两台设备在同一局域网。
- 关闭中继以强制直连：
- 设置 → 连接 → 取消勾选 启用中继。
- 两台设备都需操作。
- 启用 NAT 穿透（如果设备在不同子网）：
- 设置 → 连接 → 勾选 启用 NAT 穿透。
- 手动指定对方地址（最可靠）：
- 远程设备 → 编辑 → 地址 → 输入
tcp://192.168.x.x:22000。
- 远程设备 → 编辑 → 地址 → 输入
3. 同步问题
问题：文件夹状态持续为 “未同步”
可能原因与解决方案：
| 原因 | 解决方案 |
|---|---|
| 正在进行初始同步（大量文件） | 等待同步完成。可以在 Web UI 查看同步进度条。 |
| 文件夹 ID 不匹配 | 确认所有设备上共享文件夹的 文件夹 ID 完全一致（区分大小写）。 |
| 设备未连接 | 排查网络连通性问题（见上节）。 |
| .stignore 配置导致文件被忽略 | 检查 .stignore 文件中的规则是否过于宽泛。 |
| 文件权限问题 | 确认 Syncthing 对同步文件夹有读写权限。 |
| 磁盘空间不足 | 检查磁盘剩余空间，清理不必要的文件。 |
| 文件路径过长（Windows） | Windows 路径长度限制为 260 字符，移动文件夹到较浅的目录。 |
问题：同步速度很慢
可能原因与解决方案：
- 首次同步大量文件 → 耐心等待，首次同步会扫描所有文件并计算哈希。
- 通过中继而非直连 → 见上节”通过中继而非直连”的解决方案。
- 启用了速率限制 → 设置 → 连接 → 检查速率限制是否设置得太低。
- 磁盘 I/O 瓶颈 → 如果有大量小文件（如 Obsidian 的
.obsidian/缓存），同步可能变慢。可在.stignore中忽略缓存目录。 - 加密/校验计算负载 → Syncthing 会对传输数据进行加密和完整性校验，CPU 较弱的设备（如旧款笔记本）可能较慢。
问题：频繁出现冲突副本
原因： 同一文件在两台设备上几乎同时被修改。
减少冲突的策略：
- 等待同步完成再编辑：在开始编辑文件前，确认 Web UI 显示 最新（绿色）。
- 错开编辑时间：避免在多台设备上同时编辑同一文件。
- 使用仅发送/仅接收模式：如果某台设备只是展示用途，设为仅接收模式。
- 增大扫描间隔：减少频繁扫描导致的冲突机会。高级设置 → 扫描间隔设为
300秒（5 分钟）或使用 监视模式。
问题：文件被误删或误覆盖
恢复步骤：
-
如果启用了版本控制：
- 进入同步文件夹同级的
.stversions目录。 - 按时间戳查找被删除/覆盖前的版本。
- 将文件复制回原位置。
- 进入同步文件夹同级的
-
如果未启用版本控制：
- 立即在另一台已同步的设备上查找文件（如果文件是在本机被误删，另一台设备可能仍有副本）。
- 从另一台设备复制文件回来。
- 紧急操作：在另一台设备上暂停 Syncthing（防止同步删除操作传播），然后恢复文件。
-
如果所有设备都已同步删除：
- 从回收站/垃圾桶中找回（如果系统回收站未清空）。
- 从 Git 历史中恢复（如果仓库同时受 Git 管理）。
- 从定期备份中恢复。
版本控制是第一道防线
Syncthing 的文件版本控制是防止意外删除/覆盖的最有效手段。在实战章节中我们已经配置了简单版本控制，如果你还没有配置，请立即配置。
4. 配置与权限问题
问题：设备配对后无法同步文件夹
- 确认文件夹已共享给远程设备：
- Web UI → 编辑文件夹 → 共享 标签页 → 勾选目标设备。
- 确认远程设备已接受共享请求：
- 在远程设备的 Web UI 上查看是否有待接受的共享通知。
- 检查文件夹 ID 是否一致：
- 两台设备上同一个共享文件夹的 文件夹 ID 必须完全一致。
问题：Windows 上文件同步时提示权限错误
- 运行 SyncTrayzor 或 Syncthing 时 以管理员身份运行。
- 检查同步文件夹是否设置了 只读 属性。
- 如果文件夹在系统保护目录（如
C:\Program Files），请移动到用户目录（如D:\或C:\Users\你的用户名\）。
问题：macOS 上同步 .obsidian 文件夹中的文件被忽略
macOS 的文件系统事件可能与 Syncthing 的监听机制冲突。可以尝试：
- 编辑文件夹 → 高级 → 扫描间隔 设为
60（秒），同时取消勾选 “监视文件系统更改”。 - 或者忽略整个
.obsidian目录（通过.stignore），仅同步笔记内容（推荐）。
问题：Android 上无法选择仓库文件夹
Android 的存储访问框架（SAF） 可能限制对特定目录的访问：
- 确保 Syncthing-Fork 已授予文件和媒体权限（设置 → 应用 → Syncthing-Fork → 权限 → 允许文件和媒体）。
- 如果仓库在外置 SD 卡，部分 Android 版本可能无法直接访问，建议将仓库移到内部存储。
- 如果使用 Obsidian 且仓库位于
Obsidian应用的默认 Vault 目录，确保 Syncthing-Fork 有权限访问Android/data/md.obsidian/目录（Android 11+ 限制较严，建议将 Vault 放在外部存储如Documents/下）。
5. 日志与诊断工具
查看 Web UI 日志
- 在 Web UI 右上角点击 操作 → 日志。
- 日志按时间倒序显示，包含以下重要信息：
[WARN]或[ERROR]级别的警告/错误。- 连接建立/断开记录。
- 文件同步开始/完成记录。
- 你可以复制日志内容，在搜索引擎或 GitHub Issues 中查询。
导出诊断信息
- 在 Web UI 上点击 操作 → 诊断。
- 诊断信息包含：连接状态、设备列表、文件夹状态、最近错误等。
- 点击 保存 可导出为文本文件，在寻求帮助时提供。
命令行诊断
# 查看 Syncthing 进程是否运行
ps aux | grep syncthing
# 测试端口连通性（在设备 B 上测试设备 A 的 22000 端口）
telnet 192.168.1.x 22000
# 或使用（Windows PowerShell）
Test-NetConnection -ComputerName 192.168.1.x -Port 22000
# 查看 Syncthing 的详细日志
# 日志文件位置：
# Windows: %LOCALAPPDATA%\Syncthing\syncthing.log
# macOS: ~/Library/Application Support/Syncthing/syncthing.log
# Linux: ~/.config/syncthing/syncthing.log6. 故障排查流程图
当同步出现问题时，按照以下流程图操作：
同步出问题了吗？
│
├─ Syncthing 是否运行？ ─── 否 ──→ 启动 Syncthing
│
├─ 设备是否已连接？ ─── 否 ──→ 检查网络连通性
│ ├─ ping 对方设备
│ ├─ 检查防火墙
│ └─ 确认同一局域网
│
├─ 文件夹状态是否为 "最新"？ ─── 否 ──→ 检查文件夹配置
│ ├─ 文件夹 ID 是否一致
│ ├─ 共享权限是否勾选
│ └─ .stignore 是否误忽略
│
├─ 是否有冲突副本？ ─── 是 ──→ 手动合并或恢复
│
├─ 同步速度太慢？ ─── 是 ──→ 检查连接方式（直连/中继）
│ ├─ 关闭中继
│ └─ 检查速率限制
│
└─ 问题仍未解决？ → 查看日志 → 搜索 GitHub Issues → 寻求社区帮助
7. 获取帮助
当以上排查步骤均无法解决问题时，可以通过以下渠道获取帮助：
官方资源
- Syncthing 官方文档：https://docs.syncthing.net/
- GitHub Issues：https://github.com/syncthing/syncthing/issues
- Syncthing 论坛：https://forum.syncthing.net/
提交 Issue 前的准备
为帮助开发者快速定位问题，请在提交 Issue 时提供以下信息：
- 操作系统与版本：如 Windows 11 / macOS 15 / Ubuntu 24.04。
- Syncthing 版本：Web UI → 设置 → 关于 → 查看版本号。
- 问题描述：具体的错误现象、发生时间、触发操作。
- 日志片段：从 Web UI 日志中复制相关的
[WARN]/[ERROR]日志。 - 诊断信息：操作 → 诊断 → 保存并附上。
- 网络环境：是否在同一局域网、是否有特殊网络配置（代理/VPN/AP 隔离）。
练习任务
- 模拟一个常见故障场景（如关闭一台设备的防火墙），观察同步状态变化。
- 查看 Syncthing 的 Web UI 日志，找到最近一次同步完成或失败的记录。
- 在
.stignore中添加一行忽略.obsidian/workspace.json，确认该文件不再被同步。 - （选做）在两台设备上模拟同时编辑同一文件产生冲突，记录冲突副本的命名格式，并尝试恢复。
验收清单
- 能够按通用排查原则系统化定位问题。
- 能够检查网络连通性（ping / 端口检测）。
- 能够配置防火墙放行 Syncthing 端口。
- 能够查看和解读 Web UI 日志。
- 能够导出诊断信息用于寻求帮助。
- 能够在发生文件误删时通过版本控制恢复。
- 了解如何获取官方帮助（文档 / GitHub Issues / 论坛）。