故障排查

大多数问题属于三种之一：两台设备互相看不见、它们没配上对、或者内核需要的某个东西缺失。synra doctor 直接 回答第三种，并把前两种范围缩小。

先跑诊断

synra doctor

它探测的是这台机器而不是网络，每个结果是三种之一：

结果	含义
ok	探针跑了，答案良好
warn	探针跑不了，或发现了不致命的东西
fail	在修好之前，内核无法在这里运行

--failures-only 只打失败的，--output json 打一个 JSON 值，方便贴进报告。

求助时把报告一起带上

--output json 就是为"能直接粘贴"设计的。它说明了哪个平台、哪些目录、以及哪些探针跑不了 —— 这三样正是帮你 的人否则要反问你的东西。

每个探针的含义

探针	失败时意味着
tcp_port_available	别的东西占着传输端口
discovery_port_available	别的东西占着发现端口
discovery_udp_available	组播发现绑不上
network_stack	这台机器根本开不了 socket
firewall	平台需要加一条规则
data_dir_writable	当前用户对数据目录没有写权限
disk_space	数据目录拒绝写入
clock_sanity	系统时钟偏得足以破坏配对
webview_version	没有可用的 WebView，窗口打不开
keyring	密钥链触达不到
wasm_backend	插件运行时没有初始化
plugin_dir	插件目录还不存在

关于密钥链或 Wasm 运行时的 warn 不是通过

它的意思是探针没跑 —— 通常因为它需要的东西这个命令起不来。它被报出来而不是被跳过，是为了让这个缺口可见。

两台设备互相看不见

按顺序检查：

1. 同一个网络。 发现是本地的。其中一台开着 VPN 可能就把它放到了另一个网络上。
2. 防火墙。 synra doctor 的 firewall 探针会说明这个平台是否需要加规则。需要放行入站的是两件独立的 事：UDP 32101，设备靠它互相找到；以及 TCP 47100，它们真正通话靠它。只放行前者的结果是最坏的那 种：设备能出现在列表里，却连不上。
3. 客户端隔离。 有些访客网络会阻断客户端之间的流量，而设备上没有任何设置能修好它。

端口

真正要紧的是两个端口，设备对它们的要求各不相同。

端口	协议	方向	用途
32101	UDP	入站与出站	发现：广播及其应答
47100	TCP	入站与出站	传输层：每个对端一条连接，承载消息

32101 是固定的。 它是协议自身的常量，而且每台设备必须一致 —— 监听在别处的设备既不会被找到，也找不到 任何东西。它同时也是每台机器上的单例：同一台主机上两个内核会对每个查询都作答，对端就会从同一个地址 收到两个携带不同设备标识符的应答。--discovery-port 可以移动它，但那样做时两台设备必须一致。

47100 是各个对端前来连接的端口，也是防火墙规则最需要关心的那个。--listen-port 可以改它，而设备广播的 通告会带上它被设成的值 —— 所以两台设备可以用不同的端口，仍然能互相连上。

出站查询用的端口不在上表之列

本机自己的发现查询是从操作系统分配的临时端口发出的，这样应答会回到一个不与别人共用的 socket 上。它 不是一项设置，每次运行都可能不同，也不需要防火墙规则。Synra 不会使用上表之外的任何端口。

看得见但配不上对

• 提示被拒绝了。 拒绝会带原因：busy、expired 或 blocked。expired 是那个可以重试的；blocked 需要 在对方设备上解除拉黑。
• 时钟偏得太多。 配对涉及时间戳，而一台慢了几分钟的设备可能立刻被判为 expired。clock_sanity 探针就是 抓这个的。

传输中断了

被打断的传输会在链路回来时自行续传，只要没超出总时间预算。被取消的不会。

要留意的失败是 integrity_mismatch：收到的字节与发送前声明的摘要不符。半成品文件会被丢弃，重试从头再来。见 错误码。

日志在哪里

synra logs 读内核日志。文件在缓存目录下 —— 各平台路径见数据位置。

诊断包不包含你的密钥

它带的是日志、崩溃报告和 doctor 报告。它不带数据目录里的密钥 —— 这正是它可以安全发出去的原因。

接下来

• 数据位置 —— 磁盘上的一切在哪。
• 错误码 —— 某个具体错误码是什么意思。
• 平台支持 —— 各平台有哪些不同。