ZLMediaKit WebRTC黑屏问题排查与解决方案

问题现象描述

在使用ZLMediaKit进行WebRTC功能测试时，用户反馈在外部网络环境下访问WebRTC测试页面时出现黑屏并伴有持续加载动画的情况。尽管调用接口进行录制和截图功能均能正常工作，但WebRTC视频流无法正常显示。

问题分析

通过对日志和配置的深入分析，我们发现WebRTC连接最终状态显示为"failed"。从技术角度来看，WebRTC连接建立失败通常与以下几个因素有关：

1. ICE候选地址问题：WebRTC需要正确的ICE候选地址来建立P2P连接
2. 端口映射配置：UDP/TCP端口映射不正确会导致媒体流无法传输
3. NAT穿透问题：在复杂网络环境下需要正确配置外部IP地址

关键发现

检查日志发现，虽然SDP协商成功完成，但ICE连接最终失败。进一步分析配置发现：

1. RTC模块配置了externIP参数，指向公网IP地址
2. 网络安全组仅开放了TCP端口，未开放UDP端口
3. Docker容器端口映射配置存在不一致性

解决方案

经过技术验证，解决此问题需要以下步骤：

1. 正确配置RTC模块参数

在config.ini配置文件中，确保rtc模块配置正确：

[rtc]
externIP=公网IP地址  # 必须设置为服务器的公网IP
port=27233          # 自定义UDP端口
tcpPort=27233       # 自定义TCP端口

2. 完善Docker端口映射

在docker-compose.yml中，需要同时映射UDP和TCP端口：

ports:
  - "27233:27233/udp"  # UDP端口映射
  - "27233:27233/tcp"  # TCP端口映射

3. 网络安全组配置

在云服务器安全组中，需要同时放行UDP和TCP协议的对应端口：

• 协议类型：UDP和TCP
• 端口范围：27233（或自定义端口）
• 授权对象：0.0.0.0/0

技术原理深入

WebRTC协议在建立连接时，会同时尝试UDP和TCP两种传输方式：

1. UDP协议：用于传输实时音视频数据，具有低延迟特性
2. TCP协议：用于信令传输和数据通道

在NAT环境下，必须正确配置externIP参数，服务器才能向客户端提供有效的ICE候选地址。同时，UDP端口的开放至关重要，因为大多数WebRTC实现会优先使用UDP传输媒体流。

最佳实践建议

1. 双协议支持：始终同时配置UDP和TCP端口
2. 网络诊断：使用工具检查端口连通性
3. 日志分析：关注ICE协商过程和连接状态变化
4. 渐进式调试：先从局域网环境测试，再扩展到公网

总结

ZLMediaKit作为一款优秀的流媒体服务器，其WebRTC功能的稳定运行依赖于正确的网络配置。通过本文的分析和解决方案，开发者可以快速定位和解决WebRTC黑屏问题，确保音视频流的正常传输。理解WebRTC底层协议原理对于排查此类问题至关重要，正确的端口配置和网络环境准备是保证功能正常的基础条件。