ONVIF协议接入
简介
ONVIF（Open Network Video Interface Forum）是网络摄像机（IPC）行业最通用的互操作标准之一，联犀平台通过 onvif 协议将符合 ONVIF 标准的网络摄像机接入音视频模块，实现统一纳管、实时预览、云台控制与录像回放。
与 GB28181 国标走 SIP 注册的接入方式不同，ONVIF 摄像机采用设备发现方式接入：平台先在「音视频 - 设备管理 / 设备发现」中按摄像机 IP、端口、用户名、密码完成添加，再在 IoT 设备维度绑定已有音视频设备通道即可完成关联，无需在摄像机侧做任何国标配置。
核心能力：绑定后设备接入页统一提供 WS-FLV / HTTP-FLV 实时预览，ONVIF 设备额外支持 PTZ 云台控制（方向 / 变倍 / 预置位） 与 历史回放（录像日历 → 录像列表 → 播放）。
应用场景
- 标准 ONVIF 摄像机接入：符合 ONVIF 规范的 IPC 设备，按设备发现方式接入音视频模块
- 设备维度绑定：IoT 设备与已有 ONVIF 音视频设备通道建立绑定关系，一个 IoT 设备对应一路视频通道
- 实时预览：绑定后经 WS-FLV / HTTP-FLV 在浏览器观看实时画面（依赖流媒体服务器 ZLMediaKit 收流）
- PTZ 云台控制：支持八方向转动、停止、变倍缩放、云台速度调节，以及预置位的设置 / 调用 / 删除
- 历史回放：按月份查询录像日历，选择有录像的日期查看录像列表并在线回放
能力边界：ONVIF 通道仅支持「绑定已有音视频设备」方式接入，不支持填写流地址自动建档（该能力仅 RTSP/RTMP 协议提供）。
前置条件
- 音视频服务已部署：
allinone镜像已包含音视频服务（avsvr）与流媒体服务器 ZLMediaKit，部署时启用音视频功能（avDocker.yaml配置Enable: true） - 网络可达：ONVIF 摄像机与平台流媒体服务网络互通；浏览器播放 FLV 需能访问 ZLMediaKit 的 HTTP/WebSocket 入口（见部署说明）
- 设备凭据：ONVIF 摄像机的 IP、端口（默认 80）、用户名、密码
- 产品已创建：创建产品时主协议选择「音视频」分组下的
ONVIF 协议接入
产品配置
1. 创建产品
创建产品时，「主协议」下拉选择「音视频」分组下的 ONVIF 协议接入（同分组还提供 GB28181 国标视频接入、RTSP/RTMP 拉流接入）：
2. 产品接入说明
进入产品详情「设备接入」Tab，平台按协议类型渲染对应的接入说明页。ONVIF 产品页展示接入指引：
- 先在「音视频 - 设备管理 / 设备发现」中添加 ONVIF 设备（输入摄像机 IP、端口、用户名、密码完成接入）；
- 回到设备接入页，在「绑定已有音视频设备」中选中该 ONVIF 设备，再选择对应通道完成绑定；
- 绑定成功后即可进行 WS-FLV / HTTP-FLV 实时预览、云台（PTZ）控制与历史回放。
产品页展示的为协议接入说明（以配置页实际内容为准），不进行设备绑定操作；绑定在设备维度的「设备接入」页完成。
设备接入
1. 在音视频模块添加 ONVIF 设备
进入「音视频 - 设备管理 / 设备发现」，按摄像机信息添加 ONVIF 设备，添加成功后设备出现在音视频设备列表中。
2. 创建设备并绑定通道
在产品下创建 IoT 设备，进入设备详情「设备接入」Tab，页面展示当前绑定状态。未绑定时提供「绑定已有音视频设备」卡片：
- 音视频设备：下拉选择已添加的 ONVIF 设备（设备列表按协议类型过滤）
- 通道：选中设备后自动加载其通道列表，选择要绑定的一路通道
- 点击「确认绑定」，绑定成功后页面刷新为已绑定视图
3. 解绑
已绑定页面顶部展示绑定信息（音视频设备、通道、传输协议、通道 ID），提供「解绑」按钮，二次确认后解除绑定关系；解绑后需重新绑定才能预览。
绑定后能力
绑定成功后，设备接入页上方展示绑定信息，下方按「实时预览」「历史回放」两个页签组织：「实时预览」页签为左右分栏布局——左侧为视频画面，右侧为「云台控制（PTZ）」面板。
实时预览（WS-FLV / HTTP-FLV）
页面提供「开始预览 / 停止预览」按钮，默认通过 WS-FLV（低延迟）与流媒体服务器完成媒体交互，观看实时画面；环境不支持 WebSocket 时自动回退到 HTTP-FLV，浏览器不支持 MSE 或播放器组件不可用时自动降级为 HLS 兜底播放。连接失败时自动重试。
播放协议说明：
| 对比项 | WS-FLV / HTTP-FLV（默认） | WebRTC（可选） |
|---|---|---|
| 延迟 | 约 1~3 秒 | 约 200~500 毫秒 |
| 浏览器兼容性 | 高（需 MSE，主流浏览器均支持） | 中（部分移动端/企业环境受限） |
| 网络要求 | HTTP / WebSocket 端口，内网通常可通 | 需放行 UDP 媒体端口及 ICE 候选端口 |
| 适用场景 | 监控预览、录像回放 | 对延迟极敏感的实时控制 |
切换方式：默认由播放器自动选择 WS-FLV；若播放器或页面提供手动切换入口，可按需选择 WS-FLV / HTTP-FLV / WebRTC。
云台控制（PTZ）
八方向（上 / 下 / 左 / 右 / 四角）转动与停止、变倍缩放（长按放大 / 缩小）、云台速度调节（0 ~ 1），以及预置位管理：设置预置位（编号 + 名称）、调用预置位、删除预置位。
历史回放
选择月份后点击「查询日历」加载有录像的日期，选中日期查看录像列表（开始时间 / 结束时间 / 时长 / 类型），点击播放在线回放历史录像。
录像需配置后才会产生：平台侧录像需先为通道配置录像计划（或开启录制）后才会录制；未配置录像计划的通道不会自动录像，日历中也不会出现有录像的日期。
技术方案
接入架构
ONVIF 摄像机 ──RTSP──> ZLMediaKit ──WS-FLV/HTTP-FLV/HLS──> 浏览器
(设备发现接入) (流媒体收流) (实时预览 / 回放)
│
└──ONVIF 协议命令──> 平台 avsvr（PTZ 云台控制 / 录像查询）- ONVIF 摄像机在「音视频」模块按设备发现方式添加，平台持有设备 IP / 账号 / 通道信息
- IoT 设备维度绑定已有 ONVIF 设备通道，绑定关系落库（音视频设备记录记录所属产品与 IoT 设备名；设备侧协议配置记录
avDeviceID/avChannelID） - 拉流：ONVIF 摄像机 RTSP 流接入流媒体服务器 ZLMediaKit，播放默认走 WS-FLV / HTTP-FLV（HTTP/WebSocket 经平台反代，媒体流由 ZLM 直接转发）；支持切换 WebRTC 以获得更低延迟
- 控制：PTZ 云台、录像查询等走平台音视频服务接口下发 ONVIF 命令
- 平台把 GB28181 / ONVIF / RTSP-RTMP 三个协议统一内嵌注册到 avsvr，不依赖独立协议进程
与 GB28181 的能力差异
| 能力 | ONVIF | GB28181 |
|---|---|---|
| 接入方式 | 设备发现（IP / 端口 / 账号密码） | SIP 注册（国标域 / SIP ID / 密码） |
| 摄像机侧配置 | 无需国标配置 | 需按平台 SIP 参数在设备侧注册 |
| 拉流方式 | RTSP 拉流到流媒体服务器 | 平台主动收流（UDP/TCP 被动/主动） |
| 实时预览 | WS-FLV / HTTP-FLV | WS-FLV / HTTP-FLV |
| PTZ 云台控制 | ✅ | ✅ |
| 历史回放 | ✅ | ✅ |
| 接入入口 | 音视频设备管理 / 设备发现 | 音视频设备管理（SIP 注册上线） |
两者拉流后均汇入同一套流媒体与播放体系，绑定与预览、控制、回放操作完全一致。
协议注册与配置页托管
- 三个音视频协议（
gb28181/onvif/rtspRtmp）统一由 avsvr 在启动时幂等注册到协议信息表（类型为 media 音视频），不新建独立协议进程、不实例化协议直连对象 - avsvr 自托管一份单文件配置页（随 allinone 镜像打包），监听随机端口并把
web_port随心跳上报，平台经/api/v1/things/protocol/web/{device|product}/<code>反代后以 iframe 渲染到产品 / 设备详情的「设备接入」Tab - 协议注册与配置页服务不依赖部署级音视频开关，未启用完整音视频功能的环境同样可以查看接入说明
部署说明
- 镜像：音视频能力随
docker.unitedrhino.com/saas/allinone镜像发布（avsvr 内嵌，配置页打包进镜像），无需单独部署protocol-onvif协议容器 - 流媒体服务器：ZLMediaKit 独立容器，负责 ONVIF 摄像机 RTSP 拉流与 WS-FLV / HTTP-FLV / HLS / WebRTC 播放，默认监听 RTSP（
8554）、RTMP（1936）、HTTP（8088）、WebRTC 信令与媒体（8000，ICE / RTP 候选端口范围30000-30050）等端口，实际以部署配置为准
公网 WebRTC 预览必须放行
8000与30000-30050的 TCP + UDP；部分企业网络会阻断 UDP，可切换 HLS 播放。RTSP 源拉流超时时优先检查摄像机源地址可达性。
注意事项
- ONVIF 设备必须先添加到「音视频 - 设备管理 / 设备发现」，才能在产品 / 设备接入页的绑定下拉中出现
- 一个 IoT 设备绑定一路音视频通道；重复保存绑定会先解绑旧绑定再写入新关系
- 解绑操作需二次确认；解绑后需重新绑定才能预览
- 实时预览默认使用 WS-FLV / HTTP-FLV，依赖浏览器 MSE 支持与 HTTP/WebSocket 网络连通；如需 WebRTC 低延迟预览，需检查公网 WebRTC 端口放行
- 平台侧录像需配置录像计划后才会产生，未配置不会自动录制
- 平台侧通过设备发现 / 手动添加接入音视频模块，具体操作入口以「音视频 - 设备管理 / 设备发现」页面实际内容为准
参考链接
更新日志
2026/8/31 14:31
查看所有更新日志
2fc1c-于eb33f-于70dbb-于b72ca-于