1. 项目缘起与目标定位最近在折腾一个需要处理实时音视频流的内部项目选型时把目光投向了 ZLMediaKit。这玩意儿在开源流媒体服务器圈子里名气不小主打高性能和低延迟支持 RTSP、RTMP、HLS、HTTP-FLV 等多种协议对于需要自建流媒体服务或者做二次开发的场景来说是个相当不错的起点。不过官方文档虽然详尽但更多是面向已经搭好环境的“下一步”操作。真正从零开始在一台干净的 CentOS 7.9 机器上把它编译出来并跑通基础测试这个过程里藏着不少需要自己趟过去的“坑”。这篇文章就是记录我这次从编译环境准备到功能验证的完整实操过程目标很明确给你一份能在 CentOS 7.9 上复现的、带避坑指南的“保姆级”操作手册。为什么是 CentOS 7.9虽然它已经停止维护但在很多企业内网、存量服务器上依然有广泛部署稳定性经过长期考验。在这个环境下成功编译和测试 ZLMediaKit意味着你能在大量现有服务器资源上快速部署一套可用的流媒体服务无需为升级系统大动干戈。整个过程涉及从系统依赖、编译工具链的配置到源码获取、编译参数调整最后到服务启动和基础功能测试。我会把每一步的操作意图、可能遇到的问题以及我的解决方案都掰开揉碎了讲清楚特别是那些官方文档可能一笔带过但实际操作中却会卡住你的细节。2. CentOS 7.9 基础环境准备与依赖库安装编译 ZLMediaKit 的第一步不是急着去git clone代码而是确保你的 CentOS 7.9 系统已经具备了所有必要的编译环境和依赖库。一台刚装好的最小化安装Minimal Install的 CentOS 7.9很多东西都是缺的。2.1 系统更新与基础开发工具链首先确保系统是最新状态并安装最核心的开发工具包。这能避免因为gcc、g、make等工具版本过低或缺失导致的编译错误。# 更新系统已有的软件包到最新版本 sudo yum update -y # 安装 EPEL 扩展仓库很多后续的依赖包需要从这里获取 sudo yum install -y epel-release # 安装开发工具组这包含了 gcc, g, make, autoconf 等一整套编译工具 sudo yum groupinstall -y Development Tools # 安装一些必要的工具和库 sudo yum install -y wget git cmake3 pkgconfig这里有个细节CentOS 7 默认的cmake版本是 2.8对于 ZLMediaKit 来说太老了。所以我们安装cmake3。但后续调用时命令是cmake3而不是cmake这点需要注意或者在系统里做个软链接ln -s /usr/bin/cmake3 /usr/local/bin/cmake来统一命令。2.2 安装 ZLMediaKit 的核心依赖库ZLMediaKit 的编译依赖几个关键的第三方库主要是 OpenSSL、libsrtp 和 ffmpeg。我们必须手动编译安装它们以确保版本的兼容性和功能的完整性。Yum 仓库里的版本往往不是太老就是功能不全。安装 OpenSSL 1.1.1ZLMediaKit 强烈推荐使用 OpenSSL 1.1.1 及以上版本以支持更安全的加密协议如 DTLS。CentOS 7.9 默认的 OpenSSL 是 1.0.2我们需要手动升级。# 安装编译 OpenSSL 所需的依赖 sudo yum install -y perl-IPC-Cmd # 下载 OpenSSL 1.1.1 源码 (以 1.1.1w 为例请检查官网获取最新稳定版) wget https://www.openssl.org/source/openssl-1.1.1w.tar.gz tar -zxvf openssl-1.1.1w.tar.gz cd openssl-1.1.1w # 配置、编译并安装到 /usr/local/openssl 目录避免覆盖系统自带的 OpenSSL ./config --prefix/usr/local/openssl --openssldir/usr/local/openssl shared zlib make -j$(nproc) # 使用多核编译加速 sudo make install # 将新安装的 OpenSSL 库路径添加到系统库搜索路径 echo /usr/local/openssl/lib | sudo tee /etc/ld.so.conf.d/openssl-1.1.1.conf sudo ldconfig # 验证新安装的 OpenSSL 版本 /usr/local/openssl/bin/openssl version这一步完成后你应该看到输出OpenSSL 1.1.1w ...。--prefix参数指定了安装目录将其与系统默认路径隔离是更安全稳妥的做法防止影响其他系统服务。安装 libsrtpSRTP安全实时传输协议用于对 RTP 流进行加密。ZLMediaKit 的 WebRTC 等功能需要它。# 下载 libsrtp 源码 git clone https://github.com/cisco/libsrtp.git cd libsrtp git checkout v2.5.0 # 选择一个稳定的版本如 2.5.0 # 配置并编译安装 ./configure --prefix/usr/local --enable-openssl make -j$(nproc) sudo make install sudo ldconfig--enable-openssl参数很重要它让 libsrtp 使用我们刚刚安装的 OpenSSL 1.1.1 进行加密操作。安装 FFmpegZLMediaKit 的转码、滤镜等功能依赖于 FFmpeg。我们需要编译一个包含常用编码器如 H.264的版本。# 安装 FFmpeg 编译依赖 sudo yum install -y yasm nasm libass-devel freetype-devel # 下载 FFmpeg 源码 (以 n6.0 为例) wget https://ffmpeg.org/releases/ffmpeg-6.0.tar.xz tar -xJf ffmpeg-6.0.tar.xz cd ffmpeg-6.0 # 配置编译选项。这里启用了一些常用编码器和协议支持。 ./configure --prefix/usr/local/ffmpeg \ --enable-gpl \ --enable-nonfree \ --enable-libx264 \ --enable-libx265 \ --enable-libvpx \ --enable-libmp3lame \ --enable-libfdk-aac \ --enable-openssl \ --extra-cflags-I/usr/local/openssl/include \ --extra-ldflags-L/usr/local/openssl/lib make -j$(nproc) sudo make install sudo ldconfig # 验证安装 /usr/local/ffmpeg/bin/ffmpeg -version注意--enable-libx264等选项需要你先安装对应的开发库如x264-devel。如果遇到报错可以先sudo yum install -y x264-devel等。为了简化流程上述配置命令是目标状态实际可能需要分步安装更多-devel包。一个更省事的办法是使用预编译的 FFmpeg但自编译能更好地控制功能和路径。2.3 解决潜在的依赖冲突与路径问题在安装完上述核心依赖后可能会遇到一些路径冲突。最常见的是系统自带的旧 OpenSSL 与我们新安装的版本冲突。我们需要确保编译 ZLMediaKit 时cmake能找到正确的库。可以设置环境变量来明确指定路径export OPENSSL_ROOT_DIR/usr/local/openssl export FFMPEG_ROOT/usr/local/ffmpeg你可以将这些行添加到~/.bashrc文件中然后执行source ~/.bashrc使其永久生效。这样在后续的编译步骤中CMake 就会优先在这些路径下查找依赖库。3. ZLMediaKit 源码获取与编译配置环境准备妥当后我们就可以开始处理 ZLMediaKit 本体了。3.1 克隆源码与初始化子模块# 克隆 ZLMediaKit 的主仓库 git clone --depth 1 https://github.com/ZLMediaKit/ZLMediaKit.git cd ZLMediaKit # 非常重要初始化并更新子模块很多核心代码如 mediakit在子模块里 git submodule update --init --recursive--depth 1只克隆最近一次提交速度更快。但切记git submodule update --init --recursive这一步绝对不能省略。我见过不止一个人因为漏了这一步编译时疯狂报“找不到头文件”的错误折腾半天才发现是子模块没拉下来。3.2 使用 CMake 生成构建系统进入源码目录我们创建一个独立的构建目录这是一种良好的“源代码外构建”实践保持源码树的干净。# 在 ZLMediaKit 源码根目录下 mkdir build cd build接下来是关键的 CMake 配置步骤。我们需要通过参数告诉 CMake 我们自定义的依赖库路径。# 使用 cmake3 进行配置 cmake3 .. \ -DCMAKE_BUILD_TYPERelease \ -DOPENSSL_ROOT_DIR/usr/local/openssl \ -DOPENSSL_LIBRARIES/usr/local/openssl/lib \ -DENABLE_WEBRTCON \ -DENABLE_SRTOFF \ # 根据需求开启SRT需要额外依赖 -DENABLE_RTPPROXYON \ -DENABLE_APION \ -DENABLE_FFMPEGON \ -DFFMPEG_ROOT/usr/local/ffmpeg参数解析-DCMAKE_BUILD_TYPERelease生成 Release发布版本编译器会进行优化去掉调试信息性能更好体积更小。如果是调试可以用Debug。-DOPENSSL_ROOT_DIR和-DOPENSSL_LIBRARIES明确指向我们手动安装的 OpenSSL 1.1.1。这是避免链接到系统旧版 OpenSSL 的关键。-DENABLE_WEBRTCON开启 WebRTC 支持。如果你需要浏览器无插件播放这个必须开。-DENABLE_FFMPEGON和-DFFMPEG_ROOT开启 FFmpeg 支持并指定路径用于转码等功能。其他如ENABLE_SRT,ENABLE_RTPPROXY,ENABLE_API等可以根据你的实际需求开关。初次测试建议保持默认或全部开启以验证完整功能。执行完cmake3命令后仔细查看终端输出。理想情况下最后几行应该会显示Configuring done和Generating done并且没有红色的错误ERROR信息。可能会有一些黄色的警告WARNING通常是关于找不到某些可选依赖如libsdptransform只要不是核心依赖一般不影响编译。3.3 编译源码并处理常见错误配置成功后就可以开始编译了。# 使用多核并行编译大幅缩短时间。$(nproc) 会自动获取你CPU的核心数。 make -j$(nproc)这个过程视机器性能可能需要几分钟到十几分钟。如果一切顺利你会在build目录下看到生成的可执行文件最主要的是MediaServer。编译过程中可能遇到的坑及解决方案错误找不到 OpenSSL 的EVP_*或SSL_*相关函数现象链接阶段报错提示undefined reference toEVP_...。原因CMake 仍然链接到了系统旧的 OpenSSL 库。解决首先确认cmake3命令中OPENSSL_ROOT_DIR参数是否正确。然后可以手动检查 CMake 缓存文件CMakeCache.txt搜索OPENSSL_开头的变量看其值是否指向/usr/local/openssl。如果不正确最彻底的方法是删除整个build目录重新执行cmake3配置命令。错误找不到libsrtp2现象CMake Error at CMakeLists.txt:xxx (find_package): Could not find a package configuration file provided by libsrtp2...原因libsrtp默认安装可能没有提供 CMake 所需的配置文件。解决ZLMediaKit 的 CMake 脚本其实自带了libsrtp的查找逻辑。通常只要libsrtp安装到了/usr/local下并且执行了sudo ldconfigCMake 就能通过find_library找到它。如果还是找不到可以尝试在cmake3命令中显式指定-DLIBSRTP2_ROOT/usr/local。错误FFmpeg 相关函数未定义现象链接时报告av_...等函数未定义。原因FFmpeg 路径未正确识别或版本不兼容。解决确保-DFFMPEG_ROOT参数正确指向了你安装 FFmpeg 的目录例如/usr/local/ffmpeg。同时检查该目录下的lib和include子目录是否存在且包含文件。如果编译成功最后你会看到类似[100%] Built target MediaServer的输出。此时在build/release/linux/Debug或build/release/linux/Release目录下取决于你的CMAKE_BUILD_TYPE就能找到MediaServer这个核心可执行文件了。4. 服务启动、基础功能测试与验证编译产出不是终点能跑起来、能用才是。接下来我们启动服务并进行最基本的推流、拉流测试。4.1 启动 MediaServer 服务首先将编译好的MediaServer复制到一个方便的位置并准备其配置文件。# 假设我们在 build 目录下 cd release/linux/Release/ # 或 Debug根据你的编译类型 cp MediaServer /usr/local/bin/ # 复制到系统路径方便全局调用 cp -r conf /etc/zlmediakit/ # 复制配置文件目录 # 切换到配置文件目录并启动服务默认前台运行方便看日志 cd /etc/zlmediakit/ MediaServer -c conf/config.ini -s conf/default.pem-c指定主配置文件路径。-s指定 SSL/TLS 证书路径用于 HTTPS、WSS 等。default.pem是自签名证书仅用于测试。如果启动成功你应该能在终端看到大量的日志输出最后会有类似MediaServer started!的信息并且服务不会退出。这表明 ZLMediaKit 的服务进程已经正常运行在监听配置文件默认是config.ini中指定的端口例如 80HTTP、443HTTPS、554RTSP、1935RTMP等。4.2 使用 FFmpeg 进行推流与拉流测试我们以最常用的 RTMP 协议为例进行一个完整的推流-服务转发-拉流测试链。第一步使用 FFmpeg 模拟一个视频源并向 ZLMediaKit 推送 RTMP 流。打开一个新的终端窗口执行以下命令# 使用 FFmpeg 生成一个测试图案color红色并以 H.264 编码通过 RTMP 推送到本地的 ZLMediaKit 服务器 /usr/local/ffmpeg/bin/ffmpeg -re -f lavfi -i testsrcsize640x480:rate30 -vcodec libx264 -preset ultrafast -tune zerolatency -f flv rtmp://127.0.0.1/live/teststream命令拆解-re以原始帧率读取输入模拟实时流。-f lavfi -i testsrc...使用lavfiLibavfilter虚拟设备生成一个 640x480、30fps 的测试彩条图案。-vcodec libx264使用 H.264 编码。-preset ultrafast -tune zerolatency为了极低延迟的测试选用最快的编码预设和零延迟调优。-f flv输出格式为 FLV这是 RTMP 常用的封装格式。rtmp://127.0.0.1/live/teststream推流地址。127.0.0.1是本地 IPlive是应用名Appteststream是流名Stream。如果推流成功这个终端会持续输出编码和发送的帧信息。同时在运行MediaServer的终端里你应该能看到类似[RTMP推流器] 推流成功的日志。第二步使用 FFplayFFmpeg 套件中的播放器从 ZLMediaKit 拉取 RTMP 流进行播放。再打开一个新的终端窗口执行# 从 RTMP 地址拉流并播放 /usr/local/ffmpeg/bin/ffplay rtmp://127.0.0.1/live/teststream如果一切正常会弹出一个播放窗口显示动态的彩条图案。这就完成了一个最基本的“推流-服务器转发-拉流”的闭环测试证明了 ZLMediaKit 的 RTMP 模块工作正常。第三步测试 HTTP-FLV 和 HLS 拉流。ZLMediaKit 的强大之处在于协议互转。我们推了 RTMP 流它自动生成了其他协议的拉流地址。你可以通过以下方式测试HTTP-FLV低延迟在浏览器需支持 Flash或使用 VLC 等播放器中打开http://你的服务器IP:80/live/teststream.flv。更现代的方式是使用flv.js等前端库在无插件的网页中播放。你可以用ffplay测试ffplay http://127.0.0.1/live/teststream.flv。HLS自适应码率兼容性好HLS 是切片传输会有一定延迟。拉流地址是http://你的服务器IP:80/live/teststream/hls.m3u8。你可以用ffplay或支持 HLS 的播放器如 VLC打开这个.m3u8文件地址。在MediaServer的日志中当你访问这些地址时会看到对应的协议访问日志。4.3 通过管理接口与 Web 界面查看状态ZLMediaKit 提供了一个 HTTP API 接口和一个简单的 Web 管理界面方便查看服务器状态和流信息。确保配置文件中[api]段是启用的默认是enable1并且secret有设置默认是035c73f7-bb6b-4889-a715-d9eb2d1925cc生产环境一定要改。获取服务器配置和版本信息curl http://127.0.0.1:80/index/api/getServerConfig?secret035c73f7-bb6b-4889-a715-d9eb2d1925cc获取当前所有的流列表curl http://127.0.0.1:80/index/api/getMediaList?secret035c73f7-bb6b-4889-a715-d9eb2d1925cc如果之前推流成功这个接口会返回teststream的相关信息。访问 Web 管理界面在浏览器中打开http://你的服务器IP:80/你会看到一个简单的页面上面有服务器状态、API 文档链接以及一个内置的播放器测试页面。你可以在这个测试页面输入live/teststream.flv来测试 HTTP-FLV 播放需要浏览器环境支持。5. 生产环境部署考量与性能调优建议通过上述步骤我们已经成功在 CentOS 7.9 上编译并验证了 ZLMediaKit 的基本功能。但如果要用于生产环境还有一些重要的步骤和考量。5.1 以系统服务方式运行前台运行MediaServer不适合生产环境。我们需要将其配置为 systemd 服务实现开机自启、故障重启和日志管理。创建服务文件/etc/systemd/system/zlmediakit.service[Unit] DescriptionZLMediaKit Media Server Afternetwork.target [Service] Typesimple Usernobody # 建议使用非root用户运行提升安全性 Groupnobody WorkingDirectory/etc/zlmediakit ExecStart/usr/local/bin/MediaServer -c /etc/zlmediakit/conf/config.ini -s /etc/zlmediakit/conf/default.pem Restarton-failure RestartSec5s # 资源限制可选 LimitNOFILE65536 LimitCOREinfinity [Install] WantedBymulti-user.target然后启用并启动服务sudo systemctl daemon-reload sudo systemctl enable zlmediakit sudo systemctl start zlmediakit sudo systemctl status zlmediakit # 查看状态日志可以通过journalctl -u zlmediakit -f来实时查看。5.2 配置文件关键项调优默认的config.ini配置文件适用于测试。生产环境需要根据实际负载调整。以下几个部分需要重点关注[general]段maxStreamWaitMS等待流注册的超时时间网络不好可适当调大。streamNoneReaderDelayMS流无观众时的延迟关闭时间节省资源。addMuteAudio是否在转协议时添加静音音频轨道确保某些播放器兼容性。resetWhenRePlay重复播放时是否重置时间戳。[shell]段可以启用enable1并设置maxReqSize和authSecret用于通过 API 执行服务器命令如重启某个协议。[protocol]各子段如[rtmp],[rtsp],[hls]等可以修改port端口号、sslportSSL端口号。务必检查并修改默认端口特别是如果服务器有公网 IP。[hls]段broadcastRecordTs是否广播录制 ts 文件deleteDelaySec切片文件删除延迟segNum和segRetain控制切片数量和保留策略直接影响存储空间和延迟。[record]段如果启用录制appName和fastStart等参数需要配置filePath要指向一个有足够空间和写入权限的目录。[http]段charSet字符集keepAliveSecond连接保持时间maxReqSize最大请求大小rootPath静态文件根目录Web管理界面文件在此。最重要的安全项修改[api]段的secret密钥使用一个你自己生成的复杂字符串不要使用默认值。5.3 性能监控与问题排查思路当服务运行起来后监控和排查是运维的日常。资源监控使用top、htop或nmon监控MediaServer进程的 CPU 和内存占用。流媒体服务通常是 I/O 和 CPU 密集型特别是开启转码时。网络监控使用iftop或nethogs查看网络带宽使用情况确认推流和拉流带宽是否符合预期。日志分析MediaServer的日志级别可以在配置文件中通过logLevel调整。遇到问题时可以临时调整为Debug或Trace级别获取更详细的信息。重点关注错误ERROR和警告WARN日志。流状态查询熟练使用前面提到的getMediaList、getMediaInfo等 API实时了解服务器上所有流的状态如发布者 IP、观看人数、产生时间、编码信息等。常见问题速查推流失败检查防火墙是否放行了对应的端口如 1935。检查推流地址的 AppName 和 StreamName 是否正确。查看服务器日志是否有鉴权失败等信息。拉流失败404确认流是否还存在通过getMediaListAPI。检查拉流地址的协议、AppName、StreamName 后缀如.flv,.m3u8是否正确。播放卡顿或延迟大检查服务器带宽是否充足。检查播放器设置如果是 HLS延迟本身较大。如果是 HTTP-FLV 还卡顿可能是网络抖动或服务器性能瓶颈。可以尝试降低推流码率或分辨率。内存缓慢增长可能是流没有正常关闭检查streamNoneReaderDelayMS设置是否合理或者是否存在播放器异常断开连接没有发送close事件的情况。5.4 关于 Docker 部署的补充虽然本文主题是编译但网络热词中提到了zlmediakit docker compose。对于生产环境使用 Docker 部署确实是更优雅和一致的选择。ZLMediaKit 官方提供了 Docker 镜像zlmediakit/zlmediakit。使用 Docker Compose 可以轻松定义服务、配置文件和数据卷。一个简单的docker-compose.yml示例如下version: 3 services: zlmediakit: image: zlmediakit/zlmediakit:latest container_name: zlmediakit restart: always ports: - 1935:1935 # RTMP - 80:80 # HTTP/HTTP-FLV/HLS/API - 443:443 # HTTPS/WebSocket-FLV - 554:554 # RTSP - 10000:10000/tcp # RTP over TCP - 10000:10000/udp # RTP over UDP volumes: - ./conf:/opt/zlmediakit/conf # 挂载自定义配置文件 - ./logs:/opt/zlmediakit/logs # 挂载日志目录 - ./record:/opt/zlmediakit/record # 挂载录制文件目录 environment: - TZAsia/Shanghai # 设置时区使用 Docker 的好处是环境隔离、依赖统一、升级回滚方便。你需要做的就是把编译环节中手动调整的config.ini配置文件放到宿主机的./conf目录下然后docker-compose up -d即可。这相当于把编译的复杂性交给了镜像维护者你只需要关注配置和运行。对于快速部署和维护来说这是更推荐的方式。当然理解本文的编译过程能让你在需要自定义依赖、深度定制或排查底层问题时更有底气。