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

创建 RTCPeerConnection 并配置服务器
下面使用浏览器原生 WebRTC API,不需要安装第三方 JavaScript 库。示例适用于支持 RTCPeerConnection 的现代 Chromium、Firefox 和 Safari 浏览器。
先准备一台可访问的 STUN 服务器。如果需要验证中继候选,还必须准备已经部署并启用认证的 TURN 服务,例如 coturn。
配置示例:
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,将服务器地址和凭据替换为真实配置,再完整执行代码。
(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);预期输出示例(真实候选数量、顺序、地址及端口由网络环境决定):
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 地址与凭据:
(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 可达、认证成功且候选收集在超时前完成时,预期输出类似:
gathering completed: true
relay candidates: 1
relay discovered: truerelay 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 |
可以为连接添加错误事件监听:
// 片段示例: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 状态、候选信息及统计数据;其他浏览器的调试入口和展示字段可能不同。
建议按以下顺序验收:
- 使用
getConfiguration()确认浏览器实际采用了预期服务器配置。 - 监听
icecandidate,确认正常策略下至少发现可用候选。 - 将策略改为
relay,确认 TURN 能返回中继候选。 - 在完整双端连接中检查选中的候选对,并实际发送一条 DataChannel 消息。
当 STUN、TURN 配置正确,浏览器能够按预期发现候选,并且双端测试能完成数据传输时,才算完成了从 ICE 服务器配置到可用 WebRTC 传输路径的验证。