P2P 与分布式存储 / 系统课时

用 ICE 连接状态识别异常

用 ICE 连接状态识别异常

WebRTC 连接异常时,不能只根据 DataChannel 是否打开判断故障。通过监听 iceGatheringState 和 iceConnectionState,可以区分候选收集、连通性检查、短暂断连和连接失败,并为日志记录、重试与 ICE Restart 提供依据。本课实现一个可运行的浏览器状态监控示例。

学习目标

  • 区分 ICE 候选收集状态与连接检查状态,理解各自代表的阶段。
  • 使用浏览器原生事件持续记录状态变化和异常时间。
  • 根据 disconnected、failed 等状态选择合理的恢复动作,并验证监控结果。

两组 ICE 状态分别表示什么

RTCPeerConnection 提供两组独立状态。iceGatheringState 描述本地 ICE 候选收集进度;iceConnectionState 描述候选对的连通性检查与连接状况。两者不能互相替代。

属性 状态 含义
iceGatheringState new 尚未开始收集候选
iceGatheringState gathering 正在收集 host、srflx 或 relay 等候选
iceGatheringState complete 当前轮候选收集结束
iceConnectionState new ICE 检查尚未开始或尚无正在执行的检查
iceConnectionState checking 正在检查候选对是否可达
iceConnectionState connected 已找到可用候选对,但检查可能仍在继续
iceConnectionState completed ICE 检查已完成并形成可用连接
iceConnectionState disconnected 当前连接暂时失去连通性,可能恢复
iceConnectionState failed ICE 已判定无法建立或维持可用连接
iceConnectionState closed ICE 传输已关闭

例如,iceGatheringState=complete 只能证明候选收集结束,不能证明远端可达;即使收集完成,iceConnectionState 仍可能停留在 checking,最终进入 failed。

connected 也不意味着所有检查已经结束。实际业务通常可以在 DataChannel 打开后开始发送数据,不必等待 completed。此外,Trickle ICE 允许候选收集和连通性检查重叠进行,因此不能假定所有状态严格按一条固定时间线依次出现。

观察正常连接与异常分支

下图将候选收集与连通性检查分成两条状态轨道。上方显示本地候选收集,下方显示连接检查及异常恢复路径。重点观察 disconnected 可以回到 connected,而 failed 需要进一步处理。

ICE 候选收集与连接检查状态及异常恢复关系图

判断时需要结合持续时间和上下文,而不是看到一个状态就立即重连。例如移动网络切换时,连接可能短暂进入 disconnected,随后自行恢复;如果在 checking 阶段长期没有可用候选对,则应检查信令交换、STUN/TURN 可达性和候选对检查结果。

用浏览器事件记录状态变化

下面的示例可直接保存为 ice-monitor.html 并在支持 WebRTC 的现代浏览器中打开。它创建一个 RTCPeerConnection,监听两组 ICE 状态事件,并记录相对时间。点击按钮创建 DataChannel 和本地 Offer,启动候选收集;由于没有远端参与,示例不会自动建立 P2P 连接。

html
<!doctype html>
<html lang="zh-CN">
<head><meta charset="utf-8"><title>ICE 状态监控</title></head>
<body>
<button id="start">开始本地 ICE 收集</button>
<button id="stop">关闭连接</button>
<pre id="log"></pre>
<script>
const pc = new RTCPeerConnection({
  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }]
});
const startedAt = performance.now();
const logElement = document.querySelector('#log');

function record(eventName, state) {
  const elapsed = Math.round(performance.now() - startedAt);
  const line = `${elapsed}ms ${eventName}: ${state}`;
  logElement.textContent += line + '\n';
  console.log(line);
}

// 分别记录候选收集与候选对检查,避免混淆两种状态。
pc.addEventListener('icegatheringstatechange', () => {
  record('iceGatheringState', pc.iceGatheringState);
});
pc.addEventListener('iceconnectionstatechange', () => {
  record('iceConnectionState', pc.iceConnectionState);
});
pc.addEventListener('icecandidateerror', event => {
  record('iceCandidateError', `${event.errorCode} ${event.errorText}`);
});

document.querySelector('#start').onclick = async () => {
  try {
    // DataChannel 使本地 Offer 包含数据传输协商信息。
    pc.createDataChannel('diagnostics');
    const offer = await pc.createOffer();
    await pc.setLocalDescription(offer);
    record('localDescription', '已设置');
  } catch (error) {
    record('error', error.message);
  }
};

document.querySelector('#stop').onclick = () => pc.close();
record('initialGathering', pc.iceGatheringState);
record('initialConnection', pc.iceConnectionState);
</script>
</body>
</html>

预期结果:页面首先显示两组初始状态。点击“开始本地 ICE 收集”后,在网络及浏览器支持的情况下,通常可观察到以下事件顺序(时间和错误事件因环境而异):

text
0ms initialGathering: new
1ms initialConnection: new
<TIME>ms iceGatheringState: gathering
<TIME>ms localDescription: 已设置
<TIME>ms iceGatheringState: complete

<TIME> 表示运行时测得的毫秒数,实际值可能不同。部分浏览器的事件与异步操作完成顺序也可能不同。由于没有设置远端描述,iceConnectionState 可能一直保持 new;不能期待本地测试自动出现 checking、connected 或 failed。

要观察完整连接状态,需要让两个对等端交换 Offer、Answer 和 ICE 候选,并在双方设置相应的远端描述。完成协商后,使用相同的事件监听器即可记录真实的检查、连接及断连过程。

根据状态安排恢复动作

状态监控应提供可执行的故障处理策略。以下超时值是应用层起始建议,不是 WebRTC 标准规定的超时;应根据网络质量、移动端切换频率及业务容忍度调整。

观测条件 建议动作
gathering 持续较久 检查 STUN/TURN 域名解析、网络与服务器可达性;不要仅凭耗时认定失败
checking 超过 15 秒 记录候选与信令信息,检查远端候选是否到齐、TURN 是否可用
disconnected 持续不足 5 秒 保留连接,等待自动恢复并继续观测
disconnected 持续超过 5 秒 提示网络不稳定,检查网络切换,按策略尝试 ICE Restart
failed 记录诊断信息,触发受控的 ICE Restart;多次失败后报告连接不可用
closed 停止重试并释放应用侧资源

ICE Restart 必须配合新的 Offer/Answer 信令交换,不能只调用方法就认为连接已经恢复。已有信令通道的应用可以由发起端执行以下操作。

js
// 片段示例:依赖已建立的 pc,以及应用实现的 sendSignal 函数。
// 新的 Offer 携带更新后的 ICE 凭据,必须发送给远端完成协商。
async function restartIceConnection(pc, sendSignal) {
  pc.restartIce();
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);
  await sendSignal({ type: 'offer', sdp: pc.localDescription.sdp });
}

这里的 sendSignal 是业务信令接口,不是浏览器内置 API。远端收到 Offer 后需要执行 setRemoteDescription()、createAnswer() 和 setLocalDescription(),再将 Answer 返回发起端;双方还必须继续处理新的 ICE 候选。验证时应看到新一轮协商及 ICE 检查,最终恢复可用候选对,而不是仅凭 restartIce() 调用成功判断恢复完成。

同一连接不要并发发起多个 Restart。生产环境应限制重试次数,例如最多 3 次,并采用 1、2、4 秒的退避间隔;如果信令通道也已断开,应先恢复信令能力,再执行重新协商。

联合统计信息定位真实故障

ICE 状态只能告诉我们连接处于哪个阶段,不能直接证明故障来自 NAT、TURN、丢包还是信令。实际排查可在浏览器开发者工具的 Console 中读取 getStats(),寻找已选中的候选对以及对应的本地和远端候选信息。

js
// 片段示例:在已有 RTCPeerConnection 实例 pc 的上下文执行。
async function inspectIceStats(pc) {
  const stats = await pc.getStats();
  for (const report of stats.values()) {
    if (report.type !== 'transport' || !report.selectedCandidatePairId) continue;
    const pair = stats.get(report.selectedCandidatePairId);
    if (!pair) continue;
    const local = stats.get(pair.localCandidateId);
    const remote = stats.get(pair.remoteCandidateId);
    console.log({
      pairState: pair.state,
      localType: local?.candidateType,
      remoteType: remote?.candidateType,
      bytesSent: pair.bytesSent,
      bytesReceived: pair.bytesReceived
    });
  }
}

片段依赖现有的 pc,并且需要浏览器提供对应的统计对象。成功连接且统计信息完整时,localType 和 remoteType 可能为 host、srflx、prflx 或 relay;如果没有选中候选对,函数可能不输出任何内容。不要把缺少某个统计字段直接当作连接失败。

排查时建议保留 iceGatheringState、iceConnectionState、connectionState、状态变化时间、ICE 候选类型以及选中候选对的收发字节计数。注意 connectionState 还综合反映其他传输状态,与 iceConnectionState 不完全相同。

验收可以进行两次实验:正常网络下完成双端 DataChannel 协商,观察连接进入 connected 或 completed;随后临时断开一端网络并恢复,观察是否出现 disconnected 及后续恢复。不同浏览器和网络环境可能出现不同的中间状态,测试通过的标准应是状态日志能解释实际连接行为,而不是强制出现所有状态。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 ICE 连接状态识别异常

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通