ONVIF协议接入
简介
ONVIF（Open Network Video Interface Forum）是网络摄像机（IPC）行业最通用的互操作标准之一，联犀平台通过 onvif 协议将符合 ONVIF 标准的网络摄像机接入音视频模块，实现统一纳管、实时预览、云台控制与录像回放。
与 GB28181 国标走 SIP 注册的接入方式不同，ONVIF 摄像机采用设备发现方式接入：平台先在「音视频 - 设备管理 / 设备发现」中按摄像机 IP、端口、用户名、密码完成添加，再在 IoT 设备维度绑定已有音视频设备通道即可完成关联，无需在摄像机侧做任何国标配置。
核心能力：绑定后设备接入页统一提供 WebRTC 实时预览，ONVIF 设备额外支持 PTZ 云台控制（方向 / 变倍 / 预置位） 与 历史回放（录像日历 → 录像列表 → 播放）。
应用场景
- 标准 ONVIF 摄像机接入：符合 ONVIF 规范的 IPC 设备，按设备发现方式接入音视频模块
- 设备维度绑定：IoT 设备与已有 ONVIF 音视频设备通道建立绑定关系，一个 IoT 设备对应一路视频通道
- 实时预览：绑定后经 WebRTC 在浏览器低延迟观看实时画面（依赖流媒体服务器 ZLMediaKit 收流）
- PTZ 云台控制：支持八方向转动、停止、变倍缩放、云台速度调节，以及预置位的设置 / 调用 / 删除
- 历史回放：按月份查询录像日历，选择有录像的日期查看录像列表并在线回放
能力边界：ONVIF 通道仅支持「绑定已有音视频设备」方式接入，不支持填写流地址自动建档（该能力仅 RTSP/RTMP 协议提供）。
前置条件
- 音视频服务已部署：
allinone镜像已包含音视频服务（avsvr）与流媒体服务器 ZLMediaKit，部署时启用音视频功能（avDocker.yaml配置Enable: true） - 网络可达：ONVIF 摄像机与平台流媒体服务网络互通；若浏览器需直接播放 WebRTC，还需公网放行 ZLMediaKit 的 WebRTC 端口（见部署说明）
- 设备凭据：ONVIF 摄像机的 IP、端口（默认 80）、用户名、密码
- 产品已创建：创建产品时主协议选择「音视频」分组下的
ONVIF 协议接入
产品配置
1. 创建产品
创建产品时，「主协议」下拉选择「音视频」分组下的 ONVIF 协议接入（同分组还提供 GB28181 国标视频接入、RTSP/RTMP 拉流接入）：
2. 产品接入说明
进入产品详情「设备接入」Tab，平台按协议类型渲染对应的接入说明页。ONVIF 产品页展示接入指引：
- 先在「音视频 - 设备管理 / 设备发现」中添加 ONVIF 设备（输入摄像机 IP、端口、用户名、密码完成接入）；
- 回到设备接入页，在「绑定已有音视频设备」中选中该 ONVIF 设备，再选择对应通道完成绑定；
- 绑定成功后即可进行 WebRTC 实时预览、云台（PTZ）控制与历史回放。
产品页展示的为协议接入说明（以配置页实际内容为准），不进行设备绑定操作；绑定在设备维度的「设备接入」页完成。
设备接入
1. 在音视频模块添加 ONVIF 设备
进入「音视频 - 设备管理 / 设备发现」，按摄像机信息添加 ONVIF 设备，添加成功后设备出现在音视频设备列表中。
2. 创建设备并绑定通道
在产品下创建 IoT 设备，进入设备详情「设备接入」Tab，页面展示当前绑定状态。未绑定时提供「绑定已有音视频设备」卡片：
- 音视频设备：下拉选择已添加的 ONVIF 设备（设备列表按协议类型过滤）
- 通道：选中设备后自动加载其通道列表，选择要绑定的一路通道
- 点击「确认绑定」，绑定成功后页面刷新为已绑定视图
3. 解绑
已绑定页面顶部展示绑定信息（音视频设备、通道、传输协议、通道 ID），提供「解绑」按钮，二次确认后解除绑定关系；解绑后需重新绑定才能预览。
绑定后能力
实时预览（WebRTC）
页面提供「开始预览 / 停止预览」按钮，使用浏览器原生 WebRTC（RTCPeerConnection）与流媒体服务器完成信令与媒体交互，低延迟观看实时画面；连接失败时自动重试，并可通过 HLS 等协议作为备选播放方式。
云台控制（PTZ）
八方向（上 / 下 / 左 / 右 / 四角）转动与停止、变倍缩放（长按放大 / 缩小）、云台速度调节（0 ~ 1），以及预置位管理：设置预置位（编号 + 名称）、调用预置位、删除预置位。
历史回放
选择月份后点击「查询日历」加载有录像的日期，选中日期查看录像列表（开始时间 / 结束时间 / 时长 / 类型），点击播放在线回放历史录像。
技术方案
接入架构
ONVIF 摄像机 ──RTSP──> ZLMediaKit ──WebRTC/HLS/FLV──> 浏览器
(设备发现接入) (流媒体收流) (实时预览 / 回放)
│
└──ONVIF 协议命令──> 平台 avsvr（PTZ 云台控制 / 录像查询）- ONVIF 摄像机在「音视频」模块按设备发现方式添加，平台持有设备 IP / 账号 / 通道信息
- IoT 设备维度绑定已有 ONVIF 设备通道，绑定关系落库（音视频设备记录记录所属产品与 IoT 设备名；设备侧协议配置记录
avDeviceID/avChannelID） - 拉流：ONVIF 摄像机 RTSP 流接入流媒体服务器 ZLMediaKit，播放统一走 WebRTC（信令经平台反代，媒体直连 ZLM）
- 控制：PTZ 云台、录像查询等走平台音视频服务接口下发 ONVIF 命令
- 平台把 GB28181 / ONVIF / RTSP-RTMP 三个协议统一内嵌注册到 avsvr，不依赖独立协议进程
与 GB28181 的能力差异
| 能力 | ONVIF | GB28181 |
|---|---|---|
| 接入方式 | 设备发现（IP / 端口 / 账号密码） | SIP 注册（国标域 / SIP ID / 密码） |
| 摄像机侧配置 | 无需国标配置 | 需按平台 SIP 参数在设备侧注册 |
| 拉流方式 | RTSP 拉流到流媒体服务器 | 平台主动收流（UDP/TCP 被动/主动） |
| 实时预览 | WebRTC | WebRTC |
| 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 拉流与 WebRTC / HLS / FLV 播放
- 端口分工（以测试环境为例）：
| 端口 | 用途 |
|---|---|
8554 | ZLMediaKit RTSP 推流 / 播放 |
1936 | ZLMediaKit RTMP 推流 / 播放 |
8088 | ZLMediaKit HTTP API / HLS（经反向代理对外，可不直接开放） |
8000 | WebRTC 信令与媒体（TCP/UDP，公网预览需放行） |
30000-30050 | WebRTC ICE / RTP 候选端口范围（TCP/UDP，公网预览需放行） |
公网 WebRTC 预览必须放行
8000与30000-30050的 TCP + UDP；部分企业网络会阻断 UDP，可切换 HLS 播放。RTSP 源拉流超时时优先检查摄像机源地址可达性。
注意事项
- ONVIF 设备必须先添加到「音视频 - 设备管理 / 设备发现」，才能在产品 / 设备接入页的绑定下拉中出现
- 一个 IoT 设备绑定一路音视频通道；重复保存绑定会先解绑旧绑定再写入新关系
- 解绑操作需二次确认；解绑后需重新绑定才能预览
- 实时预览依赖浏览器 WebRTC 能力与网络连通；ICE 连接超时优先检查公网端口放行
- 平台侧通过设备发现 / 手动添加接入音视频模块，具体操作入口以「音视频 - 设备管理 / 设备发现」页面实际内容为准
参考链接
更新日志
2026/8/22 01:02
查看所有更新日志
bdb19-于
