4.3 连接失败诊断手册
文档摘要
4.3 连接失败诊断手册 本节摘要：原理懂了、服务器也部署了，凌晨三点用户报告「连不上」时怎么办？本节把「连不上」按症状组合拆成六类故障，每类给出判据（在哪看、看什么）、根因（为什么）与修复动作（怎么办），并配一张诊断决策图。这一节是本章前两节的出口——把候选知识变成故障现场的肌肉记忆。 读完本节你能 阅读完本节，你应当能够： 按 iceConnectionState 的取值组合快速框定故障类别； 从候选清单的类型分布读出 STUN、TURN 与防火墙的健康状况； 区分「部分用户失败」与「全部用户失败」的排查路径差异； 处理网络切换（Wi-Fi 换蜂窝）引发的中断与恢复； 建立一套可复用的连接故障报告模板，让远程排障不再反复追问。
4.3 连接失败诊断手册
本节摘要：原理懂了、服务器也部署了，凌晨三点用户报告「连不上」时怎么办？本节把「连不上」按症状组合拆成六类故障，每类给出判据（在哪看、看什么）、根因（为什么）与修复动作（怎么办），并配一张诊断决策图。这一节是本章前两节的出口——把候选知识变成故障现场的肌肉记忆。
读完本节你能
阅读完本节，你应当能够：
- 按 iceConnectionState 的取值组合快速框定故障类别；
- 从候选清单的类型分布读出 STUN、TURN 与防火墙的健康状况；
- 区分「部分用户失败」与「全部用户失败」的排查路径差异；
- 处理网络切换（Wi-Fi 换蜂窝）引发的中断与恢复；
- 建立一套可复用的连接故障报告模板，让远程排障不再反复追问。
一、问题与直觉：先分类，再动手
连接失败最忌讳的动作是「上来就抓包」。ICE 失败的候选原因有限，症状组合足够把它们分开。分类的第一把尺子是范围：全部用户失败，大概率是你自己的部署或发布出了问题；部分用户失败，大概率是用户侧网络环境与你的基础设施的组合出了问题。第二把尺子是状态：connectionState 停在哪、候选清单长什么样。两把尺子交叉，六类故障基本现形。
| 症状 | 判据 | 根因方向 |
|---|---|---|
| 全员失败，候选只有 host | 无 srflx 无 relay | STUN 与 TURN 都不可达或都未配置 |
| 跨网失败，有 srflx 无 relay | 探测停在 checking | 对称 NAT 遇上无 TURN 兜底 |
| 有 relay 仍失败 | relay 探测不通 | 中继端口池被防火墙拦截 |
| 时通时断，部分用户 | 日志见凭证校验错误 | 凭证签发或时钟问题 |
| 通话中突然断开 | disconnected 后未恢复 | 网络切换或映射过期 |
| 一端可见另一端不可见 | ice 已 connected | 已越出本章范围，转向第 5 章协商与解码 |
表格最后一行是重要的边界意识：ICE 只负责「路通」，路通了画面不出来是协商与媒体层的问题，诊断手册要能「转诊」而不是硬套。
二、核心方法：诊断决策图与取证清单
图：连接失败诊断决策树
网络切换值得单讲。移动设备在 Wi-Fi 与蜂窝之间切换时，原通路作废，现代浏览器会自动重启 ICE（监听 onicecandidate 重新收集），connectionState 表现为 disconnected 短暂停留后回到 connected。你要做的不是干预，而是容忍：UI 上把短暂 disconnected 显示为「弱连接」而非「已断开」，等待窗口给足（工程上十秒为宜），超时才判死。早期版本浏览器不自动重启 ICE 的，需要应用层手动重建连接——这也是老设备「出电梯就断线」的病根。
取证清单是远程排障的效率关键。让用户或客户端自动上报五样东西：两端状态机取值序列、候选清单全文、信令消息时间线、凭证错误码、网络环境摘要（网络类型与运营商）。前四样第 1 章的事件监听都能打进日志，第五样问一句即可。
VPN 场景值得单独设一个排查分支。虚拟网卡会让 host 候选多出一批、srflx 地址指向企业出口，个别 VPN 客户端还会接管 UDP 流量导致 relay 探测超时——症状与恶意网络封锁高度相似。区分的判据是「关闭 VPN 复测一次」：现象立刻消失即可定责，随后有两条路可走，产品侧在候选清单里识别虚拟网段并降权（优先尝试物理网卡候选），运维侧与客户 IT 协商放行 TURN 端口段。把「是否挂着 VPN」做进诊断的第一问，能砍掉企业场景里相当比例的误排查时间。
三、工程实践要点：把诊断做进客户端
成熟产品的做法是把诊断能力做进客户端：一个隐藏的「连接体检」面板，展示当前候选清单、状态机时序、最近一次探测的错误码；再配一个「一键导出诊断报告」按钮。支持团队的工单解决时间会因此显著下降——大量工单根本不需要工程师介入，用户自己对着面板就能发现「原来是我开着 VPN」。
完整案例：企业 VPN 用户的集体失联
背景：某客户企业批量采购后反馈，其办公区内约半数员工无法发起通话，但同一工位换个人偶尔又能通。
操作：按诊断决策图先看范围——仅该企业、部分人员，属于「部分用户失败」。读候选清单：这些用户只有 host 与 srflx，relay 候选收集报错；且他们的 srflx 地址显示为同一企业出口。推断：企业出口防火墙对 UDP 高位端口（中继池）做了时段性限速，部分会话的探测在限速窗口内超时。与客户网络组确认后，对方放行了 TURN 服务器的 3478、5349 与中继池段，并按源地址做了白名单。
结果：该企业失败率归零。产品侧顺势在客户端体检面板里加了「TURN 可达性探测」常驻检查，检测到 relay 探测超时就提示「当前网络可能限制了视频通话」，把网络原因与产品原因在用户视角里分开。
解读：这个案例有两个可迁移的要点。其一，企业防火墙的行为常常是概率性的（限速而非全禁），「偶尔能通」不代表配置正确，判据要落在候选清单与错误码上而不是现象复现上。其二，诊断能力的产品化——把排障知识做成用户可见的面板——是一次投入、长期收效的工程，比每次远程会议里的口头追问划算得多。
变式：多方会议场景的诊断入口更前移一步：接入 SFU 时连接失败，先区分「端到服务器」与「端到端」两类 ICE——与 SFU 的连接通常是服务器侧防火墙问题（排查清单简单得多），端到端链路才是本章的完整战场。把故障树的第一层按拓扑切分，能避免把 SFU 接入问题错诊成 NAT 穿越问题。
⚠️ 常见坑：把 disconnected 立刻当 failed 处理会制造大量假故障——手机进出电梯、切换基站的几秒里连接会自己恢复。判死要给恢复窗口，且窗口要长于网络切换的典型耗时。
本节要点回顾
- 先分类后动手：范围尺（全员还是部分）与状态尺（状态机与候选清单）交叉，六类故障各归各位。
- 候选清单是第一现场：类型分布直接指认缺陷环节——缺 srflx 怪 STUN，缺 relay 怪 TURN，relay 不通怪防火墙。
- 网络切换要容忍不要干预：disconnected 给足恢复窗口，判死窗口长于切换耗时。
- 取证清单固定五样：状态机序列、候选全文、信令时间线、错误码、网络摘要，让远程排障一次到位。
- 诊断能力要产品化：体检面板与一键报告，把排障知识变成用户与支持团队共用的工具。