P2P 与分布式存储 / 系统课时
通过信令传递 ICE 候选
通过信令传递 ICE 候选
WebRTC 创建 Offer 和 Answer 后,还需要让双方知道可以尝试通信的网络地址。本课使用 Trickle ICE:监听 icecandidate 事件,通过 WebSocket 信令发送本地候选,并调用 addIceCandidate() 添加远端候选,最终验证候选交换与连接状态。
学习目标
- 理解 ICE 候选产生、信令转发和远端添加之间的关系。
- 使用
icecandidate事件和addIceCandidate()完成增量候选交换。 - 处理候选早于远端描述到达、重复消息和收集结束等边界情况。
ICE 候选为什么需要单独传递
ICE(Interactive Connectivity Establishment)负责为两个 WebRTC 端点寻找可通信的网络路径。候选通常包括本地接口候选 host、通过 STUN 获得的服务器反射候选 srflx,以及通过 TURN 获得的中继候选 relay。
RTCPeerConnection 可以逐步发现这些候选,但不会自动把它们发送到另一个浏览器。应用必须提供信令通道,例如 WebSocket,并确保候选被送到正确的会话和对端。
Trickle ICE 允许候选一产生就发送,无须等到所有候选收集完毕。这可以让远端更早开始连通性检查,减少等待完整候选集合的时间。

这里要区分两条通道:信令通道传递 SDP 与 ICE 候选,WebRTC 连接则负责后续数据传输。即使信令 WebSocket 已连接,也不能据此判断 P2P 数据通道已经可用。
监听并发送本地候选
浏览器使用 RTCPeerConnection 的 icecandidate 事件报告新发现的候选。事件对象中的 candidate 通常是一个 RTCIceCandidate,调用 toJSON() 可以获得适合通过 JSON 信令传输的字段。
常用字段如下:
| 字段 | 作用 |
|---|---|
candidate |
ICE 候选属性字符串,包含地址、端口、传输协议及候选类型等信息 |
sdpMid |
候选所属媒体节的标识 |
sdpMLineIndex |
候选所属媒体节的索引 |
usernameFragment |
候选所属 ICE 代次的用户名片段,可辅助识别重启后的候选 |
以下为浏览器 JavaScript 片段示例,依赖已建立的 RTCPeerConnection 实例 pc、处于 OPEN 状态的 WebSocket ws,以及应用定义的 sessionId。信令服务器必须根据会话标识把消息转发给另一端。
pc.addEventListener('icecandidate', (event) => {
if (ws.readyState !== WebSocket.OPEN) {
console.warn('信令未连接,候选需要排队或重试');
return;
}
// null 表示本次 ICE 候选收集全部结束
const payload = event.candidate
? { type: 'ice-candidate', candidate: event.candidate.toJSON() }
: { type: 'ice-complete' };
ws.send(JSON.stringify({ sessionId, ...payload }));
});预期结果:每发现一个候选,信令服务器便收到一条 ice-candidate 消息;当事件的 candidate 为 null 时,收到 ice-complete。具体候选数量、地址与端口取决于网络环境,不应固定写死。
生产环境不要在 WebSocket 暂时断开时直接丢弃候选。应把消息放入有界发送队列,待信令恢复后按当前会话与 ICE 代次重发;已经失效的旧代次候选不应继续发送。
在远端正确添加候选
接收端使用 pc.addIceCandidate() 将候选交给浏览器的 ICE Agent。但它有一个关键前置条件:必须先通过 setRemoteDescription() 设置相应的远端 SDP。
如果网络传输导致候选消息比 Offer 或 Answer 更早到达,立即调用 addIceCandidate() 可能抛出 InvalidStateError。正确做法是先缓存候选,在远端描述设置成功后统一补加。
以下是可直接集成到浏览器端信令处理模块的片段示例。依赖已创建的 pc、ws 和 sessionId,且其他模块已经负责 Offer/Answer 的发送及本地描述设置。服务器只转发当前会话的消息,不把发送者自己的消息回送给发送者。
const pendingCandidates = [];
const seenCandidates = new Set();
async function addRemoteCandidate(candidate) {
// 未设置远端 SDP 时先缓存,避免 InvalidStateError
if (!pc.remoteDescription) {
pendingCandidates.push(candidate);
return;
}
await pc.addIceCandidate(candidate);
console.log('已添加远端候选');
}
async function flushCandidates() {
while (pendingCandidates.length > 0) {
await pc.addIceCandidate(pendingCandidates[0]);
pendingCandidates.shift();
console.log('已补加缓存候选');
}
}
// 串行处理异步信令,避免 SDP 设置与候选添加交错
let messageQueue = Promise.resolve();
ws.addEventListener('message', (event) => {
messageQueue = messageQueue.then(async () => {
const msg = JSON.parse(event.data);
if (msg.sessionId !== sessionId) return;
if (msg.type === 'offer' || msg.type === 'answer') {
await pc.setRemoteDescription(msg.description);
await flushCandidates();
} else if (msg.type === 'ice-candidate') {
const c = msg.candidate;
const key = JSON.stringify([
c.candidate, c.sdpMid, c.sdpMLineIndex,
c.usernameFragment
]);
if (seenCandidates.has(key)) return;
await addRemoteCandidate(c);
seenCandidates.add(key);
} else if (msg.type === 'ice-complete') {
console.log('远端已完成候选收集');
}
}).catch((error) => {
console.error('处理信令失败', error.name, error.message);
});
});预期结果:远端 SDP 设置成功后,收到的候选触发 已添加远端候选;提前到达的候选在 SDP 设置后触发 已补加缓存候选;重复候选不会再次提交;收集完成消息触发 远端已完成候选收集。日志数量取决于实际候选。
这段示例演示的是一次普通协商中的候选缓存和去重,不包含完整的 ICE Restart、会话恢复或 Perfect Negotiation。正式项目应为每次 ICE 代次分别维护候选队列与去重集合,并检查 usernameFragment 是否属于当前协商,防止旧候选污染新连接。
处理收集结束与异常边界
ICE 候选交换不是简单的发送一次、接收一次。浏览器可能先发现 host 候选,再获得 srflx 或 relay 候选;双方候选数量也不要求相等。
| 情况 | 处理方式 |
|---|---|
| 候选早于 SDP 到达 | 缓存候选,setRemoteDescription() 成功后补加 |
| 候选重复到达 | 通过会话、ICE 代次及候选字段去重 |
addIceCandidate() 抛出 OperationError |
检查候选字段、sdpMid、ICE 用户名片段及远端 SDP 是否匹配 |
| 信令断线 | 保留当前有效代次的待发送消息,恢复后重试并防止重复 |
| ICE Restart | 清理旧代次队列与去重记录,按新 SDP 的 ICE 凭据重新交换 |
收集结束还可以使用标准的 end-of-candidates 标记表达。浏览器支持调用 addIceCandidate({ candidate: '' }) 来指示远端候选结束,但多媒体节和 ICE 代次场景应保留正确的媒体节及代次信息。为了避免把一个会话级完成通知错误地套用到所有媒体节,本课示例仅记录 ice-complete,不直接把它转成 addIceCandidate(null)。
验证候选交换是否真正生效
建议在两个浏览器标签页或两台不同网络的设备上测试。先确保双方通过同一信令会话完成 Offer/Answer 协商,再观察候选日志和 ICE 状态。
可在浏览器控制台执行以下片段。前提是当前页面能访问前面创建的 pc 实例。
pc.addEventListener('iceconnectionstatechange', () => {
console.log('ICE 状态:', pc.iceConnectionState);
});
pc.addEventListener('connectionstatechange', () => {
console.log('连接状态:', pc.connectionState);
});
// 查看当前已经选定的候选对
async function inspectSelectedPair() {
const stats = await pc.getStats();
for (const report of stats.values()) {
if (report.type === 'transport' && report.selectedCandidatePairId) {
const pair = stats.get(report.selectedCandidatePairId);
console.log('选定候选对:', pair?.state ?? '未知');
}
}
}
inspectSelectedPair();预期结果:如果 ICE 连通性检查成功,iceConnectionState 通常进入 connected 或 completed,connectionState 通常进入 connected。如果统计报告暴露选定候选对且其状态为成功,则控制台可能显示:
ICE 状态: connected
连接状态: connected
选定候选对: succeeded实际事件顺序和状态可能不同;如果尚未选定候选对,最后一行可能不会出现。可在 Chromium 浏览器的 chrome://webrtc-internals 中进一步查看 ICE Candidate Pair 统计信息。对于已选定的候选对,还可以根据其本地与远端候选类型判断当前使用直连还是 TURN 中继。
验收时至少覆盖三个场景:同一局域网交换 host 候选、不同 NAT 网络交换 srflx 候选,以及限制直连后使用 relay 候选。第三个场景需要预先配置可用的 TURN 服务器;只有配置 STUN 并不能保证复杂 NAT 环境下连通。
如果日志显示候选已经收到,但 ICE 始终处于 checking 后进入 failed,应依次检查远端 SDP 是否匹配、候选是否发送到正确会话、STUN/TURN 是否可达,以及防火墙是否阻止 UDP。addIceCandidate() 成功仅说明浏览器接受了候选信息,不代表候选对应的网络路径一定可达。
完成这些检查后,候选交换链路就具备了可观测的发送、接收、缓存、去重和状态验证能力,可以继续在已建立的 WebRTC 连接上使用 DataChannel 传输应用数据。