ZLMediaKit在Windows下编译部署及GB28181接入实践

简介最新Windows下可用的ZLMediaKit流媒体服务器面向需要在Windows环境快速搭建推拉流服务或进行二次开发的工程师。该版本已实测可运行并正常播放省去自行编译与依赖配置的麻烦具备开箱即用特性适合本地调试、协议学习或集成到Windows项目中。压缩包共82个文件约74.45MB内含可执行程序与测试工具exe、开发所需的lib/dll库、Web管理界面js/html/css、配置与证书文件以及地图和样式等静态资源目录结构清楚。Web管理目录提供网页控制和播放页面方便直接查看服务状态内置的推流、拉流、WebRTC、H264推流、HTTP API、WebSocket、SRT等测试程序可帮助验证不同协议和接口同时保留API库与扩展接口适合对照源码二次开发减少环境排错时间。该版本已有982人学习/下载适合需要快速上手Windows流媒体服务的开发者参考。1. ZLMediaKit是什么为什么在Windows下折腾它最近在给一个监控项目做流媒体服务选型专门把ZLMediaKit在Windows下完整跑了一遍。标题里说的“最新”其实有两层意思一是目前master分支甚至最新发布tag对应的版本二是指在Windows这套工具链下能稳定编译运行、又能配合国标平台做接入的那一套配置方式。ZLMediaKit后面我直接叫ZLM是一个基于C11开发的高性能开源流媒体服务器和只做RTMP转发的老牌方案不一样它把RTSP、RTMP、HLS、HTTP-FLV、WebRTC这几种主流协议都收在一个进程里同时内置了GB28181所需的SIP信令处理和RTP收发能力。对做安防平台的人来说一条“摄像头GB28181接入、平台统一拉流、浏览器低延迟播放”的链路它一个人就能扛下来。我专门把Windows版拿出来写是因为多数流媒体服务器教程默认都是Linux但真正做方案验证、现场演示、甚至临时给客户出样机的时候很多人的主力电脑就是Windows。能在Windows上直接编译运行就不用开虚拟机或临时装双系统调试效率会明显高不少。1.1 项目定位与核心能力ZLM在开源社区里算是比较活跃的流媒体项目了。它的核心能力体现在两个层面协议接入层面它能作为GB28181的媒体接收端也能作为RTSP/RTMP的推流端和拉流端协议输出层面它能把一路输入流转成多种输出协议比如把摄像头的RTSP流转成HLS给浏览器播放或者转成HTTP-FLV给小程序播放。它和Nginx-RTMP这类方案的最大区别是Nginx-RTMP更像一个“管道”而ZLM更像一个“媒体中心”。比如你要做录像回看ZLM自带按时间点播的能力你要做鉴权或事件通知它有完整的Webhook接口你要做集群它还有多节点负载均衡的考虑。这些能力对实际项目的价值比单纯“能把流拉出来”要大得多。1.2 为什么不直接用Linux虚拟机很多朋友会问ZLM在Linux下部署多成熟干嘛还在Windows上硬折腾我的观点是虚拟机能跑通但不等于适合所有阶段。举个例子你在VMware里跑一个Ubuntu当服务器网络模式要调整、端口要映射、文件要共享调试时还要在两个系统之间来回切换。如果你正在做国产化平台联调客户的业务服务可能都跑在Windows上这时候你一定希望流媒体服务和业务进程同机部署把网络链路复杂度降到最低。另一个更现实的原因是调试体验。Windows上用Wireshark抓包看SIP信令、用VLC直接验证拉流地址、用浏览器打开管理页面这些操作比在Linux里来回拷贝数据包舒服太多了。对做集成和被集成的人来说节省的是整个联调周期。1.3 本文适合谁如果你正在做安防监控平台的二次开发或者项目里有摄像头国标接入、需要把视频流转换成浏览器可播放格式的需求又或者只是想在自己的Windows开发机上搭一套流媒体服务做概念验证这篇文章应该能帮你省不少时间。我会把从源码编译、配置、启动到对接WVP-GB28181的完整链路都写出来包括我踩过的坑和对应的解决办法。2. 编译前的准备工具链与依赖2.1 编译器选型MSVC还是MinGWWindows下编译ZLM首先面对的选项是用MSVC也就是Visual Studio的C编译器还是MinGW。两个方向都能跑通但我更推荐MSVC原因是社区里在Windows上维护构建脚本、上报问题时绝大多数都是以VS工程为准遇到坑更好搜而且后面你要用Visual Studio的调试器去看崩溃现场也方便。MinGW的优势是更接近Linux下GCC的编译习惯也能用但在第三方库的链接处理上会麻烦一些。所以除非你自己对MinGW已经非常熟否则直接上Visual Studio 2022就好社区版免费功能完全够用。2.2 安装CMake、Git和依赖库编译准备需要三块Visual Studio 2022、CMake、Git。Visual Studio安装时记得勾选“使用C的桌面开发”这个工作负载否则cl.exe和Windows SDK都不会装上。CMake建议装3.22以上版本并把安装路径下的bin目录加到系统PATH里。Git不用多说拉代码离不开安装Git for Windows即可。依赖库方面ZLM会用到OpenSSL、libsrtp等第三方库Windows下比较省事的做法是用vcpkg统一管理也可以直接参考项目文档里提到的预编译依赖方式。如果你只是做RTSP/RTMP转发测试编译核心功能时不一定非要FFmpeg全部装好但如果要转封装到HLS或做录像就尽量把FFmpeg相关的库也一并装上免得后面编译选项关掉后又后悔。2.3 环境配置检查装完工具之后建议先确认环境是否正常。在命令行里输入cmake --version和git --version能看到版本号就说明PATH没问题。用MSVC编译时不要直接打开一个普通的cmd窗口而是用“开始菜单里的x64 Native Tools Command Prompt for VS 2022”或者在普通终端里提前执行vcvars64.bat这样才能让cmake找到cl.exe。这一步我吃过亏第一次在普通PowerShell里直接执行cmake结果提示找不到MSVC折腾了十几分钟才发现是环境变量没加载。所以尽量从一开始就养成用开发者命令行窗口的习惯能少踩很多莫名其妙的坑。3. Windows下的源码编译全过程3.1 拉取源码与更新子模块ZLM的源码托管在GitHub上项目自身还把ZLToolKit等公共库作为子模块引入。直接执行git clone --recursive https://github.com/ZLMediaKit/ZLMediaKit.git cd ZLMediaKit git submodule update --init --recursive如果第一步已经拉过但没有带子模块后面这条update命令也能补齐不用重新clone。拉完代码后建议先看一下Release和tags选择一个发布版本切过去避免直接拿master开发分支踩到刚引入的新问题。我的做法是先确认当前master在最近一次发版之后没有大的breaking change再决定是用主干还是切到最新的稳定tag。3.2 用CMake生成Visual Studio工程在项目根目录下新建一个build目录然后执行cmake -S . -B build -G Visual Studio 17 2022 -A x64这条命令会生成一个build目录里面是完整的VS解决方案文件。如果你用的VS版本不同生成器的名称要对应调整比如VS 2019对应“Visual Studio 16 2019”。CMake会自动探测ZLToolKit和其他依赖如果提示缺少某个库回到第2步把对应依赖装上就行。需要留意的是CMake输出会显示很多编译选项比如ENABLE_WEBRTC、ENABLE_FFMPEG等默认值不一定是你想要的可以在生成时用-D参数显式指定比如cmake -S . -B build -G Visual Studio 17 2022 -A x64 -DENABLE_WEBRTCON -DENABLE_FFMPEGON3.3 正式编译与产物确认生成工程后直接命令行编译cmake --build build --config Release --parallel编译时间取决于机器一般几分钟到十几分钟不等。完成后到build\Release目录下会看到MediaServer.exe、MediaServer.pdb还有一些第三方DLL。如果某次只改了配置或源码的一小部分重新执行同一命令会做增量编译速度会快很多。我第一次编译时因为Visual Studio没装完整组件报了一堆“找不到windows.h”的错误后来补装SDK就好了。遇到这种“头文件缺失”的报错先把VS的C工作负载全部勾上再逐个确认依赖库比直接Google报错字符串更高效。提示build目录最好放在源码目录之外或单独隔离不然CMake生成的中间文件和源码文件混在一起后续维护会比较乱。4. 首次运行与基础配置4.1 目录结构与启动方式编译完后的build\Release目录就是运行目录。启动前先看看有没有config.ini如果没有从源码目录拷一份到运行目录。ZLM的可执行文件是MediaServer.exe直接在命令行执行MediaServer.exe此时终端会输出日志并把实际监听的端口打印出来。第一次启动时如果系统弹防火墙授权建议在专用网络里允许访问否则后面局域网内的设备就访问不到了。如果只想在开发机上本机测试可以先点取消后面需要时再手动加白名单。ZLM也支持指定配置目录MediaServer.exe -d D:\zlm\config这样可以把配置文件和程序分离升级时只替换exe和dll不必反复覆盖config.ini。我把这个方式用在持续集成环境里每次发版测试都可以一键切换不同配置非常方便。4.2 修改监听端口和Web管理界面默认情况下ZLM会占用80、443、554、1935、10000等常见端口。在Windows上这类端口很容易被其他服务或者系统服务占用比如IIS或者其他软件注册的HTTP监听器。进入config.ini建议先把HTTP端口改成一个不那么敏感的值比如8080RTSP端口如果被占用就改成10554RTMP端口改成11935。改完重启MediaServer看到日志里端口全部变成你设定的值再继续下一步。ZLM内置了一个Web管理页面默认地址就是刚刚配置的HTTP端口。浏览器访问http://127.0.0.1:8080能看到一个播放测试页面这里可以做MP4点播测试。如果页面能打开说明HTTP服务正常工作。实际使用中我建议把这个页面暴露在管理网段而不要直接放到公网因为它的定位是调试工具不是正式业务入口。4.3 用FFmpeg完成第一次推流测试接下来做一次真实推流验证。先准备一个测试视频文件然后用FFmpeg推RTMPffmpeg -re -i test.mp4 -c copy -f flv rtmp://127.0.0.1:11935/live/demo这里的live是应用名demo是流ID合起来完整流地址就是rtmp://127.0.0.1:11935/live/demo。推流成功后可以用三种方式去验证拉流RTMP播放rtmp://127.0.0.1:11935/live/demoHTTP-FLV播放http://127.0.0.1:8080/live/demo.flvHLS播放http://127.0.0.1:8080/live/demo/hls.m3u8用VLC打开这几个地址或者直接在浏览器里用页面自带的播放器测试只要能出画面说明ZLM在Windows下已经能正常工作了。第一次跑通的时候我建议把这几个地址都试一遍因为后面对接业务时会发现每种协议的使用场景不一样提前验证过能少很多排查时间。5. 对接WVP-GB28181更贴近实际项目5.1 WVP在体系里是什么WVP-GB28181大多时候大家简称WVP是一个基于Java的国标GB28181信令平台负责处理设备注册、云台控制、录像查询这类信令逻辑但它本身不承担媒体转发实际的音视频流媒体能力交给ZLM来做。简单理解WVP负责“怎么找到摄像头、怎么管理摄像头”ZLM负责“摄像头传来的流怎么转出去、分发给谁”。这两个项目在安防社区里基本是绑定出镜的所以如果你做国标平台一定会遇到ZLM和WVP对接。5.2 配置ZLM作为WVP的流媒体节点在WVP的管理后台里找到流媒体服务配置或服务器节点配置需要新增一个节点填上名称、IP地址、端口和接口密钥。这里的端口通常是ZLM的HTTP端口比如8080接口密钥就是之前config.ini里api段配置的secret两边必须一致。WVP会通过这个HTTP端口调用ZLM的RESTful API去创建RTP接收端口、查询流状态、关闭流等。配置好之后注意ZLM的RTP代理端口默认是10000。在WVP配置里也有对应的端口设置要和ZLM的[rtp_proxy]段保持一致。因为GB28181设备是通过SIP信令和RTP媒体通道工作的如果这两个端口没对上会出现设备能注册但拉流超时的情况。我建议在Windows防火墙里同时放行UDP 10000端口段并确保WVP所在的Java进程能访问到这个端口。5.3 国标设备接入时的坑我实际接入海康、大华设备时遇到过几个典型的坑。第一是SIP服务器ID和域WVP里配置的SIP国标编码要和设备上填的保持一致不能随便写。第二是Windows防火墙很多人在本机测试时设备是局域网里的摄像头如果MediaServer进程没有放行SIP信令能到WVP但媒体流回不来。第三是网络端口规划多个摄像头并发时10000端口是动态分流的如果并发很高要确认[rtp_proxy]的端口范围足够用必要时把范围扩大并在防火墙上放行一整段UDP端口。这章内容看着多其实核心就一句话先保证ZLM自己推流拉流没问题再考虑WVP的配置信令和媒体端口的对应关系必须逐项核对。我在现场联调时习惯先抓包确认SIP消息能来回再去看RTP端口通不通这样能把“信令问题”和“媒体问题”快速分开。6. 常见问题与排查技巧6.1 启动失败端口占用和DLL缺失启动时最常见的两个问题一个是端口被占用另一个是缺失动态库。端口被占用时日志会明确报bind failed直接根据日志里提示的端口号去查是谁占用的netstat -ano | findstr 1935 tasklist | findstr PID找到进程后要么关掉它要么修改config.ini换端口。缺失DLL表现为启动时弹窗提示找不到某个dll或者进程直接退出。这种情况通常是因为运行目录不完整把build\Release下的所有dll和exe都放在同一个目录或者把第三方库的bin目录加到PATH里就能解决。如果用了vcpkg还要确认编译时链接的库版本和运行时装的是否匹配Debug和Release混用也容易出问题。6.2 推流成功但拉不到流这个问题在Windows上大概率是防火墙阻拦了播放端的入站连接。虽然TCP端口如RTMP、HTTP默认在Windows防火墙里会有弹窗提醒但如果你之前点了“取消”后面就得手动添加规则。另外还要检查一下rtp_proxy的UDP端口是否放行GB28181设备注册不了、拉流超时很多都是UDP 10000端口不通导致的。如果同一台机器上本机能播放局域网其他机器不能播放先查防火墙和端口监听范围再去查路由和交换机不要上来就怀疑ZLM配置。用VLC的“工具-媒体信息”和Wireshark抓包区分信令和媒体是两个层面这个思路比重复改配置文件更重要。6.3 常见问题速查表现象可能原因解决思路启动即退出配置文件找不到把config.ini放到exe同目录或用-d指定端口bind失败其他程序占用80/554/1935换端口或结束占用进程本机能播局域网不能Windows防火墙放行MediaServer.exe入站规则GB28181设备注册不上SIP端口、域、ID不匹配和WVP配置逐项核对拉流超时rtp_proxy端口不通放行UDP端口段延迟越来越大播放端使用TCP拉流或解码慢优先排网络再考虑调整协议排查问题的时候不要一条一条试而是按照“进程是否活着-端口是否监听-本机是否可拉流-局域网是否可拉流-跨网段是否可拉流”这个顺序来几下就能定位到层级。7. 个人使用心得与进阶思路7.1 Windows下建议做进程守护ZLM在Windows上作为开发调试用很稳定但如果要当正式服务跑几天、几周直接开个命令行窗口显然不合适。可以用WinSW或者NSSM这类工具把MediaServer.exe注册成Windows服务设置开机自启、异常自动重启。我自己的习惯是修改config.ini后先在命令行前台跑一次确认日志没有报错再停掉手动启动的服务避免服务一直在崩溃循环里刷日志。注册成服务以后配合ZLM的api接口做健康检查也方便。你可以写一个定时任务去请求http://127.0.0.1:8080/index/api/getServerConfig如果返回值异常就触发告警或自动拉起服务。这是把Windows当“小服务器”用的常见姿势。7.2 可以扩展的方向ZLM在Windows下跑通只是第一步后续可以做的方向还挺多。比如用它的RESTful API和Webhook对接自己的业务管理后台或者把GB28181平台、ZLM、录像存储结合起来做一整套安防方案再比如研究它的WebRTC能力让浏览器直接低延迟播放摄像头画面省掉插件。如果对性能有更高要求可以考虑把流媒体服务部署到LinuxWindows则作为管理端使用两边并行互不冲突。从我的实际使用体验来说ZLM在Windows上的可用性已经相当不错编译门槛不高运行稳定性也够用。如果现在就缺一台方便调试的流媒体服务器照着上面的步骤一下午应该就能把它跑起来。本文还有配套的精品资源点击获取