title: 阶段总结之海康摄像头接入 createTime: 2025/11/02 21:31:11 permalink: /article/vq1oqr2u/

引言

本文记录我在项目中从 0 搭建“海康摄像头 → Web 预览与告警图片”的完整链路与实践要点。网络链路如下：

摄像头 → NVR → 边缘计算路由器 → 光猫 → HikDeviceGateway 所在服务器 → ZLMediaKit 所在服务器 → 业务系统

核心目标：

• 获取稳定可用的预览流 URL（RTSP → 浏览器友好格式）
• 通过轮询接口获取告警图片，下载并投递到 MQ 供其他服务消费

---

一、系统架构概览

• 组件角色：

  • HikDeviceGateway：统一对接海康设备，负责 ISUP 5.0 注册、ISAPI 透传与预览流 URL 获取
  • ZLMediaKit：负责将 RTSP 流协议转换为浏览器友好的 HTTP-fMP4/WS-FLV/HLS 等

• 数据流向：

  • 摄像头/NVR 产出 RTSP 流 → 网关拉取/汇聚 → 转给 ZLMediaKit 做按需协议转换 → 前端以 fMP4/FLV/HLS 播放
  • 告警图片由轮询接口发现 → 下载存储 → 投递 MQ 供下游服务消费与展示

---

二、网络环境搭建与成本优化（动态 IP + DDNS）

由于未购买固定公网 IP，我采用“路由器定时任务上报 IP 到 DDNS 服务”的方式，将域名与当前公网 IP 绑定，从而以固定域名远程访问路由器与同网络的 NVR：

• 方案要点：
  • 路由器定时任务每 5 分钟上报一次当前公网 IP
  • DDNS 平台将域名解析更新为最新 IP
  • 通过固定域名访问路由器/NVR/服务器，便于远程调试与改配置

---

三、HikDeviceGateway 集成与使用

参考文档：https://open.hikvision.com/docs/docId?productId=5cda567cf47ae80dd41a54b3&version=%2F0cbf4539c3e74a3f858f9601582544e9&tagPath=%E6%A6%82%E8%BF%B0-%E7%AE%80%E4%BB%8B

3.1 ISUP 5.0 设备注册

• 作用：对接海康设备（摄像头/NVR），统一注册并管理在线状态
• 流程概要：
  1. 在网关侧创建/维护设备接入参数（设备序列号、认证信息、通道信息）
  2. 设备上线后，网关维护心跳与状态；异常时做重连与告警
• 典型要点：
  • 确认设备时间、网络与鉴权参数一致，避免注册失败
  • 为多通道 NVR 规划好通道索引与码流（主/子码流）
• 网关页面选择接入网卡 IP 的实操注意：
  • 在 HikDeviceGateway 的页面中，需要从下拉框选择“作为设备接入网络”的宿主机网卡 IP。
  • 不建议在“有大量 Docker 桥接网络”的宿主机上部署网关：网关会枚举并展示这些 bridge 网段的 IP，导致下拉列表挤满无用项。
  • 该下拉列表最多仅显示有限数量的 IP（实际观察约 12～16 项），一旦真实对外网关 IP不在展示范围内，将无法选择正确的对外网卡。
  • 建议：
    1. 在网络干净的宿主机或专用虚拟机上部署网关；
    2. 清理多余的 Docker 网络或减少 bridge 数量；
    3. 明确标注宿主机“对外网关”的真实网卡与 IP，避免选错导致设备接入失败。

3.2 ISAPI 协议透传

• 作用：通过网关直接调用设备的 ISAPI 接口（查询/控制/参数调整）
• 使用场景：
  • 查询设备配置（如 GET /ISAPI/System/time）
  • 设置编码/码率/OSD 等（如 PUT /ISAPI/Streaming/channels/101）
• 透传调用要点：
  • 网关提供 REST 接口，内部代理到设备 ISAPI；统一鉴权与日志
  • 建议对高频调用做限速与重试

3.3 预览 RTSP 流 URL 获取

• 常见海康 RTSP 地址格式：
  • 主码流：rtsp://<device_ip>:554/Streaming/Channels/101
  • 子码流：rtsp://<device_ip>:554/Streaming/Channels/102
• 通过网关获取预览 URL：
  • 在网关侧调用预览接口，返回设备通道对应的 RTSP URL
  • 结合设备在线状态与码流偏好，动态选择 101/102 等通道

---

四、ZLMediaKit 流媒体服务

参考文档：https://docs.zlmediakit.com/zh/guide/

4.1 RTSP → HTTP-fMP4 转换

• 背景：浏览器原生不支持 RTSP，需将协议转换为 HTTP-fMP4/WS-FLV/HLS 等
• 典型用法：
  1. 通过 ZLMediaKit 的 API 添加 RTSP 代理（按需拉流）
  2. 获取对应的播放地址（例如 http://<zlm_host>/live/<stream>.fmp4）
• 示例（添加流代理，具体参数以实际部署为准）：

curl -X POST "http://<zlm_host>:<api_port>/index/api/addStreamProxy" \
  -d "vhost=__defaultVhost__&app=live&stream=cam01&url=rtsp://<device_ip>:554/Streaming/Channels/101&retry_count=3"

• 常见播放地址形式：
  • HTTP-fMP4：http://<zlm_host>/live/cam01.fmp4
  • WS-FLV：ws://<zlm_host>/live/cam01.live.flv
  • HLS：http://<zlm_host>/live/cam01/hls.m3u8

4.2 延迟与带宽简述

• 低延迟建议：优先使用 HTTP-fMP4/WS-FLV 等秒开、低时延方式
• 带宽规划：依据码率（主码流/子码流）与并发播放数量做带宽预估

---

五、告警图片功能实现（轮询 + 下载 + MQ 投递）

5.1 轮询策略与时间窗口

• 实现思路：隔固定时间（如每 30 秒/1 分钟）调用接口，查询“最近一段时间”是否有新图片；有则下载并投递 MQ。
• 时间窗口：使用 [now - interval - overlap, now]，其中 overlap（如 5~10 秒）用于处理时钟误差或接口延迟，避免漏图。
• 游标维护：每个设备/通道维护“最后处理时间戳”；下一次查询从该时间戳向后推进，配合 overlap 防抖。
• 幂等关键：新图片以 deviceId + channel + eventTime + filename 作为唯一键，已处理的键写入去重集合（如 Redis set）。

示例伪代码：

for each deviceChannel in configuredList:
  windowStart = max(lastProcessedTime[deviceChannel] - overlap, now - interval)
  windowEnd   = now
  images = queryImages(deviceChannel, windowStart, windowEnd)
  for img in images:
    key = hash(deviceId, channel, img.eventTime, img.filename)
    if not exists(processedSet, key):
      path = download(img.url)
      sendToMQ({deviceId, channel, eventTime, path, checksum})
      mark(processedSet, key)
      lastProcessedTime[deviceChannel] = max(lastProcessedTime, img.eventTime)

5.2 下载与存储规范

• 下载方式：HTTP 流式下载，校验 Content-Length/MD5，失败重试（指数退避，最大重试次数）。
• 存储路径：/alerts/{deviceId}/{channel}/{yyyy-MM-dd}/{eventTime}_{filename}；统一文件命名便于检索与生命周期管理。
• 图片质量：根据业务需要控制分辨率与压缩质量（JPEG/PNG），建议优先 JPEG 以降低存储占用。
• 清理策略：针对历史数据配置生命周期（例如保留 90 天），定期归档或清理。

5.3 MQ 投递与消费

• 消息结构（示例）：

{
  "deviceId": "HK-001",
  "channel": "101",
  "eventTime": "2025-11-02T21:33:21Z",
  "imagePath": "/alerts/HK-001/101/2025-11-02/1730871201_alarm.jpg",
  "checksum": "md5-xxxx",
  "size": 183245
}

• 队列设置：开启持久化；失败重试与死信队列（DLQ）；消费者幂等（根据唯一键去重）。
• 业务消费：下游服务根据 deviceId/channel/eventTime 做关联，支持二次处理（识别/标注/推送）。

5.4 失败兜底与监控

• 失败重试：下载失败或 MQ 不可用时，写入重试队列，采用指数退避；超过阈值写入 DLQ 等待人工/定时恢复。
• 指标监控：记录每分钟新图片数、下载失败率、MQ 投递失败率、平均处理时延；出现异常时告警。
• 速率限制：为接口调用与下载设置限流，避免高并发导致设备或网关过载。

---

六、性能测试（保留）

• 并发能力：在 N 路摄像头同时预览时的 CPU/内存占用与丢帧率
• 端到端时延：摄像头 → 网关 → ZLMediaKit → 浏览器 的总时延测量
• 带宽测算：主/子码流在不同并发下的上/下行带宽占用

---

七、项目总结

• HikDeviceGateway + ZLMediaKit 组合能较好满足“RTSP 到 Web 播放”的通用需求
• 动态 IP + DDNS 大幅降低公网成本，同时保证远程维护与配置变更可行
• 告警图片抓取与展示对前端无强依赖，只需提供稳定 URL 与基本接口即可

---

附录

• DDNS 上报脚本与定时任务示例（见上文）
• 常用端口（按需开放）：
  • 554：RTSP（摄像头/NVR）
  • 80/443：HTTP/HTTPS（网关/ZLMediaKit/管理台）
  • 1935：RTMP（ZLMediaKit 可选）
• 参考链接：
  • HikDeviceGateway 文档：https://open.hikvision.com/docs/docId?productId=5cda567cf47ae80dd41a54b3&version=%2F0cbf4539c3e74a3f858f9601582544e9&tagPath=%E6%A6%82%E8%BF%B0-%E7%AE%80%E4%BB%8B
  • ZLMediaKit 指南：https://docs.zlmediakit.com/zh/guide/