P2P 与分布式存储 / 系统课时
用抓包与日志定位 ICE 失败
用抓包与日志定位 ICE 失败
WebRTC 连接失败时,单看 iceConnectionState=failed 无法判断问题出在信令、候选收集、NAT 过滤还是 TURN 中继。本课通过统一时间线关联信令日志、浏览器 WebRTC 统计和 Wireshark 抓包,建立可复现的定位方法,并验证修复是否真正恢复了数据传输。
学习目标
- 采集并关联信令事件、ICE 候选、候选对统计和网络报文。
- 区分候选缺失、连通性检查超时、TURN 鉴权失败与中继不可达。
- 使用最小诊断脚本和抓包过滤器验证故障根因及修复结果。
先固定故障现场和时间基准
假设浏览器 A 与 B 通过 WebSocket 交换 SDP 和 ICE 候选,使用 STUN 获取公网映射地址,并在直连失败时通过 coturn 中继。现象是双方信令连接正常,但 DataChannel 始终未进入 open,最终 ICE 状态变为 failed。
首先固定浏览器版本、网络出口、TURN 地址、故障发生时间和测试会话 ID。每次复现只改变一个条件,例如先使用正常 ICE 配置,再单独测试 iceTransportPolicy: 'relay'。不要同时修改防火墙、凭据和 ICE 服务器地址,否则无法归因。
建议为一次连接记录以下事件:
| 观测点 | 必须记录的内容 | 定位价值 |
|---|---|---|
| 信令服务 | 会话 ID、发送方、消息类型、发送及接收时间 | 判断 Offer、Answer、Candidate 是否丢失或乱序 |
| 浏览器事件 | iceGatheringState、iceConnectionState、connectionState |
确定失败阶段 |
| ICE 候选 | host、srflx、relay、地址、协议 |
判断候选来源是否完整 |
| Candidate Pair | 状态、请求和响应计数、收发字节数 | 判断是否完成检查及实际传输 |
| 网络抓包 | STUN、TURN、UDP、TCP、TLS 报文 | 验证请求是否到达及是否收到响应 |
所有日志优先使用 UTC 时间戳,并记录单调时钟时间用于本进程内排序。跨设备分析前应同步系统时钟;浏览器 performance.now() 不能直接与服务器时间戳比较,需要通过 performance.timeOrigin + performance.now() 转换为近似的 Unix 毫秒时间。网络延迟和时钟偏差仍需单独考虑。
采集浏览器 ICE 事件与候选对统计
Chrome 可以打开 chrome://webrtc-internals,在复现前进入页面,保留对应 PeerConnection 的事件与统计记录。Firefox 可使用 about:webrtc。不同浏览器的统计展示名称和导出方式可能不同,应以当前版本实际界面为准。
下面的 JavaScript 可直接在支持 WebRTC 的浏览器开发者工具 Console 中执行。它创建一个独立的 RTCPeerConnection,监听候选收集和状态变化,并每秒读取一次统计;示例没有远端信令交换,因此只用于验证采集机制,不代表能够独立建立 P2P 连接。
(async () => {
const pc = new RTCPeerConnection({ iceServers: [] });
const stamp = () => new Date().toISOString();
pc.onicecandidate = (event) => {
console.log(stamp(), 'candidate',
event.candidate?.candidate ?? 'end-of-candidates');
};
pc.onicegatheringstatechange = () =>
console.log(stamp(), 'gathering', pc.iceGatheringState);
pc.oniceconnectionstatechange = () =>
console.log(stamp(), 'ice', pc.iceConnectionState);
// 创建数据通道,使连接产生需要协商的媒体传输部分。
pc.createDataChannel('diagnostic');
await pc.setLocalDescription(await pc.createOffer());
const timer = setInterval(async () => {
const stats = await pc.getStats();
for (const s of stats.values()) {
if (s.type !== 'candidate-pair') continue;
console.log(stamp(), 'pair', {
id: s.id,
state: s.state,
nominated: s.nominated,
requestsSent: s.requestsSent,
responsesReceived: s.responsesReceived,
bytesSent: s.bytesSent,
bytesReceived: s.bytesReceived
});
}
}, 1000);
// 10 秒后释放诊断连接,避免持续占用资源。
setTimeout(() => {
clearInterval(timer);
pc.close();
console.log(stamp(), 'diagnostic-finished');
}, 10000);
})();预期结果:控制台出现带 ISO 时间戳的 gathering 事件和可能的 candidate 事件,约 10 秒后出现 diagnostic-finished。候选内容取决于浏览器和网络;由于没有交换远端 SDP,不保证产生 Candidate Pair,也不应期待 connected 状态。
实际项目中应把相同的监听与 getStats() 逻辑接入正在协商的 PeerConnection,才可以分析真实候选对。重点关注 selectedCandidatePairId 所引用的候选对,或统计中 nominated 且处于 succeeded 的候选对;不要仅凭存在某条 succeeded 记录就认定它是当前传输路径。
requestsSent 增长而 responsesReceived 不增长,提示检查请求未得到对应响应,但不能仅凭这两个计数判断报文丢失位置。部分统计字段可能缺失,读取时应允许 undefined。
用同一条时间线关联三个证据来源
信令日志能说明候选有没有传给对端,浏览器统计能说明 ICE Agent 做了什么,抓包能说明网络上实际出现了哪些报文。三者必须以同一会话和相近时间范围进行关联。

例如某次复现的归一化时间线如下,时间为示例相对时间,并非固定的 ICE 超时阈值:
| 相对时间 | 信令或浏览器事件 | 网络证据 |
|---|---|---|
| 0 ms | Answer 已设置 | 协商开始 |
| 180 ms | 收到远端 relay 候选 | 候选可参与配对 |
| 430 ms | Candidate Pair 检查开始 | 发出 STUN Binding Request |
| 930 ms | 请求计数增加,响应计数不变 | 观察到重传请求 |
| 4200 ms | 检查仍未成功 | 未观察到匹配响应 |
| 8000 ms | ICE 报告 failed |
本次检查未建立可用路径 |
此时不能直接断言是 NAT 对称映射导致失败。还需查看远端是否收到请求、TURN Permission 是否存在、服务器是否有鉴权错误,以及抓包位置是否覆盖了真正的数据路径。
关联 STUN 事务时使用 Transaction ID,而不是只比较 IP 和端口。STUN 请求和响应携带相同事务 ID;重传也会复用对应事务 ID。浏览器内部统计对象 ID 与 STUN Transaction ID 不是同一种标识,不能直接比较。
用 Wireshark 确认检查请求和 TURN 响应
在允许抓包的测试环境中,优先同时采集客户端出口和 TURN 服务器网卡的数据。Wireshark 显示过滤器 stun 可用于查看识别出的 STUN/TURN 控制消息;如果流量使用 TURN/TLS,客户端与服务器之间的加密控制内容通常不能直接从普通抓包中读取。
可以先在 Wireshark 的显示过滤栏使用以下条件:
stun这是 Wireshark 显示过滤器片段,不是 Shell 命令。应用后检查 Binding Request、Binding Success Response、Allocate Request、Allocate Error Response 和 Allocate Success Response。具体能看到哪些消息取决于抓包位置、传输方式和协议解析情况。
在 Linux 测试服务器上,可用 tcpdump 保存 coturn 常见监听端口的报文:
sudo tcpdump -i any -nn -s 0 -w turn-control.pcap 'udp port 3478 or tcp port 3478 or tcp port 5349'预期结果:终端显示 listening on any 或对应接口的监听提示;按 Ctrl+C 结束后生成 turn-control.pcap。实际监听接口和提示文字取决于系统及 tcpdump 版本。该命令只覆盖所列控制监听端口,不包含 TURN 分配的全部中继端口;若要分析 Peer 与中继之间的数据,还需要结合 coturn 的实际中继端口范围和部署拓扑扩大采集范围。
判断报文时遵循以下顺序:
- 客户端是否真的发出 Binding 或 Allocate 请求。
- 服务器入口是否收到同一请求,事务 ID 是否一致。
- 服务器是否返回成功或错误响应,错误码是什么。
- 响应是否回到客户端,随后候选对是否变为
succeeded。
如果客户端抓到请求、服务器入口却没有对应报文,应检查路由、防火墙和上游网络策略;如果服务器已返回响应但客户端未收到,应继续定位返回路径。单侧抓包不能证明整个网络路径上的丢包位置。
按故障特征定位根因并修复
将问题按最早出现异常的阶段分类,比只看最终 failed 状态更有效。
| 故障类型 | 典型证据 | 优先修复方向 |
|---|---|---|
| 候选缺失 | 没有预期的 srflx 或 relay;或候选未送达远端 |
检查 ICE 服务器配置、候选收集事件、信令转发和候选过滤逻辑 |
| 连通性检查超时 | 请求已发出,匹配响应缺失,候选对未成功 | 检查双向 UDP、NAT 过滤、路由与 TURN 权限 |
| TURN 鉴权失败 | Allocate 收到 401 或 438,且重试后仍未成功 | 检查 realm、nonce、用户名、密码和临时凭据有效期 |
| 中继不可达 | Allocate 无响应,或分配成功后中继数据路径不通 | 检查监听端口、云安全组、中继端口范围和外部映射地址 |
候选缺失和信令丢失
host 候选通常来自本地接口,srflx 候选需要通过 STUN 获得服务器反射地址,relay 候选需要成功完成 TURN Allocation。没有 relay 并不一定是错误:如果没有配置 TURN,或者未成功分配中继,本来就不会得到可用的 relay 候选。
若本地 onicecandidate 已产生候选,但远端没有相应记录,应检查信令消息是否携带 candidate、sdpMid、sdpMLineIndex,以及接收端是否正确调用 addIceCandidate()。候选在远端描述尚未设置时到达,应先缓存,再在 setRemoteDescription() 成功后应用;不能静默丢弃。
检查超时和网络过滤
如果双方候选已经交换,检查请求持续发送却没有响应,先比较双侧抓包。只有请求到达对端而对端不响应时,才重点检查对端 ICE Agent、用户名片段、消息完整性校验及过滤策略。若请求根本未到达,应检查路径上的 NAT、ACL 和防火墙。
不要通过无限延长超时来掩盖网络不可达。生产策略应保留有界的直连尝试,并提供 TURN 回退;具体超时预算应结合实际网络质量与应用可接受的建连时延测试确定。
TURN 鉴权与中继地址
TURN 长期凭据机制中,初次 Allocate 收到 401 Unauthorized 并携带 REALM、NONCE,可能是正常认证挑战;客户端携带正确认证属性重试后应得到成功响应。438 Stale Nonce 通常要求使用新 nonce 重试,不能把首次 401 或可恢复的 438 直接判为最终鉴权失败。
如果重试持续返回 401,应检查 coturn 与业务后端是否使用一致的共享密钥、realm 和临时凭据算法,并确认客户端时钟与凭据过期时间。不要在生产日志中记录明文密码或完整授权密钥。
若 Allocate 已成功,但 relay 候选无法通信,应检查 coturn 的 external-ip 映射是否符合部署方式,以及中继 UDP 端口范围是否已在主机防火墙和云安全组放行。仅开放 3478 或 5349 并不等于中继数据端口可达。
复测选中路径并给出验收证据
修复后应分别验证正常 ICE 策略和强制 relay 策略。强制 relay 可以验证 TURN 路径,但不能证明直连路径可用。建议使用两个不同网络出口的浏览器节点,避免仅在同一局域网内测试。
验收时按顺序确认:
- 双端均完成 Offer/Answer,且收到预期的远端候选。
iceConnectionState进入connected或completed,未持续停留在checking。- 通过
getStats()确认当前选中候选对及其本地、远端候选类型;强制 relay 时,所选本地候选应为relay。 - DataChannel 进入
open,A 发送带序号的测试消息,B 返回相同序号的确认消息。 - 连续发送 100 条小消息,记录成功确认数、往返延迟和超时数;目标可先设为 100/100 条确认,再按真实业务要求调整。
- 对照抓包和 TURN 服务器日志,确认数据经过预期路径,而不是仅根据 UI 显示成功。
一次完整的故障报告至少保留会话 ID、UTC 时间范围、浏览器版本、候选类型、选中候选对、关键 STUN/TURN 事务、修复操作和复测结果。对于没有完整证据的结论,应明确标记为待验证假设。
最终验收依据应是候选对检查成功、实际数据双向传输成功、预期回退路径得到验证三项同时成立,而不是只看到 ICE 状态从 failed 变成 connected。