Windows下ZLMediaKit编译部署与GB28181联调实战指南

简介ZLMediaKit是一套支持RTSP、RTMP、HLS、HTTP-FLV等协议的高性能流媒体服务框架常用于直播、安防、物联网等场景这份资源提供Windows系统下已编译好的可运行版本基于2024年7月的源码构建并经过播放测试验证。使用者无需安装复杂的编译工具链和依赖库解压后即可部署主服务并调用相关接口。压缩包共82个文件总大小74.45MB主要包含exe可执行程序、lib静态库、dll动态库和JavaScript脚本另有HTML/CSS页面用于Web管理界面以及pem证书、ini配置文件、Markdown说明等辅助文件包内自带主服务程序和多个测试工具可辅助完成推流、拉流、RTSP/RTMP协议互通、WebSocket连接等常见场景的验证。目前已有982人学习或下载该资源适合流媒体领域的中级开发者快速搭建实验环境、理解ZLMediaKit的基本用法并为进一步二次开发提供可直接调用的现成组件。 先交代一下背景ZLMediaKit 是一个高性能流媒体服务框架支持 RTSP、RTMP、HTTP-FLV、HLS、SRT、WebSocket-FLV 和 GB28181在安防、直播、物联网等领域用得非常多。很多同行默认这种 C 写的服务只适合扔在 Linux 服务器上Windows 上就算能编也全是坑。其实从项目正式支持 Windows 构建开始这套说法就已经过时了。尤其是做本地联调、国标平台对接、给客户现场演示的场景直接在 Windows 上跑一个最新版的 ZLMediaKit省掉了来回传包、临时借服务器的一大堆麻烦。这篇文章我就把当前 Windows 下可用的几种方案、完整编译过程、配置细节和踩坑记录都整理出来给正在折腾的人做参考。1. Windows 上跑 ZLMediaKit到底能做什么值得折腾吗先把这个问题的价值说清楚很多人一上来就问“Windows 能跑吗”其实真正该问的是“在 Windows 上跑能给我省多少事”。你是一个做音视频或者安防平台开发的工程师本地改代码、调接口、看日志是家常便饭。如果每次验证一个流媒体功能都要把代码推到 Linux 服务器上编译再通过远程终端看日志整个迭代节奏会被拖得很慢。Windows 下直接跑 ZLMediaKit你可以在 Visual Studio 里打断点跟在 IDE 里观察收到 RTP 包、推流握手、回调触发这些细节日志就在当前控制台窗口里刷比远程看服务器日志舒服太多了。ZLMediaKit 本身不是一个简单的“拉流工具”它更像一个可二次开发的流媒体网关。你可以在它的基础上做鉴权、转封装、协议转换、事件回调甚至自己接 AI 分析模块。Windows 版本同样支持这套 API 机制所以在 Windows 上把它跑通意味着你本地就能完成大部分业务层开发最后再部署到 Linux 生产环境时代码几乎不用改。常见的应用场景包括这些安防项目里对接 GB28181 国标摄像头先用 Windows 本机做 WVP-GB28181 平台和 ZLMediaKit 的联调。直播场景里做本地推拉流压力测试一台 Windows 电脑同时跑推流端和 ZLMediaKit。嵌入式或者边缘设备项目先用 Windows 上位机验证协议流程再移植到 Linux 目标板。给客户做 POC 演示带一台 Windows 笔记本就能现场起一个流媒体服务不需要临时部署服务器。一句话总结就是Linux 跑生产Windows 跑开发。两边都要用而且 Windows 这边用好了效率翻倍。2. 先选路线源码编译、Docker 容器还是 WSL2 套壳在 Windows 上把 ZLMediaKit 用起来有两条完全不同的技术路线。选错了会走很多弯路所以先做对比再根据自己的场景选。路线一源码编译。这是最正规的方式用 Visual Studio 的 CMake 工具链直接编出 MediaServer.exe。优点是能调试、能改代码、能长期维护发布的时候也掌握全部依赖。缺点是首次配置环境稍微麻烦需要装 Visual Studio 的 C 工作负载、CMake、Git而且编译时间取决于机器性能。路线二Docker Desktop 里跑 Linux 镜像。官方有现成的 zlmediakit 镜像拉下来直接启动端口映射好就能用。优点是上手快不用装一堆编译工具环境干净换版本也方便。缺点是你没法在 Windows 里直接打断点调试镜像内的二进制而且 Docker Desktop 本质是靠 WSL2 虚拟机跑 Linux 容器网络模型和你直觉里“本机上的服务”不太一样。路线三直接在 WSL2 里装 Linux 发行版然后在 WSL 里按 Linux 方式编译或者用发行版软件包。这个路线本质上是接近 Linux 的开发方式优点是和生产环境一致性高缺点是要额外维护一套 WSL 环境和 Linux 工具链而且 Windows 和 Linux 文件系统之间频繁跨目录操作会有效率损失。我把三条路的对比列成了一张表方案上手成本调试能力适合场景VS源码编译中强可断点二次开发、本地调试、长期维护Docker Desktop镜像低弱看日志为主快速跑通、临时演示、版本切换WSL2内运行中高中依赖gdb等模拟生产环境、习惯Linux操作我个人的选择是日常开发用源码编译需要验证部署或者做版本对比的时候用 Docker 镜像WSL2 只在调试跨平台编译问题的时候才开。这里多提醒一句很多人在 Docker Desktop 里跑 ZLMediaKit然后发现 WVP-GB28181 连不上多半是容器 IP 和映射端口的问题。后面第 5 节我会单独说这个坑。3. Visual Studio 编译最新源码的完整过程如果决定走源码编译下面这套流程是我目前验证下来最顺的。前提是 Windows 10 或 Windows 1164 位系统。3.1 准备编译环境需要装的东西有四个Visual Studio 2022、Git、CMake以及 VS 里的“使用 C 的桌面开发”工作负载。Visual Studio 的安装器里勾选“使用 C 的桌面开发”时默认会带上 MSVC 编译器和 Windows SDK这两个是编译 C 项目的核心。CMake 可以在 VS 安装器里勾选也可以单独去官网下载装完记得把路径加到系统 PATH 里。Git 就不多说了一般搞开发的机器上都有。环境装好之后最好用“x64 Native Tools Command Prompt for VS 2022”或者“Developer PowerShell for VS 2022”打开终端。为什么要用这个而不是普通 PowerShell因为它会把 MSVC 的编译环境变量都设置好后面跑 CMake 和编译命令的时候不会出现找不到 cl.exe 或者环境不匹配的问题。3.2 拉取源码并编译在终端里执行这几条命令git clone --depth 1 https://github.com/ZLMediaKit/ZLMediaKit.git cd ZLMediaKit mkdir -p build cd build cmake .. -G Visual Studio 17 2022 -A x64 cmake --build . --config Release --parallel关于 -G 参数不同版本的 VS 对应的字符串不同VS2019 用Visual Studio 16 2019VS2022 用Visual Studio 17 2022。-A x64 是显式指定生成 64 位程序这个不能漏32 位版本在高并发流媒体场景下性能和内存寻址都吃亏。第一次执行 cmake 的时候会联网拉取依赖库像 OpenSSL、libsrtp 这些ZLMediaKit 的 CMake 脚本会自动处理。如果网络环境不好导致第三方库下载失败多试几次或者检查 DNS 和代理设置确保能正常访问 GitHub 及常用的开源软件源就行。编译时间一般在几分钟到十几分钟不等取决于 CPU 性能。编译完成后在 build 目录下找到 MediaServer.exe 和一堆 dll 文件。注意这些 dll 一个都不能少后面发布的时候也需要一起拷贝。ZLMediaKit 的构建输出目录在不同版本里略有差异有的在build/Release有的在build/bin以实际生成位置为准。3.3 最简单的方式直接用官方预编译包如果不想自己编译可以先去项目的 GitHub Releases 页面看一眼发现官方发布了带 Windows 二进制包的版本直接下载解压就能用。不过这里有个现实问题并非每个 release 都会附带 Windows 包而且你需要的可能是某个特定分支的最新特性。所以我把源码编译放在前面讲因为这是最稳定、永远可用的方式。下载到压缩包之后同样只需要关注 MediaServer.exe 和同目录的 dll、配置文件模板。先不要急着改配置直接双击运行一次让程序在当前目录生成默认的 config.ini再关掉去改这样最不容易出错。4. 启动配置与 Windows 防火墙、端口占用实战编译产物拿到手运行只是第一步。真正让人头疼的是配置、端口和防火墙。4.1 config.ini 里的关键项MediaServer.exe 第一次运行时会在当前工作目录生成 config.ini。打开这个文件重点看几个段落[rtsp] port554 [rtmp] port1935 [http] port8080 [api] secret035c73f7-bb6b-4889-a715-d9eb2d1925ccRTSP 默认端口是 554RTMP 是 1935HTTP API 和 HTTP-FLV 服务共用 8080。这个 secret 是调用 ZLMediaKit HTTP API 的密钥后面接 WVP 平台的时候必须保持一致这个我会在第 5 节详细说。如果本机 554 端口已经被其他软件占了比如某些播放器或者旧的流媒体服务启动时会有端口绑定失败报错。排查方法是在命令行执行netstat -ano | findstr :554看到占用进程的 PID 后去任务管理器确认是哪个程序然后改 ZLMediaKit 的端口或者停掉占用进程。不要一上来就想着杀进程先确认是不是系统服务。4.2 Windows 防火墙放行规则这是 Windows 上跑流媒体服务和 Linux 最大的区别。Linux 上只要没有 iptables 拦截端口默认对局域网开放Windows 上防火墙默认弹窗问你要不要允许如果当时点了取消后面摄像头或者其他设备就连不上。如果你用的是编译出来的 MediaServer.exe第一次启动一般会弹 Windows 安全警报窗口。这里记得勾选“专用网络”不要勾“公用网络”。如果没弹窗或者你想直接在命令行静默放行可以用管理员权限的 PowerShell 执行netsh advfirewall firewall add rule nameZLMediaKit-TCP dirin actionallow protocolTCP localport554,1935,8080 netsh advfirewall firewall add rule nameZLMediaKit-UDP dirin actionallow protocolUDP localport5060,10000-10200后面那条 UDP 规则是为 GB28181 通信用准备的5060 是 SIP 信令端口10000 到 10200 是 RTP 流媒体收流端口范围。如果你只做直播推拉流TCP 规则就够了。4.3 启动和联调测试启动服务的方式有几种最简单的是直接双击 MediaServer.exe。如果想在后台运行不在桌面留窗口可以用命令start /b MediaServer.exe -c config.ini -d-d参数表示以守护模式启动-c指定配置文件路径。这样 cmd 窗口关掉以后服务也会继续跑适合临时挂机验证。服务跑起来以后先用 FFmpeg 推一路流测试ffmpeg -re -i test.mp4 -c copy -f flv rtmp://127.0.0.1:1935/live/test然后在一个能播流媒体地址的播放器里试HTTP-FLV 地址http://127.0.0.1:8080/live/test.live.flvRTSP 地址rtsp://127.0.0.1:554/live/testHLS 地址http://127.0.0.1:8080/live/test/hls.m3u8能同时出画面和声音就说明 Windows 下的基础服务已经完全可用了。5. 国标实战让 WVP-GB28181 调用本机 ZLMediaKit如果你是从安防行业搜索“wvp-gb28181 zlmediakit 编译安装”这些词过来的那这一节才是你真正要的东西。WVP-GB28181 是一个基于 Spring Boot 的国标视频平台负责对接 GB28181 摄像头、管理设备、处理信令而真正的流媒体传输和转发是交给 ZLMediaKit 来做的。这两个东西一个管“控制”一个管“媒体”必须配合起来才能形成一个完整的国标平台。5.1 WVP 侧需要改的核心配置WVP 启动之前要修改配置文件里的 media 相关项media: id: ZLMediaKit ip: 127.0.0.1 port: 8080 secret: 035c73f7-bb6b-4889-a715-d9eb2d1925cc这里有几个关键点ip和port是 WVP 调用 ZLMediaKit HTTP API 的地址8080 就是上面 config.ini 里 http.port 那个端口。secret必须和 ZLMediaKit 的 config.ini 中[api] secret完全一致。id是 WVP 用来标识这个流媒体节点的名字起个好认的名字就行。验证 ZLMediaKit 的 API 是否通可以直接在浏览器里访问http://127.0.0.1:8080/index/api/version这个地址返回 JSON 格式的版本信息就表示 API 服务正常。如果打不开检查 ZLMediaKit 是否在运行以及防火墙是否放行了 8080。5.2 摄像头注册与 RTP 收流地址问题WVP 启动以后在平台里添加国标设备填上 SIP 服务器地址和端口。这里的 IP 有一个细节如果摄像头和 WVP、ZLMediaKit 都在同一台 Windows 机器上做演示IP 填 127.0.0.1 就行如果摄像头是局域网里的真实设备那 SIP 服务器地址要填 Windows 主机的局域网 IP不能继续用 127.0.0.1。为什么因为摄像头向平台注册时WVP 会通过信令告诉摄像头往哪个 IP 推流。如果你在 WVP 里配置的是 127.0.0.1摄像头那边会理解为它自己本机RTP 流根本到不了你的 Windows 机器。这个问题在实际部署中非常常见排查了半小时端口、防火墙最后发现是 IP 配置问题。除了 WVP 配置还需要确认 Windows 防火墙放行 UDP 5060 和 UDP 10000 到 10200 的范围这两个是国标设备注册和媒体流传输的核心。如果摄像头显示在线但拉流超时优先查 UDP 规则。5.3 与 Redis、MySQL 的联动WVP 本身依赖 MySQL 和 Redis。MySQL 在 Windows 上装一个社区版就行Redis 在 Windows 上可以用官方的 Windows 移植版也可以装一个 WSL 里的 Redis或者直接用 Docker 起一个 Redis 容器。这个环节的坑在于如果 Redis 跑在 Docker 或者 WSL 里WVP 配置的连接地址就不能写 127.0.0.1 的概念要写 Docker 容器的映射端口对应的宿主地址。很多人在这里搞混导致 WVP 启动后一直报 Redis 连接不上。我的建议是本地联调时要么 Redis 原生跑在 Windows 上要么就用 Docker 映射到宿主机的 6379这样 WVP 配置写 127.0.0.1 最省事。6. 实战中我踩过的几个 Windows 专属的坑这一节是纯经验全部来自实际操作中踩过之后才总结出来的。每一个都值得记下来。6.1 只拷贝 exe 文件不拷贝 dll导致其他机器跑不起来这个问题我在编译完成的第二天就踩了。当时为了图干净只把 MediaServer.exe 复制到另一台电脑结果双击报错找不到 libcrypto-x64.dll。ZLMediaKit 在 Windows 下编译出来的运行依赖包括 OpenSSL、libsrtp 等多个动态库发布的时候必须把 exe 和所有 dll 放在同一个目录下整个目录一起打包。最稳妥的办法是直接把编译输出目录压缩而不是自己挑文件。6.2 资源管理器拖放和拷贝大目录的问题Windows 下如果要拷贝大量录像文件到媒体目录经常遇到 Explorer 拖放卡死甚至报“资源管理器已停止工作”的情况。这个不是 ZLMediaKit 的问题是资源管理器本身的通病文件一多、路径一深Explorer 的响应就很容易崩。解决办法是用命令行替代图形界面。拷贝目录的时候用 robocopy比如robocopy E:\media C:\media /E /COPY:DATrobocopy 即使遇到某个文件被占用也能跳过继续拷贝而且不会像资源管理器一样在一个文件上卡死整个窗口。有这个习惯之后我在 Windows 上处理流媒体文件目录的稳定性高了很多。6.3 Docker 容器 IP 在 wsl --update 之后漂移如果你用 Docker Desktop 跑 ZLMediaKit并且把 WVP 的 media ip 填成了容器的 IP那么一旦 Windows 子系统更新或者 Docker Desktop 重启容器 IP 可能就变了。这个坑特别隐蔽因为表面上看服务都在跑WVP 却怎么都连不上 ZLMediaKit。解决思路有两个。一个是在启动容器的时候把端口映射到宿主机然后用 127.0.0.1 作为 WVP 里的 media ip这样容器内部 IP 怎么变都不受影响。另一个是每次重启后通过 docker inspect 查看新的 IP把 WVP 配置改掉。前者更适合日常联调后者适合需要真实网络隔离的场景。6.4 hosts 文件对回调地址的影响在一些复杂的网络环境里WVP 回调 ZLMediaKit 的地址可能会走系统域名解析。如果遇到“本机能访问、外部访问正常但平台回调就是失败”的情况可以打开C:\Windows\System32\drivers\etc\hosts文件查看有没有历史遗留的 localhost 映射或者旧的 IP 别名记录。大部分时候 hosts 文件不需要动但如果你之前手贱加过什么自定义域名映射或者某些软件改过就会导致 WVP 访问 ZLMediaKit 的时候把请求发到错误地址上。排查思路是先把 hosts 里可疑的本地映射注释掉再试一次回调。这个文件我也在排查中看过不少次虽然不是最常见的坑但一旦碰上不查 hosts 很难找到原因。7. 最后的实践建议ZLMediaKit 在 Windows 下能做的事情远比“能编出来跑一下”多得多。无论是做 GB28181 国标平台的本机联调还是做直播流媒体的功能验证源码编译这条路最值得花一点时间走通。走通之后你会发现在 Windows 上开发流媒体功能并没有那么痛苦反而因为调试方便而效率提升。顺着这个思路后续还可以尝试在 Windows 上跑更多流媒体周边组件比如把 FFmpeg、SRS、Nginx-RTMP 也纳入本地测试环境再通过 WVP 把设备和平台串起来就能模拟出一套完整的安防或直播系统。Windows 和 Linux 的部署差异主要在系统服务和防火墙层面业务流程代码几乎可以完全复用。这也是我推荐大家优先搞定 Windows 本地环境的原因省下来的时间都是实打实的开发和调试时间。本文还有配套的精品资源点击获取