mediamtx 中 WebRTC 客户端连不上或 ICE 协商失败怎么按顺序排查？

mediamtx 中 WebRTC 客户端连不上或 ICE 协商失败怎么按顺序排查【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx在 MediaMTX 中WebRTC 的 HTTP 握手8889 端口能通、页面或 WHIP/WHEP 请求能发出但 peer connection 迟迟建立不起来、最终超时或报 ICE 协商失败是文档明确列出的典型网络场景服务器在容器内或服务器与客户端之间存在 NAT / 防火墙。本文按官方文档 Solving WebRTC connectivity issues 给出的优先级顺序给出从静态 UDP 端口到 TURN 中继的完整排查路径每一步都有对应的配置项和验证方式。先理解 MediaMTX 建立 WebRTC 连接的四种方式在 WebRTC 中服务器和客户端的握手通过标准 HTTP 请求完成媒体流则走握手后建立的 peer connection 专用通道。docs/2-features/25-webrtc-specific-features.md 按效率和简便程度从高到低列出四种建立 peer connection 的方式使用静态 UDP 服务器端口webrtcLocalUDPAddress需有值默认已启用使用静态 TCP 服务器端口webrtcLocalTCPAddress需有值默认未启用使用随机 UDP 端口配合打洞技术webrtcICEServers2需配置 STUN 服务器默认没有使用暴露 TCP 端口、由服务器和客户端共同访问的 TURN 中继webrtcICEServers2需配置 TURN 服务器默认没有。排查思路就是沿这条链逐级降级优先保住默认的 UDP 路径走不通再换 TCP再不行上 STUN最后才用 TURN。排查第 0 步确认基线配置与监听状态先确认服务器确实按默认方式在监听。查看 mediamtx.yml 中 WebRTC 部分的关键默认值mediamtx.yml#L374-L428webrtc: true webrtcAddress: :8889 webrtcLocalUDPAddress: :8189 # 默认启用的 UDP/ICE 监听端口 webrtcLocalTCPAddress: # 默认禁用 webrtcAdditionalHosts: [] # 默认空 webrtcICEServers2: [] # 默认没有 STUN/TURN启动后可在日志中确认监听器已打开。docs/2-features/18-logging.md 给出的示例输出文档示例{timestamp:20XX-YY-ZZT10:45:05.99999999901:00,level:INF,message:[WebRTC] listener opened on :8889 (TCP/HTTP), :8189 (UDP/ICE)}看到这一行说明 8889HTTP 握手和 8189UDP/ICE两个监听器都已就绪。如果 UDP 监听缺失webrtcLocalUDPAddress被设为空串说明默认路径已被你主动禁用需要先恢复它或转向后面的方案。另外注意一个容易混淆的点如果最终能连上但画面解不出来那属于浏览器编解码兼容性问题见 docs/4-read/03-webrtc.md 引用的浏览器 codec 限制不是本文的 ICE 问题二者要分开判断。排查第 1 步webrtcAdditionalHosts 是否包含客户端可达的 IP文档要求的第一件事是确保webrtcAdditionalHosts包含客户端能用来到达服务器的地址。配置项含义见 mediamtx.yml#L411-L412# Additional hosts or IPs to send to clients.。按客户端位置选择值下面的192.168.x.x、1.2.3.4、my-dns.example.org均为文档中的示例格式替换为你的实际地址客户端与服务器在同一局域网加入服务器的局域网地址客户端从互联网访问加入服务器的公网 IP或有 DNS 名则加入 DNS 名。可以同时加多个值覆盖所有场景webrtcAdditionalHosts: [192.168.x.x, 1.2.3.4, my-dns.example.org, ...]如果你通过 Docker 启动且不想挂载配置文件安装文档 docs/1-kickoff/2-install.md 给出了等价的环境变量写法docker run --rm -it \ -e MTX_WEBRTCADDITIONALHOSTS192.168.x.x \ -p 8554:8554 \ -p 1935:1935 \ -p 8888:8888 \ -p 8889:8889 \ -p 8892:8892 \ -p 8890:8890/udp \ -p 8189:8189/udp \ -p 8892:8892/udp \ -p 8893:8893/udp \ bluenviron/mediamtx:1其中MTX_WEBRTCADDITIONALHOSTS要填入客户端实际连接服务器使用的 IP文档说明-p 8189:8189/udp即下文的 UDP 转发。如何判断这一步生效用浏览器访问http://服务器IP:8889/mystream读取页面见 docs/4-read/03-webrtc.md或 WHIP 推流页http://服务器IP:8889/mystream/publish。若仍连不上进入第 2 步。排查第 2 步打通 8189 端口的 UDP 转发如果服务器与客户端之间存在 NAT / 容器必须配置其把入站的8189 端口所有 UDP 报文转发到服务器。使用 Docker 时官方给出的对应启动参数是下面只保留与本问题相关的部分完整端口列表参见 docs/1-kickoff/2-install.mddocker run --rm -it \ -p 8189:8189/udp \ bluenviron/mediamtx:1非 Docker 的 NAT / 防火墙环境需要自行做等价规则放行入站 UDP 8189 并指向服务器进程。判断若端口已正确转发但连接仍失败文档给出的下一个假设是 UDP 被防火墙直接阻断转入第 3 步切到 TCP。排查第 3 步改用静态 TCP 端口webrtcLocalTCPAddressUDP 被阻断时让 ICE 走 TCP。启用 TCP 服务器端口webrtcLocalTCPAddress: :8189配置生效后NAT / 容器需要改为把入站的8189 端口所有 TCP 报文转发到服务器对应 Docker 参数为-p 8189:8189/tcp与 UDP 版是不同协议需单独放行。注意 mediamtx.yml#L401-L403 对该默认禁用的解释This is disabled by default since TCP is less efficient than UDP and introduces a progressive delay when network is congested.TCP 效率低于 UDP且网络拥塞时会引入渐进式延迟。所以这一步是降级手段UDP 可用时不应长期停留在 TCP 方案。排查第 4 步配置 STUN 做 UDP 打洞如果 TCP 也不通可让服务器和客户端各自通过 STUN 服务器发现自己的公网 IP然后用UDP 打洞在随机 UDP 端口上建立连接——这种随机端口不需要显式放行webrtcICEServers2: - url: stun:stun.l.google.com:19302webrtcICEServers2的完整用法包括username、password、clientOnly字段在 mediamtx.yml#L413-L422 有注释说明配置项含义为STUN 服务器用于获取并共享服务器公网 IPTURN/TURNS 服务器强制所有流量经过中继。排查第 5 步强制所有 WebRTC/ICE 连接走 TURN前面的方式都失败时最后的兜底是强制所有 WebRTC/ICE 连接经过 TURN 服务器。服务器地址和凭据写在配置文件里webrtcICEServers2: - url: turn:host:port username: user password: password文档特别强调port不是可选的turn:host:port中必须写端口。如果 TURN 服务器使用基于密钥的认证例如 Coturn 的use-auth-secret选项则用户名固定填AUTH_SECRET密码填密钥webrtcICEServers2: - url: turn:host:port username: AUTH_SECRET password: secret此时secret为 TURN 服务器的密钥。MediaMTX 会用该密钥生成一组凭据并在 WebRTC/ICE 连接建立前发送给客户端见 docs/2-features/25-webrtc-specific-features.md。还有一个变体某些场景希望浏览器走 TURN、但 MediaMTX 自己不走例如 TURN 与 mediamtx 同网段。文档提供了clientOnly字段webrtcICEServers2: - url: turn:host:port username: user password: password clientOnly: true可选分支用 Coturn 自建 TCP TURN 服务器文档说明 Coturn 方案only if all other WebRTC connectivity methods have failed时才需要。官方给出的 Docker 启动命令会实际运行一个 Coturn 容器使用 host 网络模式docker run --rm -it \ --networkhost \ coturn/coturn \ --log-filestdout -v \ --no-udp --no-dtls --no-tls \ --min-port49152 --max-port65535 \ --use-auth-secret --static-auth-secretmysecret -r myrealm文档中各项设置的用途说明只启用 TCP 传输--no-udp既然其他方式都失败了TCP 更可靠--networkhostCoturn 会为每个 peer connection 分配一个 TCP 端口--min-port/--max-port指定 TCP 端口范围49152–65535--use-auth-secret启用密钥认证避免客户端保存长期有效的凭据。然后让 MediaMTX 指向该 TURN 服务器REPLACE_WITH_COTURN_IP需替换为 Coturn 所在机器 IPwebrtcICEServers2: - url: turn:REPLACE_WITH_COTURN_IP:3478?transporttcp username: AUTH_SECRET password: mysecret其中?transporttcp后缀用于强制使用 TCPAUTH_SECRET作为用户名、共享密钥作为密码与上面 Coturn 的--static-auth-secretmysecret对应。验证与结果判断每一级配置修改后用下面的方式复测直到某一步能稳定建立连接浏览器读取访问http://服务器IP:8889/mystream把mystream换成实际路径名页面能播流即 peer connection 建立成功WHEP 读取使用支持 WHEP 的客户端请求http://服务器IP:8889/mystream/whep见 docs/4-read/03-webrtc.mdWHIP 推流浏览器访问http://服务器IP:8889/mystream/publish或支持 WHIP 的推流端请求http://服务器IP:8889/mystream/whip见 docs/3-publish/05-webrtc-clients.md。修改方式方面docs/2-features/05-configuration.md 说明配置文件可以在服务器运行时热重载hot reloading直接写入配置文件即可变更会被检测并应用且尽可能在不断开现有客户端的情况下生效。因此排查时改mediamtx.ymlDocker 内路径为/mediamtx.yml后无需重启容器也可以用MTX_参数名大写形式的环境变量如MTX_WEBRTCADDITIONALHOSTS覆盖单个参数。边界与限制四种连接方式有明确的效率排序官方建议停留在能用的高优先级方式上TCP 方案在网络拥塞时延迟会渐进增大mediamtx.yml#L401-L403。turn:host:port的端口必须显式给出clientOnly: true只让客户端使用 TURNMediaMTX 本身不走 TURN。即使连接成功浏览器能否解码还取决于编解码兼容性与服务器无关的限制H265 在多数浏览器中不能直接读Chrome 仅在 Windows 且具备相应 GPU 时支持 H265含 B-frames 的 H264 流被所有浏览器有意不支持见 docs/2-features/25-webrtc-specific-features.md 的 Codec support in browsers 一节。若需要最大浏览器兼容性文档建议用 FFmpeg 以 H264 baseline profile Opus 重编码后推入。【免费下载链接】mediamtxReady-to-use Media-over-QUIC / SRT / WebRTC / RTSP / RTMP / LL-HLS / MPEG-TS / RTP live media server and media proxy that allows to read, publish, proxy, record and playback real-time video and audio streams.项目地址: https://gitcode.com/GitHub_Trending/me/mediamtx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考