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

为浏览器配置 ICE 服务器

为浏览器配置 ICE 服务器

浏览器建立 WebRTC 连接时,需要知道从哪里获取公网候选地址,以及直连失败后可以使用哪台中继服务器。本课通过 RTCPeerConnection 的 iceServers 配置接入 STUN 和 TURN,运行候选收集示例,并验证浏览器是否真正发现了 host、srflx 和 relay 候选。

学习目标

  • 使用 RTCPeerConnection 配置 STUN、TURN 地址及认证凭据。
  • 理解浏览器如何利用 ICE 服务器收集不同类型的候选地址。
  • 通过浏览器开发者工具检查候选收集结果,定位常见配置错误。

理解 iceServers 的作用

WebRTC 使用 ICE(Interactive Connectivity Establishment)发现并检查通信路径。浏览器首先获取本地接口候选,再通过 STUN 发现 NAT 映射后的公网地址,必要时通过 TURN 获取中继候选。

RTCPeerConnection 构造函数接受 RTCConfiguration 对象,其中 iceServers 是 ICE 服务器配置数组。每个 RTCIceServer 对象可以包含 urls、username 和 credential。

字段 类型 作用
urls 字符串或字符串数组 指定 STUN、TURN 服务器 URI
username 字符串 TURN 长期凭据认证使用的用户名
credential 字符串 TURN 认证密码或凭据
credentialType 字符串 可选,常用值为 password

常见 URI 格式如下:

  • stun:stun.example.com:3478:向 STUN 服务器查询映射地址。
  • turn:turn.example.com:3478?transport=udp:通过 UDP 访问 TURN 服务器。
  • turn:turn.example.com:3478?transport=tcp:通过 TCP 访问 TURN 服务器。
  • turns:turn.example.com:5349?transport=tcp:通过 TLS 访问 TURN 服务器。

这些域名仅为配置示例,不能直接当作已经部署的服务使用。实际运行时必须替换为可解析、可访问的服务器地址。

浏览器通过 STUN 与 TURN 收集 ICE 候选的网络结构

创建 RTCPeerConnection 并配置服务器

下面使用浏览器原生 WebRTC API,不需要安装第三方 JavaScript 库。示例适用于支持 RTCPeerConnection 的现代 Chromium、Firefox 和 Safari 浏览器。

先准备一台可访问的 STUN 服务器。如果需要验证中继候选,还必须准备已经部署并启用认证的 TURN 服务,例如 coturn。

配置示例:

js
const iceServers = [
  {
    urls: 'stun:stun.example.com:3478'
  },
  {
    urls: [
      'turn:turn.example.com:3478?transport=udp',
      'turn:turn.example.com:3478?transport=tcp',
      'turns:turn.example.com:5349?transport=tcp'
    ],
    username: 'demo-user',
    credential: 'replace-with-temporary-secret',
    credentialType: 'password'
  }
];

const pc = new RTCPeerConnection({
  iceServers,
  iceTransportPolicy: 'all',
  iceCandidatePoolSize: 0
});

console.log(pc.getConfiguration());

这是可以在浏览器开发者工具 Console 中执行的配置示例。执行前必须将示例域名及 TURN 凭据替换为真实值;示例中的用户名和密码并不是有效账号。

预期结果:getConfiguration() 返回包含所配置 iceServers 的对象,同时能够看到 iceTransportPolicy 为 all、iceCandidatePoolSize 为 0。浏览器还可能返回其他默认配置字段。

iceTransportPolicy 有两个常用取值:

取值 行为 适用场景
all 允许使用所有符合策略的候选类型 正常连接及直连优先场景
relay 只允许使用中继候选进行 ICE 连接 强制验证 TURN 或要求仅经中继通信

iceCandidatePoolSize: 0 表示不提前维护候选池。本课使用默认行为,让候选收集从创建 Offer 后开始,便于观察事件。

触发候选收集并观察结果

仅创建 RTCPeerConnection,通常不会立即启动本例所需的候选收集。需要创建可协商的媒体或数据通道,并完成本地描述设置。

下面给出一个独立运行的浏览器示例。打开任意普通网页的开发者工具 Console,将服务器地址和凭据替换为真实配置,再完整执行代码。

js
(async () => {
  const pc = new RTCPeerConnection({
    iceServers: [
      { urls: 'stun:stun.example.com:3478' },
      {
        urls: 'turn:turn.example.com:3478?transport=udp',
        username: 'demo-user',
        credential: 'replace-with-temporary-secret'
      }
    ],
    iceTransportPolicy: 'all'
  });

  const candidates = [];

  // 在设置本地描述之前注册事件,避免遗漏早期候选。
  pc.addEventListener('icecandidate', (event) => {
    if (event.candidate) {
      const c = event.candidate;
      candidates.push(c);
      console.log('candidate:', c.type, c.protocol);
    } else {
      console.log('ICE gathering complete');
    }
  });

  pc.addEventListener('icegatheringstatechange', () => {
    console.log('gathering:', pc.iceGatheringState);
  });

  // 数据通道让 SDP 包含需要进行 ICE 收集的传输。
  pc.createDataChannel('probe');
  const offer = await pc.createOffer();
  await pc.setLocalDescription(offer);

  // 等待收集完成或达到测试超时,避免无限等待。
  await Promise.race([
    new Promise((resolve) => {
      if (pc.iceGatheringState === 'complete') {
        resolve();
        return;
      }
      pc.addEventListener('icegatheringstatechange', () => {
        if (pc.iceGatheringState === 'complete') resolve();
      });
    }),
    new Promise((resolve) => setTimeout(resolve, 10000))
  ]);

  console.table(candidates.map((c) => ({
    type: c.type,
    protocol: c.protocol,
    address: c.address,
    port: c.port
  })));

  console.log('final state:', pc.iceGatheringState);
  pc.close();
})().catch(console.error);

预期输出示例(真实候选数量、顺序、地址及端口由网络环境决定):

text
gathering: gathering
candidate: host udp
candidate: srflx udp
candidate: relay udp
gathering: complete
ICE gathering complete
final state: complete

示例还会通过 console.table() 显示候选明细。实际地址、端口属于动态值,可分别记为 <ADDRESS> 和 <PORT>。事件触发顺序以及候选类型并不固定,TURN 不可达时可能没有 relay,STUN 不可达时可能没有 srflx。

浏览器可能使用 mDNS 主机名隐藏本地 IP,部分候选的 address 也可能受到浏览器隐私策略限制。不要把看不到明文局域网 IP 直接判定为 ICE 失败。

这段代码只验证本地候选收集,没有设置远端描述,也没有交换候选或执行完整的双端连接。因此即使收集到 relay,也不代表数据通道已经成功建立。

验证 TURN 中继是否真正可用

正常模式下,ICE 可以选择直连候选,因此仅观察到连接成功,不能证明 TURN 正常工作。验证中继时应将 iceTransportPolicy 改为 relay,并检查是否成功产生中继候选。

可以直接在开发者工具中执行下面的独立测试,使用真实 TURN 地址与凭据:

js
(async () => {
  const pc = new RTCPeerConnection({
    iceServers: [{
      urls: 'turn:turn.example.com:3478?transport=udp',
      username: 'demo-user',
      credential: 'replace-with-temporary-secret'
    }],
    iceTransportPolicy: 'relay'
  });

  let relayCount = 0;

  pc.addEventListener('icecandidate', (event) => {
    if (event.candidate?.type === 'relay') relayCount++;
  });

  pc.createDataChannel('relay-test');
  await pc.setLocalDescription(await pc.createOffer());

  // 等待收集结束,超时则报告未完成状态。
  const completed = await Promise.race([
    new Promise((resolve) => {
      if (pc.iceGatheringState === 'complete') return resolve(true);
      pc.addEventListener('icegatheringstatechange', () => {
        if (pc.iceGatheringState === 'complete') resolve(true);
      });
    }),
    new Promise((resolve) => setTimeout(() => resolve(false), 10000))
  ]);

  console.log('gathering completed:', completed);
  console.log('relay candidates:', relayCount);
  console.log('relay discovered:', relayCount > 0);
  pc.close();
})().catch(console.error);

当 TURN 可达、认证成功且候选收集在超时前完成时,预期输出类似:

text
gathering completed: true
relay candidates: 1
relay discovered: true

relay candidates 的实际数量可能大于 1。如果结果为 0,说明本次测试未发现中继候选,需要进一步检查 TURN 服务,而不能直接认定服务器一定不可用。

若要证明 TURN 可以真正传输业务数据,还需要两个 PeerConnection 完成 Offer/Answer、ICE 候选交换及连通性检查,并验证 DataChannel 进入 open 状态且能双向收发消息。单端候选收集只能证明浏览器成功获取了中继候选。

排查 ICE 服务器配置失败

候选缺失时,优先检查浏览器事件、服务器地址和认证信息,不要立即修改 NAT 或防火墙策略。

现象 常见原因 检查方法
没有 srflx STUN 不可达或网络限制 检查域名解析、UDP 3478 可达性及浏览器错误事件
没有 relay TURN 认证失败、服务不可达或中继分配失败 检查用户名、密码、TURN 日志及中继端口范围
icecandidateerror STUN/TURN 请求发生错误 记录事件的 url、errorCode 和 errorText
收集到候选但连接失败 双端候选交换、连通性检查或网络路径存在问题 检查信令交换和 ICE connection state
relay 存在但数据通道不通 远端协商未完成或中继传输路径失败 完成双端协商并检查 selected candidate pair

可以为连接添加错误事件监听:

js
// 片段示例:pc 是已经创建的 RTCPeerConnection 实例。
pc.addEventListener('icecandidateerror', (event) => {
  console.error('ICE server error:', {
    url: event.url,
    errorCode: event.errorCode,
    errorText: event.errorText
  });
});

这段代码必须在候选收集开始前注册。错误事件可能包含浏览器或网络环境相关的信息,其中错误码 701 是部分浏览器报告 STUN/TURN 服务器不可达时使用的浏览器特定错误码,不能将其理解为 TURN 协议统一定义的认证失败码。

在 Chromium 浏览器中,可以使用 chrome://webrtc-internals 查看 PeerConnection 的 ICE 状态、候选信息及统计数据;其他浏览器的调试入口和展示字段可能不同。

建议按以下顺序验收:

  1. 使用 getConfiguration() 确认浏览器实际采用了预期服务器配置。
  2. 监听 icecandidate,确认正常策略下至少发现可用候选。
  3. 将策略改为 relay,确认 TURN 能返回中继候选。
  4. 在完整双端连接中检查选中的候选对,并实际发送一条 DataChannel 消息。

当 STUN、TURN 配置正确,浏览器能够按预期发现候选,并且双端测试能完成数据传输时,才算完成了从 ICE 服务器配置到可用 WebRTC 传输路径的验证。

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

目录与阅读设置

阅读设置

17

记录一个想法

为浏览器配置 ICE 服务器

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

登录哪都通