WVP-PRO 是一个基于 GB28181 国标协议的免费开源视频监控平台很多初次接触视频监控开发的工程师都在找它的部署教程和通道录像配置方法。这篇文章会从实际项目出发把 WVP-PRO 的部署、国标设备接入、通道录像计划配置、录像回放验证和常见坑位排查完整讲透帮助你在自己的服务器上快速跑通一套可用的国标监控平台。如果你正在做智慧园区、明厨亮灶、雪亮工程或任何需要对接海康、大华等摄像头的国标平台项目这篇教程值得先收藏再慢慢看。读完你不仅知道怎么把通道录像开起来还能理解录像计划在数据库里是怎么存储的、为什么有时候录像回放会失败以及生产环境部署时应该注意哪些细节。1. 这篇文章真正要解决的问题很多刚接触视频监控开发的工程师第一次听到 WVP-PRO 这个项目时最大的疑惑是它和直接用海康 SDK 或者大华 SDK 有什么区别为什么大家都在推荐国标 GB28181 平台先给一个明确判断WVP-PRO 的价值不在于“录像存储”本身而在于“设备接入标准化”和“流媒体分发能力”。如果你只是需要在一台服务器上存几路摄像头录像随便用一个 NVR 或者 VideoIO 就够了。但当你要对接多种品牌设备、统一管理大量通道、对外提供 WebRTC 直播或者 HLS 回放时WVP-PRO 这种基于国标协议的平台优势才会体现出来。这篇文章要重点解决的问题包括七个方面WVP-PRO 到底是什么它和 GB28181 的关系。WVP-PRO 的完整部署过程包括数据库、Redis、配置文件以及国产化系统如 Deepin下的部署注意事项。国标设备如何注册接入 WVP-PRO如何正确填写 SIP 服务器参数。通道录像计划如何配置录像在数据库里如何存储、如何生效。录像回放如何验证为什么出流失败以及数据库录像记录与实际文件的对应关系。部署和录像配置过程中的常见问题排查思路。生产环境使用 WVP-PRO 时在资源评估、存储清理、安全加固方面有哪些最佳实践。如果你之前只用过 ONVIF 或者私有 SDK 接入摄像头这篇文章会帮助你建立一个关于国标监控平台的整体认知框架。如果你是做 Java 开发的看完之后你还可以直接阅读 WVP-PRO 的源码理解它如何基于 Spring Boot 构建一个完整的视频接入服务。2. WVP-PRO 与 GB28181 国标协议的核心概念在进入实操之前先把几个关键概念理清楚这样后面配置时你才知道每一项参数在做什么。2.1 GB28181 是什么GB28181 全称是《安全防范视频监控联网系统信息传输、交换、控制技术要求》是中国公共安全视频监控领域的国家标准。它定义了视频监控设备之间如何通过 SIP 协议进行注册、信令交互、媒体流传输和录像检索回放。可以这样理解GB28181 是摄像头和监控平台之间的“普通话”。以前海康用海康私有协议大华用大华私有协议平台方想同时接入两家设备就得分别写两套 SDK 适配代码。采用 GB28181 国标后只要设备端支持国标协议平台端也支持国标协议双方就能通过标准 SIP 信令进行设备注册、实时预览、录像查询和回放。这里需要重点区分两个概念GB28181 是信令和媒体传输协议NVR 是存储设备。很多人以为 WVP-PRO 会像 NVR 一样把所有录像都存到自己的磁盘里。实际上WVP-PRO 默认会推流到内置的 ZLMediaKit 流媒体服务ZLMediaKit 负责接收设备推上来的 RTP/PS 流并转封装成 RTMP、HLS、WebRTC 等协议。录像功能是在流媒体服务或者平台层面做文件记录与传统的 NVR 本地存储并不完全相同。2.2 WVP-PRO 在国标架构中的角色WVP-PRO 是开源的国标视频监控平台全称 Wireless Video Platform它具备几个核心模块信令服务模块基于 SIP 协议完成设备注册、心跳、目录查询、实时视频请求、录像检索和回放请求。媒体服务管理模块对接 ZLMediaKit负责通知 ZLMediaKit 启动或停止拉流以及处理流媒体分发。设备管理模块维护通道与设备的关联关系支持通道树、云台控制、录像计划等业务逻辑。业务接口模块对外提供 HTTP API 和 Web 管理界面方便上层业务系统集成。这里有一个新手最容易误解的地方WVP-PRO 本身不是一个完整的 NVR 替代品。它有录像功能但录像存储和管理能力相对薄弱更核心的价值是设备接入、流分发和 API 开放能力。它适合作为监控系统的“接入网关和业务调度中心”录像存储更推荐搭配 NVR 或者专门的存储服务。2.3 ZLMediaKit 和录像的关系WVP-PRO 默认集成 ZLMediaKit。ZLMediaKit 是一个高性能的开源流媒体服务支持 RTSP、RTMP、HLS、HTTP-FLV、WebRTC 多种协议。在 WVP-PRO 的架构中ZLMediaKit 承担三件事接收设备主动推上来的国标 PS 流。对外提供实时预览和录像回放的拉流服务。支持录制为 MP4 文件存放到配置的录像存储目录。从实际使用来看WVP-PRO 的“通道录像”配置本质是告诉 WVP-PRO 和 ZLMediaKit哪些通道需要进行录像、录像文件保存多长时间、以及是否允许通过平台进行按时间段检索回放。因此录像配置不只是打开一个开关还需要理解录像计划数据结构和媒体服务器的目录挂载关系。3. 环境准备与 WVP-PRO 部署WVP-PRO 的部署方式主要有三种Docker Compose 一键部署、手动部署 Java 服务和 ZLMediaKit、在国产化操作系统如 Deepin上单独编译部署。本节会以最常见的方式为例先说明环境要求再提供可复制的部署命令。3.1 环境要求组件版本要求说明操作系统CentOS 7.x / Ubuntu 18.04 / Deepin 20生产环境推荐 LinuxJDKJDK 8建议用 OpenJDK 8 或更高MavenMaven 3.6用于源码编译如果不使用 DockerMySQLMySQL 5.7存储设备和通道基础信息RedisRedis 5.0缓存流媒体订阅信息和信令状态ZLMediaKit与 WVP-PRO 版本匹配通常随 WVP-PRO 一起编译或通过 Docker 部署如果你使用 Docker Compose只需要安装 Docker 和 Docker Compose 插件即可WVP-PRO、ZLMediaKit、MySQL、Redis 都可以通过编排文件一键拉起。这里重点提醒一个版本匹配问题WVP-PRO 和 ZLMediaKit 的版本必须匹配。如果 ZLMediaKit 接口有变更而 WVP-PRO 还是旧版本会出现流媒体服务启动正常但无法拉流、无法录像的情况。优先推荐使用官方仓库提供的 Docker 镜像或者从官方 release 页面下载对应版本的二进制包不要随便混搭版本。3.2 使用 Docker Compose 一键部署如果只是测试和学习最快的方式是使用项目提供的docker-compose.yml。假设你已经安装好了 Docker执行以下步骤。第一步创建一个项目目录并进入mkdir -p /opt/wvp cd /opt/wvp第二步获取官方编排文件具体文件名以官方仓库为准也可以先在仓库 Release 页面下载完整压缩包。一个典型的编排文件包括以下四个服务version: 3.8 services: mysql: image: mysql:5.7 container_name: wvp-mysql environment: MYSQL_ROOT_PASSWORD: root123 MYSQL_DATABASE: wvp ports: - 3306:3306 volumes: - ./mysql-data:/var/lib/mysql command: --character-set-serverutf8mb4 --collation-serverutf8mb4_unicode_ci redis: image: redis:5.0 container_name: wvp-redis ports: - 6379:6379 zlmediakit: image: zlmediakit/zlmediakit:master container_name: wvp-zlmediakit network_mode: host volumes: - ./zlmediakit-data:/opt/media/bin/www - ./zlmediakit-record:/opt/media/bin/record wvp: image: wvp-pro/wvp-pro:latest container_name: wvp network_mode: host depends_on: - mysql - redis volumes: - ./wvp-data:/root/wvp environment: TZ: Asia/Shanghai这里解释几个关键配置点MySQL 的数据库名设置为wvpWVP-PRO 启动时会自动建表并初始化数据。使用network_mode: host是为了让 WVP-PRO 和 ZLMediaKit 通过127.0.0.1互相访问同时保证 SIP 默认端口 5060 和流媒体端口能够正常绑定。ZLMediaKit 的录像目录挂载到宿主机./zlmediakit-record下方便后续查看和管理录像文件。第三步启动服务docker-compose up -d第四步查看日志确认启动状态docker logs -f wvp如果看到类似SIP server started on port 5060和web server started on port 18080的日志说明 WVP-PRO 已经启动成功。需要提醒的是官方仓库的 Docker 镜像名称和编排参数可能随版本更新而调整以上 YAML 属于一种通用结构实际使用时以仓库README或docker-compose.yml中的最终版本为准。3.3 手动部署方式如果不使用 Docker或者需要在 Deepin 等只支持手动安装的系统上部署可以选择手动方式。大致步骤如下。先编译 WVP-PROgit clone https://github.com/648540858/wvp-GB28181-pro.git cd wvp-GB28181-pro mvn install -DskipTests编译完成后在target目录下会生成可执行 JAR 包。然后修改配置文件application.yml重点修改三部分内容MySQL 连接地址和账号密码。Redis 连接地址和密码如果 Redis 设置了密码。SIP 服务器 ID、域和 IP 地址。spring: datasource: url: jdbc:mysql://127.0.0.1:3306/wvp?useUnicodetruecharacterEncodingUTF8serverTimezoneAsia/Shanghai username: root password: root123 redis: host: 127.0.0.1 port: 6379 password: sip: id: 34020000002000000001 domain: 3402000000 ip: 192.168.1.100 port: 5060其中sip.id是 20 位国标编码sip.domain是 10 位国标域编码这两项必须和你的行政区划编码以及摄像头设备配置一致否则设备注册不上。然后启动 WVP-PROjava -jar target/wvp-pro.jar --spring.config.locationapplication.yml最后单独部署 ZLMediaKit。ZLMediaKit 的编译方式可以参考其官方 README编译完成后启动MediaServer并在 WVP-PRO 管理界面中配置 ZLMediaKit 的 IP 和端口即可。3.4 Deepin 系统下的部署注意点如果使用 Deepin 系统因为它是基于 Linux 的国产化桌面系统可能遇到两个问题Java 环境缺失、编译工具链不完整。建议先执行sudo apt update sudo apt install -y openjdk-8-jdk maven git如果编译 ZLMediaKit 时需要 CMake还要安装sudo apt install -y build-essential cmake libssl-dev libsdl-dev libavcodec-dev libavutil-dev ffmpegDeepin 下面还有一个常见坑防火墙默认可能没有放行 5060SIP和 10000-30000RTP 动态端口这些端口段。国标设备的媒体流通常是设备主动推流到平台媒体端口范围较大建议在测试时直接关闭防火墙或者显式放行对应端口段。4. 通道录像配置前置国标设备接入通道录像配置的前提是设备已经成功接入平台。如果设备没有注册成功后面所有录像配置都是空谈。这一节讲清楚如何完成设备接入以及如何判断设备是否注册成功。4.1 设备端 SIP 参数配置以常见的国标摄像头或者 NVR 为例在设备管理页面中找到“平台接入”或“GB28181”配置项需要填写以下内容参数填写内容说明SIP 服务器 ID34020000002000000001与 WVP-PRO 的 sip.id 一致SIP 服务器域3402000000与 WVP-PRO 的 sip.domain 一致SIP 服务器地址192.168.1.100运行 WVP-PRO 的服务器 IPSIP 服务器端口5060WVP-PRO 的 SIP 监听端口设备编号34020000001320000001设备自己的国标编码必须唯一密码自定义WVP-PRO 中也需要配置相同的密码这里要特别强调设备编号的编码规则不是随便填的。GB28181 的国标编码通常由中心编码8位、行业编码2位、类型编码2位、序号7位和校验位1位组成。如果你不熟悉编码规则最简单的做法是在 WVP-PRO 的添加设备页面里直接复制系统生成的示例编码然后到设备端使用一致编码和密码即可。4.2 WVP-PRO 端添加设备登录 WVP-PRO Web 管理界面进入“设备管理”菜单点击“添加设备”填写设备名称、设备编号、密码等信息保存后设备端发起 SIP 注册请求WVP-PRO 会校验编号和密码。注册成功后在设备管理列表中可以看到设备状态为“在线”。如果状态仍然显示“离线”请排查以下三个方向设备端填写的 SIP 服务器 IP 和端口是否能通使用telnet 192.168.1.100 5060测试。设备端和平台端的国标编号、域是否一致。有没有防火墙拦截 UDP 5060 端口SIP 默认使用 UDP 协议。4.3 通道同步与目录查询设备注册成功之后点击“同步通道”WVP-PRO 会周期性向设备发送目录查询请求设备返回通道列表包括通道编号、通道名称、通道状态等信息。同步完成后在“通道管理”里能看到所有摄像头通道。从实际项目经验来看通道同步偶尔会出现只有设备没有通道的情况尤其是部分第三方国标设备对国标目录查询的响应格式不够标准。遇到这种情况可以等待下一次自动目录查询也可以在设备端手动触发目录上报或者在 WVP-PRO 中点击“刷新通道”多次尝试。5. 通道录像计划配置全过程这是本文的核心部分。在设备成功接入并且通道已经同步到平台之后就可以开始配置录像了。WVP-PRO 的录像配置逻辑分为两层平台录像计划配置和存储资源验证。平台配置只是告诉系统哪些通道要在哪些时间段录像真正落盘则由 ZLMediaKit 完成的通道级录制任务负责。5.1 了解录像计划的基本模型进入 WVP-PRO 管理界面通常在“通道管理”或“录像管理”菜单中可以看到录像计划配置入口。计划模型一般由以下字段组成字段说明通道对应一个摄像头通道 ID计划类型全天录像、自定义时间段录像时间段开始时间和结束时间存储位置存储目录或存储策略标识如果界面中无法直接配置录像计划也可以通过 WVP-PRO 的数据库表直接插入计划数据。这里说一下常用表结构方便你理解后续的验证逻辑。-- 查看通道信息 SELECT device_id, channel_id, name, status FROM wvp_channel; -- 查看已有录像计划 SELECT id, channel_id, plan_type, start_time, end_time, status FROM wvp_record_plan;在 WVP-PRO 中通道录像计划的生效通常有几个前提条件该通道状态为“在线”。ZLMediaKit 服务运行正常且存储目录可写。设备支持国标录像回放协议或者平台侧启动录制任务。这里必须区分两类录像直接影响你后续的排查方向设备端录像NVR/SD卡录像WVP-PRO 通过国标信令向设备发起录像回放请求设备返回录像流。这种模式下录像文件不在 WVP-PRO 服务器上而在设备侧。平台端录像中心录像WVP-PRO 通知 ZLMediaKit 把实时流转存成 MP4 文件存储在平台服务器上。这种模式下你是否能回放取决于服务器的磁盘剩余空间和流媒体录制任务状态。本节重点讲平台端录像因为这是 WVP-PRO 最常用、也最容易配置出问题的模式。5.2 配置平台录像计划进入 WVP-PRO 的 Web 管理界面按照以下步骤操作。第一步点击“通道管理”找到需要录像的通道确认通道状态为“在线”。第二步点击该通道的“录像计划”按钮进入录像计划编辑页面。第三步选择计划类型“全天录像”点击保存。保存之后如果一切正常WVP-PRO 会向 ZLMediaKit 下发录制指令ZLMediaKit 开始将实时流转存为 MP4 文件。如果配置的是自定义时间段录像WVP-PRO 会启动定时任务在指定时间段内触发录制。这里有一个重要的细节录像计划保存成功不代表录制任务立即生效。部分版本中计划任务调度是按分钟轮询实现的保存后可能要等 1 分钟左右才会真正下发录制指令。验证时不要刚保存就去查文件等一会儿再看。如果你想跳过 Web 界面直接通过数据库配置一个全天录像计划可以参考以下 SQL 插入方式不同版本表名字段可能不同以实际版本为准INSERT INTO wvp_record_plan (channel_id, plan_type, start_time, end_time, status, create_time) VALUES (34020000001320000001, 1, 00:00:00, 23:59:59, 1, NOW());执行前先确认表和字段是否存在避免直接执行报错。插入数据后最好重启 WVP-PRO 或者触发一次录像计划刷新确保计划被加载。5.3 ZLMediaKit 的录像存储配置WVP-PRO 把录制任务下发给 ZLMediaKit 后实际录像文件由 ZLMediaKit 负责写入。因此必须提前确认 ZLMediaKit 的配置项# 在 ZLMediaKit 的 config.ini 中 [record] # 录制文件的保活时间秒 fileBufSize65536 # 录像存储根目录 appNamerecord # 录制器是否自动创建目录 enableVhostfalse容器部署时一般通过-v参数把宿主机目录挂载到 ZLMediaKit 的录像目录然后在 WVP-PRO 的 ZLMediaKit 配置中指定录像目录路径。手动部署时建议修改config.ini中的record.appName为可预期的目录名同时确保目录有写权限。这里举几个常见的目录结构/opt/media/bin/record/backend/34020000001320000001/2023-10-01/10-00-00-xx.mp4 /opt/media/bin/record/backend/34020000001320000001/2023-10-01/10-05-00-xx.mp4路径中的backend是 vhost 名34020000001320000001是通道编号后面的日期和时间是录像开始时间。理解了目录结构排查的时候就能快速找到对应文件。5.4 验证录像文件落盘配置录像计划后可以通过查看 ZLMediaKit 的日志或者直接查看录像目录来确认落盘情况。# 查看录像目录下新增文件 find /opt/media/bin/record -name *.mp4 -mmin -10 # 实时观看 ZLMediaKit 日志 docker logs -f wvp-zlmediakit如果文件正常生成说明平台端录像已经生效。如果目录中迟迟没有文件按以下顺序排查通道是否在线不在线的通道无法录制。WVP-PRO 是否成功向 ZLMediaKit 下发录制接口调用查看 WVP-PRO 日志中是否有startRecord关键词。ZLMediaKit 是否有写权限df -h查看磁盘空间是否充足。防火墙是否放行 ZLMediaKit 媒体端口。6. 录像回放验证与常见问题排查完成了实时录像的文件落盘验证之后还需要验证能否通过 WVP-PRO 进行录像回放。如果回放失败大概率是接口参数不正确或流媒体服务配置不对。6.1 回放验证流程在 WVP-PRO 管理界面的“通道管理”中点击“录像回放”选择日期和起止时间点击查询。如果存在录像文件回放列表会展示可用的录像片段点击播放后平台向设备或者本地录像文件发起回放请求最终通过 ZLMediaKit 返回 HLS 或 RTMP 地址给播放器。验证回放是否成功最直接的方法是拉取播放地址。在浏览器开发者工具中找到播放器请求的流地址例如http://192.168.1.100:18080/hls/backend/34020000001320000001/xxxx.m3u8在浏览器中打开该地址。如果返回 m3u8 内容说明回放出流正常。如果返回 404检查流 ID 和目录中的文件名是否一致。6.2 为什么录像回放失败下表列出最常见的回放失败原因以及对应的排查方法问题现象可能原因排查方式解决方案回放列表中无录像录像计划未生效查看 WVP-PRO 日志中是否有录制任务重新保存录像计划并等待轮询MP4 文件没有落盘ZLMediaKit 录制失败查看 ZLMediaKit 日志、磁盘空间修复存储路径权限回放点击后无画面设备端不响应 PLAY 请求检查信令日志和 SIP 交互改用平台端录像或升级设备固件回放了几秒就中断网络抖动或设备录像文件不完整查看 WVP-PRO 和 ZLMediaKit 日志更换为平台端录像优化网络HLS 地址 404流 ID 不匹配或频道离线对比文件名和回放地址核对通道编号和录像文件命名规则这里要强调一个很常见的坑国标设备的录像回放和平台端录像回放是两套完全不同的流程。如果平台端没有录像文件回放时会去请求设备端录像而很多廉价国标摄像头对国标录像回放协议支持不完整就会导致回放失败。更稳妥的做法是优先开启平台端录像没有特殊需求就别依赖设备端录像回放。6.3 用 FFmpeg 验证录像文件可读性有时候录像文件存在但播放黑屏或花屏这时候可以用 FFmpeg 检查文件是否完整ffprobe /opt/media/bin/record/backend/34020000001320000001/2023-10-01/10-00-00-xx.mp4如果输出中能看到视频流编码格式h264、分辨率、帧率等信息说明文件基本可读。如果提示moov atom not found说明文件写入中断可能是录制过程中服务器异常重启导致。7. 生产环境部署的最佳实践WVP-PRO 可以运行在单机环境但生产环境中更推荐按照以下实践来部署和运维。7.1 合理的组件拆分测试环境下WVP-PRO、ZLMediaKit、数据库、Redis 可以在同一台服务器上。生产环境建议将 WVP-PRO 和 ZLMediaKit 分离部署原因在于ZLMediaKit 的 CPU 和带宽消耗较高单独部署可以避免 WVP-PRO 的 Java 进程被媒体耗死。推荐部署方式一台 4 核 8G 服务器运行 WVP-PRO、MySQL、Redis。一台或多台 8 核 16G 服务器运行 ZLMediaKit配置足够的磁盘用于录像存储。前置 Nginx 做负载均衡和 HTTPS 代理对外只暴露 80/443 端口。7.2 存储容量评估视频监控录像的磁盘消耗非常高一定要在项目启动前估算清楚。码率与容量的对应关系可以用这个公式估算每小时录像大小GB 码率Mbps × 3600秒 ÷ 8 ÷ 1024举例说明如果摄像头主码流是 4Mbps一路通道一天的录像容量约为4 × 3600 / 8 / 1024 1.76 GB/小时 1.76 × 24 42.24 GB/天如果 10 个通道全部做全天录像一天的存储量就是 422.4GB一个月约 12.6TB。这个数字对一般服务器来说压力很大所以生产环境至少要支持循环覆盖由定时任务定期清理过期录像文件。在 ZLMediaKit 层面可以设置录制文件的切片时长比如按 5 分钟一个文件切片这样清理过期文件时更加灵活也方便回放定位到更精确的时间点。7.3 安全加固要点WVP-PRO 默认的管理界面不需要 HTTPS生产环境必须通过 Nginx 配置 HTTPS避免账号密码明文传输。WVP-PRO 的默认端口 18080 也不要直接暴露到公网建议只允许内网访问或者加上 IP 白名单。数据库和 Redis 的密码不能为空尤其是 Redis如果允许外网访问且没有密码很容易被写入恶意数据可能导致服务异常甚至被入侵。在生产环境Redis 建议只监听 127.0.0.1 或者内网网卡 IP。7.4 日志和监控WVP-PRO 运行时日志默认在控制台输出生产环境需要配置日志文件输出并定期清理。建议重点监控以下指标WVP-PRO 服务的存活状态。ZLMediaKit 的并发拉流数量和 CPU 占用。磁盘剩余空间低于阈值时自动清理过期录像。数据库连接池使用情况避免连接数过多导致服务卡死。有一个细节值得注意WVP-PRO 的日志中会包含 SIP 信令交互记录排查设备不注册或回放失败问题时会很有用。如果日志出现大量401 Unauthorized通常是设备密码校验不过如果出现Transaction timeout通常是设备响应慢或者网络抖动。8. 运维提醒与后续学习方向WVP-PRO 作为免费开源的国标监控平台功能成熟度相当高社区活跃度也不错。但考虑到它的定位是“接入平台 流媒体调度”而不是专业 NVR在实际项目中选择存储方案时一定要想清楚如果客户只需要简单的 NVR 录像功能私有协议或者成品 NVR 可能更稳定。如果需要大量异种品牌设备接入、统一平台管理、对外提供 API 能力WVP-PRO 更合适。对于想进一步阅读源码的 Java 开发者推荐从wvp-gb28181-pro仓库入手重点看sip包和media包。SIP 信令如何解析、设备目录如何维护、流媒体订阅如何管理这些代码逻辑对理解整个平台会很有帮助。建议部署时先搭一个最小环境用一台摄像头把“设备注册 → 通道同步 → 录像计划 → 文件落盘 → 回放验证”完整走通然后再上规模。这个最小闭环能帮你把配置链路中的每个环节都验证清楚比一次性接入几十路摄像头再排查要高效得多。