当Syncthing设备持续显示“Disconnected”状态或日志频繁出现“no connection to device”错误时，建议按照以下顺序进行系统性排查：首先，核对设备ID与双向配对是否成功；其次，验证局域网IP地址及TCP 22000端口的网络连通性；接着，检查并关闭防火墙、AP隔离等网络限制，必要时配置端口转发规则；然后，确认Syncthing守护进程运行正常且配置文件有效；最后，检查共享文件夹内.stfolder标记文件的存在性及文件系统权限。
在Syncthing中添加了远程设备并保存配置后，设备状态却始终显示“Disconnected”，或日志不断提示“no connection to device”？这通常源于网络连通性、身份验证或服务运行状态异常。本文提供一份从基础到进阶的完整排查指南，帮助您逐步诊断并解决Syncthing连接失败问题。
一、验证设备ID与配对状态
连接建立失败的首要原因往往是设备ID输入错误或配对流程未完成。Syncthing要求双方设备必须完成双向确认，单方面添加无法建立有效连接。
1. 在源设备的Syncthing Web管理界面（默认地址为 https://127.0.0.1:8384），进入左侧「设备」菜单，点击「添加远程设备」，准确粘贴目标设备的完整设备ID（注意包含 ABCD-... 格式的前缀）。
2. 立即前往目标设备的Web界面，通过「操作」→「显示设备 ID」获取其ID，仔细比对与源设备所填ID是否完全一致。需特别注意字母大小写及连字符位置，任何字符差异都会导致配对失败。
3. 在目标设备界面右上角查看是否有待处理的配对通知弹窗。如有，点击「接受」完成配对；如无，可尝试刷新页面或重启Syncthing服务，以重新触发配对请求。
4. 最后，确认双方设备列表中，对方设备的「地址」字段是否为空。若该字段为空，通常表明局域网自动发现机制失效，此时需要进入下一步，通过手动指定地址来建立连接。
二、检查本地网络发现与端口连通性
Syncthing默认通过UDP端口21027进行局域网广播以实现设备自动发现。若网络环境存在隔离或防火墙限制，该机制可能失效。此时，手动指定IP地址并测试核心同步端口（TCP 22000）的连通性至关重要。
1. 在源设备的「设备」设置页面，找到目标设备条目，点击右侧「编辑」图标，展开「地址」配置区域。
2. 删除默认的 dynamic 地址条目，手动添加目标设备的局域网IP地址及端口，格式示例：tcp://192.168.1.100:22000（请替换为目标设备的真实内网IP）。
3. 在源设备的命令行终端中，执行网络连通性测试命令：nc -zv 192.168.1.100 22000。若返回“succeeded”表示端口连通正常；若出现连接超时或拒绝，则问题可能源于防火墙或路由器策略。
4. 同时需在目标设备上确认Syncthing正在监听22000端口。执行 lsof -i :22000（Linux/macOS）或 netstat -ano | findstr :22000（Windows），查看输出中是否存在Syncthing进程。
三、排查防火墙与网络策略限制
操作系统防火墙或路由器中的高级设置（如AP隔离）常会阻止Syncthing所需的网络流量，导致设备无法相互通信。
1. 为快速诊断，可在目标设备上临时禁用系统防火墙：Linux系统执行 sudo ufw disable，Windows系统可在“高级安全防火墙”中暂时关闭相关入站规则。
2. 登录Wi-Fi路由器管理后台，检查是否启用了「AP隔离」或「客户端隔离」功能。此功能会阻止同一无线网络下的设备间直接通信，必须将其关闭。
3. Windows用户需额外检查：进入「Windows Defender 防火墙」→「允许应用通过防火墙」，确保 syncthing.exe 在“专用网络”和“公用网络”中均被勾选允许。
4. 若设备位于不同局域网或需从外网访问，则需在路由器中配置端口转发。规则为：将外部端口22000的TCP/UDP流量转发至内部目标设备的IP地址及22000端口。
四、验证 Syncthing 守护进程运行状态
连接问题有时并非源于网络，而是Syncthing服务本身未正常运行、意外退出或端口被占用所致。
1. 在目标设备终端中确认Syncthing进程状态：使用 ps aux | grep syncthing（Linux/macOS）或 tasklist | findstr syncthing（Windows）命令检查。
2. 若未发现进程，则手动启动Syncthing：syncthing -no-browser -logflags=0。启动时注意观察终端输出，若出现“address already in use”类错误，表明22000端口已被其他程序占用。
3. 若日志提示“failed to load config”或“invalid json”，可能是配置文件损坏。建议先备份 ~/.config/syncthing/config.xml 文件，然后将其删除，重启Syncthing服务以生成全新默认配置。
4. 在源设备Web界面中，点击「操作」菜单选择「重启」。此操作可强制刷新所有连接状态，有时能清除因状态缓存导致的设备“假离线”现象。
五、检查 .stfolder 标记与文件夹同步状态
设备连接显示正常但同步迟迟未开始时，问题往往出在共享文件夹状态异常，导致Syncthing拒绝建立数据通道。
1. 在目标设备上，定位用于接收文件的共享文件夹根目录，确认其中存在名为 .stfolder 的隐藏文件夹。若缺失，请手动创建空文件夹，并确保运行Syncthing的系统用户具备读写权限。
2. 返回源设备Web界面的「文件夹」页面，找到对应共享文件夹，点击右侧「编辑」，查看「状态」列显示内容。若为“已暂停”或“忽略”，点击旁边的「恢复」按钮激活同步。
3. 在目标设备终端中，进入共享文件夹路径，执行 ls -la | grep stfolder。检查 .stfolder 文件夹的所有者是否与运行Syncthing的用户一致。若Syncthing以非root权限运行，则该文件夹不应属于root用户。
4. 若文件夹状态持续显示“扫描中”超过十数分钟，可尝试右键点击该文件夹选择「立即扫描」。若扫描仍异常缓慢，需考虑磁盘I/O负载过高（如NAS正在执行其他重任务）导致的响应延迟。
