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 允许候选一产生就发送,无须等到所有候选收集完毕。这可以让远端更早开始连通性检查,减少等待完整候选集合的时间。

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。信令服务器必须根据会话标识把消息转发给另一端。

js
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 的发送及本地描述设置。服务器只转发当前会话的消息,不把发送者自己的消息回送给发送者。

js
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 实例。

js
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。如果统计报告暴露选定候选对且其状态为成功,则控制台可能显示:

text
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 传输应用数据。

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

目录与阅读设置

阅读设置

17

记录一个想法

通过信令传递 ICE 候选

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

登录哪都通