ZLMediaKit作为一款基于C++11的高性能运营级流媒体服务框架，在RTSP/RTMP/HLS/HTTP-FLV/WebSocket-FLV/GB28181/WebRTC等多种流媒体协议支持方面表现出色。但在实际部署和使用过程中，开发者可能会遇到各种问题。本文汇总了ZLMediaKit的常见故障场景及其解决方案，帮助您快速定位和解决问题。

【免费下载链接】ZLMediaKit 项目地址: https://gitcode.com/gh_mirrors/zlm/ZLMediaKit

🔍 配置相关问题

配置文件路径错误

ZLMediaKit默认配置文件位于conf/config.ini，如果启动时提示找不到配置文件，请检查：

• 确保程序运行目录包含conf文件夹
• 使用绝对路径指定配置文件：./MediaServer -c /path/to/config.ini

端口占用问题

当出现"bind failed"或"address already in use"错误时：

# 检查端口占用情况
netstat -tlnp | grep 1935  # RTMP默认端口
netstat -tlnp | grep 554   # RTSP默认端口
netstat -tlnp | grep 80    # HTTP默认端口

# 杀死占用进程
kill -9 <进程ID>

# 或者修改config.ini中的端口配置
[rtmp]
port=1936

🚀 编译与安装问题

依赖库缺失

编译时出现"找不到xxx库"错误，需要安装相关依赖：

# Ubuntu/Debian系统
sudo apt-get install libssl-dev libsrtp2-dev libffmpeg-dev

# CentOS/RHEL系统
sudo yum install openssl-devel libsrtp-devel ffmpeg-devel

Git子模块未初始化

编译前务必执行：

git submodule update --init

否则会出现ZLToolKit等依赖库缺失的错误。

📊 日志调试技巧

调整日志级别

在config.ini中修改日志级别获取更详细的调试信息：

[log]
# 日志级别(0-4): 0-调试 1-信息 2-警告 3-错误
level=0
# 日志文件路径，如果为空，日志输出至终端
logPath=./log

常见日志错误分析

1. 流无法播放：检查FFmpeg是否正常安装，编码格式是否支持
2. 推流失败：检查网络连接、鉴权配置和推流地址格式
3. 内存泄漏警告：关注jemalloc配置和内存使用情况

🌐 网络连接问题

RTSP/RTP传输模式问题

如果出现视频卡顿或花屏：

1. 尝试切换RTP传输模式：rtp over udp/tcp/http
2. 检查网络安全设置，确保UDP端口畅通
3. 调整config.ini中的网络缓冲区大小

WebRTC连接问题

WebRTC无法建立连接时：

• 检查TURN/STUN服务器配置
• 确认证书文件路径正确（默认使用./default.pem）
• 验证SDP协商过程是否正常

💾 资源与性能问题

高并发内存占用

当并发连接数较多时可能出现内存问题：

1. 调整config.ini中的线程池配置
2. 启用jemalloc内存管理：

[jemalloc]
enable=true

CPU占用过高

优化CPU使用率的建议：

1. 开启按需转协议功能，无人观看时不进行转码
2. 调整视频编码参数，降低编码复杂度
3. 使用硬件加速编码（如果支持）

🐳 Docker部署问题

容器内端口映射

Docker部署时确保端口映射正确：

docker run -id -p 1935:1935 -p 8080:80 -p 8443:443 \
-p 8554:554 -p 10000:10000 -p 10000:10000/udp \
zlmediakit/zlmediakit:master

配置文件挂载

自定义配置文件可通过volumes挂载：

docker run -v /path/to/custom.conf:/opt/media/conf/config.ini

🔧 高级调试技巧

GDB调试

对于复杂问题，可以使用GDB进行调试：

gdb ./MediaServer
# 设置断点
b main
b RtmpSession::onRecv
# 运行并调试
r -c config.ini

核心转储分析

配置系统生成core dump文件：

ulimit -c unlimited
echo "/tmp/core-%e-%p-%t" > /proc/sys/kernel/core_pattern

📋 常见错误代码速查表

错误现象	可能原因	解决方案
推流成功但无法播放	编码格式不支持	检查FFmpeg支持格式
延迟过高	网络抖动或缓冲区过大	调整缓存参数，检查网络
频繁断流	网络不稳定或超时设置过短	调整超时参数，检查网络质量
内存持续增长	内存泄漏或连接未释放	检查代码，调整资源释放策略

🎯 总结

ZLMediaKit作为一个功能强大的流媒体服务器框架，在正确配置和使用下能够提供稳定的服务。通过本文提供的故障排查指南，您可以快速定位和解决大多数常见问题。如遇复杂问题，建议查看详细日志、使用调试工具分析，或参考项目文档和社区讨论。

记住保持良好的配置备份习惯，定期更新到最新版本，以获得更好的性能和更多的功能支持。

【免费下载链接】ZLMediaKit 项目地址: https://gitcode.com/gh_mirrors/zlm/ZLMediaKit