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 需要进一步处理。

判断时需要结合持续时间和上下文,而不是看到一个状态就立即重连。例如移动网络切换时,连接可能短暂进入 disconnected,随后自行恢复;如果在 checking 阶段长期没有可用候选对,则应检查信令交换、STUN/TURN 可达性和候选对检查结果。
用浏览器事件记录状态变化
下面的示例可直接保存为 ice-monitor.html 并在支持 WebRTC 的现代浏览器中打开。它创建一个 RTCPeerConnection,监听两组 ICE 状态事件,并记录相对时间。点击按钮创建 DataChannel 和本地 Offer,启动候选收集;由于没有远端参与,示例不会自动建立 P2P 连接。
<!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 收集”后,在网络及浏览器支持的情况下,通常可观察到以下事件顺序(时间和错误事件因环境而异):
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 信令交换,不能只调用方法就认为连接已经恢复。已有信令通道的应用可以由发起端执行以下操作。
// 片段示例:依赖已建立的 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(),寻找已选中的候选对以及对应的本地和远端候选信息。
// 片段示例:在已有 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 及后续恢复。不同浏览器和网络环境可能出现不同的中间状态,测试通过的标准应是状态日志能解释实际连接行为,而不是强制出现所有状态。