Syncthing同步故障排查：加密密码配置引发的同步停滞问题分析

问题现象

在使用Syncthing进行文件同步时，用户遇到两个设备间同步突然停滞的情况。主要症状表现为：

• 发送端设备(bednaArch)持续显示"syncing xx%"状态且无法完成
• 接收端设备(bednaLaptop)显示"out of sync"状态
• 临时文件(.tmp)会被创建，但实际文件内容无法传输
• 重置数据库(--reset-database)和重置增量(--reset-deltas)操作均无效

环境配置

• 操作系统：Arch Linux和Manjaro Linux
• 文件系统：Btrfs(包含/和/home子卷)
• Syncthing版本：v1.28.0
• 网络配置：仅使用IPv4(tcp4://0.0.0.0:21027)
• 运行方式：systemd用户服务

根本原因分析

经过深入排查，发现问题源于文件夹加密密码的配置冲突。具体表现为：

1. 用户在文件夹共享设置中启用了密码保护
2. 但另一端设备并未以"接收加密"模式接受该共享
3. 这种配置不一致导致同步协议无法正常建立
4. 系统日志中会出现"数据已加密但不接受加密数据"的提示

解决方案

1. 移除密码保护：

   • 在Syncthing Web界面中导航至有问题的文件夹设置
   • 在"共享"选项卡中移除所有密码设置
   • 确保两端设备都执行此操作

2. 替代安全方案：

   • 如需增强安全性，建议采用以下替代方案：
     • 精确指定同步IP地址而非使用0.0.0.0
     • 配置防火墙规则限制访问
     • 使用专用网络连接建立专用网络

3. IPv6相关配置：

   • 虽然Sync Protocol Listen Addresses设置为IPv4
   • 但Local Announce仍默认使用IPv6([ff12::8384]:21027)
   • 在完全禁用IPv6的环境中，建议在配置文件中显式禁用IPv6宣告

最佳实践建议

1. 加密配置一致性：

   • 如果确实需要加密传输，确保两端配置匹配
   • 发送端设置密码后，接收端必须选择"接收加密"模式

2. 网络配置：

   • 对于纯IPv4环境，建议在配置文件中明确设置：

     [options]
     localAnnounceEnabled = false
     globalAnnounceEnabled = false
     

3. 监控与日志：

   • 启用fs、model、scanner等关键模块的日志记录
   • 定期检查同步状态和日志输出

4. 故障恢复流程：

   • 首先检查两端文件夹配置是否一致
   • 查看系统日志获取详细错误信息
   • 尝试移除高级功能(如加密)进行基础测试

技术原理深入

Syncthing的加密功能实现机制：

• 当在文件夹设置中启用密码时，系统会使用该密码派生加密密钥
• 所有传输数据都会经过加密处理
• 接收端必须使用相同密钥才能解密数据
• 若接收端未配置为加密接收模式，会导致协议握手失败
• 这种失败通常表现为同步停滞而非明确错误，增加了排查难度

通过理解这一工作机制，用户可以更有效地配置和管理Syncthing的加密功能，避免类似同步问题的发生。