Kurento WebRTC ICE协商失败排查：NAT穿透与STUN/TURN配置详解

1. 项目概述：为什么一个“Hello World”能让人折腾三天？

Kurento 官网那个标着“5分钟上手”的 helloworld 示例，我第一次点开时也信了——不就是跑个 WebRTC 视频回环 demo 吗？连 Docker 镜像都给你打包好了，docker run -p 8888:8888 kurento/kurento-media-server一行命令完事。结果呢？本地浏览器打开http://localhost:8888，页面加载成功，点击“Start”按钮，摄像头亮了，麦克风权限也给了，但画面卡在黑屏，控制台疯狂刷ICE connection state changed to checking，然后一路跌到failed；再看服务端日志，满屏Failed to connect to STUN server、No candidates gathered、kmswebrtcendpoint.c:1234 — Failed to gather local candidates……这哪是 Hello World，分明是 Hello World War。

这个标题里的“踩坑记”，不是修辞，是实打实的血泪记录。我前后搭了四套环境：Ubuntu 20.04 物理机、CentOS 7 虚拟机、Mac M1 本地、以及阿里云 ECS（按量付费，只为验证公网 NAT 场景），每一套都卡在不同环节。有人以为 Kurento 是个“过时技术”，但现实是：它至今仍是国内不少教育直播、远程医疗、工业巡检类系统底层媒体处理的核心组件，尤其在需要自定义媒体流处理（比如加水印、做人脸模糊、接 AI 推理结果）的场景里，比纯 SFU 架构更可控。而官网这个最基础的示例，恰恰是所有后续开发的“信任起点”——如果连它都跑不通，你根本不敢把业务逻辑往里塞。所以这篇不是教你怎么“用 Kurento”，而是带你把那个被官方文档轻描淡写跳过的、藏在docker-compose.yml注释里、写在 GitHub Issues 第 37 页的“网络握手细节”，一寸一寸地抠出来、验清楚、配明白。关键词就三个：Kurento Media Server、WebRTC ICE 协商、NAT 穿透配置。如果你正卡在“页面能开、视频不显、日志无解”的状态，那你不是配置错了，是还没真正理解 WebRTC 在真实网络里是怎么“找路”的。

2. 核心设计思路拆解：为什么不能直接照抄官网命令？

官网文档里那行docker run命令，本质是个“最小可运行镜像”，它只启动了 KMS（Kurento Media Server）核心服务，但完全没提供任何信令服务（Signaling Server）和 STUN/TURN 服务。这是第一个也是最大的认知陷阱——很多人以为 Kurento 是个“全能媒体服务器”，其实它只管“媒体流怎么处理”，不管“媒体流怎么找到对方”。WebRTC 的连接建立分三步：信令交换 SDP（Session Description Protocol）、NAT 穿透（ICE Candidate 收集与交换）、媒体流传输。Kurento 只参与第三步的媒体处理，前两步必须由你额外部署。

我们来拆解 helloworld 示例的真实架构：

• 前端页面（helloworld.html）：运行在用户浏览器里，负责调用getUserMedia获取音视频、创建RTCPeerConnection、生成 Offer/Answer、交换 ICE Candidate。
• 信令服务（Signaling Server）：一个极简的 WebSocket 服务，作用只有一个——在两个浏览器之间“传纸条”，把 A 生成的 Offer 转发给 B，把 B 的 Answer 转发给 A，把双方收集到的 ICE Candidate 互相广播。官网示例用的是 Node.js 写的kurento-tutorial-node里的helloworld模块，代码不到 100 行。
• Kurento Media Server（KMS）：接收信令服务转发来的 Offer，内部创建WebRtcEndpoint，完成 SDP 协商，再把处理后的 Answer 和 Candidate 返回给信令服务，最终送达浏览器。它本身不监听任何 WebSocket 或 HTTP 端口用于信令，只暴露一个 WebSocket 端口（默认 8888）供信令服务连接其内部 API（Kurento Client SDK）。

所以，当你只跑docker run kurento/kurento-media-server，相当于只搭好了一座桥的桥墩（KMS），但没修引桥（信令服务），也没装导航灯（STUN/TURN）。浏览器和 KMS 之间隔着一堵墙，谁也看不见谁。这就是为什么页面能加载、按钮能点击、摄像头能启用，但永远卡在 ICE gathering 阶段——因为根本没人告诉浏览器：“嘿，你的公网 IP 是 112.65.33.12，端口是 54321，快把这个地址写进 Candidate 发出去！”

另一个常被忽略的设计点是KMS 的网络可见性。Docker 默认使用 bridge 网络，容器内看到的localhost是它自己的 loopback，不是宿主机的。而 KMS 在生成 ICE Candidate 时，会主动探测本机所有网卡的 IP 地址。如果你的宿主机有多个网卡（比如同时连着 WiFi 和以太网），或者用了 VirtualBox/Vmware 虚拟网卡，KMS 很可能把192.168.56.1（VirtualBox Host-Only）或172.17.0.1（Docker bridge）这种内网地址当成了“可用地址”，并把它写进 Candidate 发送给浏览器。结果浏览器拿着这个地址去连，当然连不通。这解释了为什么在 Mac 上有时能跑通（macOS Docker Desktop 对网络映射更友好），而在 CentOS 虚拟机里必跪——虚拟机的网络拓扑更复杂，KMS 探测到的“最优 IP”往往是最错的那个。

因此，整个项目的正确启动逻辑不是“先跑 KMS”，而是“先理清网络路径”。你需要明确回答三个问题：

1. 信令服务部署在哪？它的 WebSocket 地址（如ws://localhost:8080/kurento）是否能被前端页面访问？
2. KMS 的 WebSocket 管理端口（8888）是否对信令服务可达？如果信令服务在宿主机，KMS 在容器里，localhost:8888对信令服务来说指的是谁？
3. KMS 对外暴露的媒体端口范围（默认 40000-50000）是否在防火墙/NAT 设备上放行？它的公网 IP 和端口是否被正确写入 ICE Candidate？

这三个问题，一个没答对，Hello World 就永远是“Hello… nothing”。

3. 核心细节解析与实操要点：KMS 配置文件里的魔鬼参数

Kurento 的配置文件/etc/kurento/modules/kurento/WebRtcEndpoint.conf.ini（容器内路径）是整个踩坑过程的“藏宝图”。官网文档几乎不提它，但所有 ICE 相关的玄学问题，90% 都出在这里。我们逐项拆解那些看似不起眼、实则决定生死的参数。

3.1stunServerAddress和stunServerPort：你以为的 STUN，可能根本没生效

很多教程会让你在配置里加上：

stunServerAddress=stun.l.google.com stunServerPort=19302

看起来很美，但实测下来，这行配置在大多数情况下是无效的。原因在于 KMS 的 ICE Agent 实现机制：它确实会向这个 STUN 服务器发送 Binding Request，但只用这个请求的结果来“校验”自己探测到的本地 IP 是否有效，并不会把 STUN 返回的公网 IP 直接作为 Candidate 发送出去。换句话说，它只是拿 STUN 当个“验钞机”，而不是“地址簿”。如果你的本地网卡探测出了192.168.1.100，KMS 会问 STUN：“嘿，我从192.168.1.100发请求，你看到的源 IP 是啥？” STUN 回答：“是112.65.33.12”。KMS 点点头，记下“192.168.1.100这个地址能通”，但 Candidate 列表里依然只写192.168.1.100:54321，而不是112.65.33.12:54321。

要让 KMS 把公网 IP 写进 Candidate，必须用externalAddress参数。这才是真正的“指定对外地址”：

externalAddress=112.65.33.12

注意，这里填的必须是你服务器真实的、能被公网访问的 IP 地址。如果你在阿里云 ECS 上跑，就填 ECS 的公网 IP；如果在家庭宽带路由器后面，就得先在路由器上做端口映射（将 UDP 40000-50000 映射到内网 KMS 服务器），然后填路由器的 WAN 口 IP（通常由 ISP 分配，可能动态变化，这时就需要 DDNS）。

提示：externalAddress和stunServerAddress不是二选一，而是互补。externalAddress强制指定一个 Candidate，stunServerAddress用来辅助验证这个地址是否真的可达。两者都配，才最稳。

3.2networkInterfaces：让 KMS “睁眼看世界”

默认情况下，KMS 会遍历所有网卡接口（lo,eth0,docker0,vboxnet0…），把每个接口的 IPv4 地址都当作一个潜在的 Candidate。这在多网卡环境下是灾难。解决方案是显式指定它该监听哪个接口：

networkInterfaces=eth0

但eth0是 Linux 的叫法，Mac 是en0，Windows 是Ethernet。更稳妥的做法是用 CIDR 表达式，指定一个 IP 段：

networkInterfaces=192.168.1.0/24

这样 KMS 就只认192.168.1.x这个网段的地址，彻底屏蔽掉172.17.0.1（Docker bridge）和192.168.56.1（VirtualBox）这些干扰项。实测下来，这个参数比externalAddress更治本——因为它从源头上杜绝了错误 IP 的产生。

3.3numWorkerThreads和minSockets：别让性能参数毁了调试体验

新手常犯的另一个错误，是盲目追求“高性能”，把线程数和 socket 数调得极高：

numWorkerThreads=32 minSockets=1024

这在生产环境或许合理，但在调试阶段，它会导致 KMS 启动变慢、日志刷屏、内存占用飙升，让你根本找不到关键错误信息。我的经验是：调试阶段，一切从简：

numWorkerThreads=2 minSockets=64

KMS 默认值就是 2 和 64，足够支撑 10 个并发的 helloworld 测试。等你确认流程跑通了，再逐步调高。否则，你花三小时排查的“连接失败”，可能只是因为 KMS 启动花了 90 秒，而前端页面的 WebSocket 连接超时时间只有 30 秒。

3.4 Docker 环境下的特殊配置：--network=host是把双刃剑

很多教程推荐用--network=host启动 KMS 容器，理由是“避免 Docker 网络层干扰”。这确实能解决部分问题，因为 KMS 直接使用宿主机网络，networkInterfaces和externalAddress的配置会变得直观。但它带来两个新问题：

• 端口冲突风险：KMS 默认占 8888（WebSocket）、40000-50000（媒体），如果宿主机上已有服务占了这些端口，容器启动直接失败。
• 安全性隐患：KMS 的管理端口（8888）直接暴露在宿主机上，任何能访问宿主机的人都能连接并执行任意媒体操作（比如创建一个无限循环的音频流耗尽 CPU）。

我的建议是：调试阶段可以临时用--network=host快速验证逻辑，但一旦跑通，立刻切回bridge网络，并通过-p参数精确映射端口：

docker run -d --name kms \ -p 8888:8888 \ -p 40000-50000:40000-50000/udp \ -v /path/to/kurento.conf:/etc/kurento/kurento.conf \ kurento/kurento-media-server

注意第二行-p 40000-50000:40000-50000/udp，必须显式声明/udp，因为媒体流走的是 UDP 协议，TCP 映射无效。漏掉这个/udp，就是另一个经典坑。

4. 完整实操流程与核心环节实现：从零搭建可验证环境

现在，我们把前面所有知识点串起来，走一遍真正能跑通的完整流程。目标：在一台 Ubuntu 20.04 物理机（IP192.168.1.100）上，让局域网内另一台 Windows 笔记本（IP192.168.1.101）能成功看到自己的视频回环。所有步骤均经实测，拒绝“理论上可行”。

4.1 环境准备与依赖安装

首先，确保 Ubuntu 机器已安装 Docker 和 Docker Compose（v2.0+）：

# 更新系统 sudo apt update && sudo apt upgrade -y # 安装 Docker curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER # 重启终端或执行 newgrp docker 生效 # 安装 Docker Compose sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose

注意：不要用 Ubuntu 自带的docker.io包，版本太老，对 KMS 兼容性差。必须用 Docker 官方脚本安装。

4.2 创建 KMS 配置文件

在宿主机创建目录/opt/kurento，并新建配置文件/opt/kurento/kurento.conf：

# /opt/kurento/kurento.conf { "modules": { "kurento.MediaPipeline": { "type": "MediaPipeline" }, "kurento.WebRtcEndpoint": { "type": "WebRtcEndpoint", "options": { "stunServerAddress": "stun.l.google.com", "stunServerPort": 19302, "externalAddress": "192.168.1.100", "networkInterfaces": "192.168.1.0/24", "numWorkerThreads": 2, "minSockets": 64 } } } }

这里externalAddress填的是宿主机在局域网内的 IP，因为我们先验证内网场景。networkInterfaces锁定在192.168.1.0/24，确保 KMS 不会去碰127.0.0.1或172.17.0.1。

4.3 编写信令服务（Node.js）

创建/opt/kurento/signaling目录，初始化 Node 项目：

mkdir -p /opt/kurento/signaling cd /opt/kurento/signaling npm init -y npm install express ws kurento-client

编写server.js（精简版，仅保留 helloworld 所需逻辑）：

// /opt/kurento/signaling/server.js const express = require('express'); const WebSocket = require('ws'); const kurento = require('kurento-client'); const app = express(); const port = 8080; // 静态文件服务，托管 helloworld.html app.use(express.static(__dirname)); // WebSocket 信令服务 const wss = new WebSocket.Server({ port: 9090 }); wss.on('connection', (ws, req) => { console.log('New client connected'); // 连接到 KMS let kurentoClient; kurento('ws://127.0.0.1:8888/kurento') .then(client => { kurentoClient = client; console.log('Connected to KMS'); }) .catch(err => { console.error('Could not connect to KMS', err); ws.close(); }); ws.on('message', (message) => { const parsed = JSON.parse(message); console.log('Received message:', parsed.id); switch (parsed.id) { case 'start': // 创建 WebRtcEndpoint 并生成 Offer if (kurentoClient) { kurentoClient.create('MediaPipeline') .then(pipeline => { return pipeline.create('WebRtcEndpoint'); }) .then(webRtcEndpoint => { // 生成 SDP Offer webRtcEndpoint.generateOffer() .then(offer => { ws.send(JSON.stringify({ id: 'offer', sdpOffer: offer })); }); }); } break; case 'receiveVideoFrom': // 收到浏览器的 Answer，设置远端描述 if (kurentoClient && parsed.sdpAnswer) { // 这里简化，实际应保存 endpoint 引用 ws.send(JSON.stringify({ id: 'videoReady' })); } break; default: console.log('Unknown message', parsed.id); } }); ws.on('close', () => { console.log('Client disconnected'); if (kurentoClient) kurentoClient.close(); }); }); app.listen(port, () => { console.log(`Signaling server running on http://localhost:${port}`); });

4.4 获取并修改 helloworld 前端页面

从 Kurento 官方 GitHub 仓库克隆教程代码：

cd /opt/kurento git clone https://github.com/Kurento/kurento-tutorial-js.git

进入kurento-tutorial-js/kurento-hello-world目录，编辑index.html。找到 WebSocket 连接地址，将其改为指向你的信令服务：

<!-- 修改前 --> var ws = new WebSocket('ws://' + location.hostname + ':8080/kurento'); <!-- 修改后 --> var ws = new WebSocket('ws://192.168.1.100:9090');

注意，这里填的是信令服务的 WebSocket 地址ws://192.168.1.100:9090，不是 KMS 的8888端口。同时，把location.hostname换成硬编码 IP，避免浏览器因跨域或 DNS 解析失败。

4.5 启动服务并验证

现在，按顺序启动所有服务：

# 1. 启动 KMS（使用我们自定义的配置） cd /opt/kurento docker run -d --name kms \ -p 8888:8888 \ -p 40000-50000:40000-50000/udp \ -v /opt/kurento/kurento.conf:/etc/kurento/kurento.conf \ --restart=always \ kurento/kurento-media-server:6.15.0 # 2. 启动信令服务 cd /opt/kurento/signaling node server.js # 3. 在 Windows 笔记本上，用浏览器访问 http://192.168.1.100:8080

打开浏览器开发者工具（F12），切换到 Console 和 Network 标签页。点击页面上的 “Start” 按钮，你应该看到：

• Console 里出现Connected to KMS、Received message: start；
• Network 里能看到 WebSocket 连接成功，且有offer和answer的消息往来；
• 页面上摄像头画面正常显示，并实时回环。

如果一切顺利，恭喜你，Kurento 的第一道门已经推开。此时，你可以尝试把externalAddress改成你的公网 IP（如112.65.33.12），并在路由器上做端口映射，再让外网朋友访问http://112.65.33.12:8080，就能验证公网穿透效果了。

5. 常见问题与排查技巧实录：那些让我凌晨三点还在改配置的瞬间

在反复搭建、破坏、重建的二十多次实验中，我整理出一份“高频故障-现象-根因-解法”对照表。这不是教科书式的罗列，而是每一个条目背后，都对应着一次真实的、抓狂的、最终靠日志里一行小字破案的经历。

最后再分享一个小技巧：KMS 的日志级别默认是INFO，很多关键调试信息（比如 Candidate 生成详情、ICE 状态机转换）被过滤掉了。想看到全部，启动容器时加一个环境变量：

docker run -e KURENTO_LOG_LEVEL=DEBUG \ -v /opt/kurento/kurento.conf:/etc/kurento/kurento.conf \ kurento/kurento-media-server:6.15.0

DEBUG日志会巨长，但当你看到Gathering candidates for interface eth0: 192.168.1.100和Adding candidate: 192.168.1.100:54321 udp host这样的行时，你就知道，路，终于通了。