4.7 KiB

Raw Blame History

海康 NVR HLS 回放控制台设计

状态： 已获用户确认，修改仅保留在本地工作区，不提交 Git。

1. 目标

为现有海康 NVR SDK 控制的 HLS 回放能力增加一个可直接打开的浏览器播放器。用户只需要在页面选择设备、日期和时间并点击查询，页面负责创建、轮询和控制回放会话，不再手工重复调用 Swagger 接口。

播放器覆盖当前后端已经支持的能力：

固定按北京时间输入和展示查询、跳转时间；
展示实际存在的连续录像区间；
自动创建 HLS 会话并等待 STARTING -> PLAYING；
播放、暂停、恢复、1/2/4/8 倍速、时间轴跳转和全屏；
HLS 地址只在浏览器同源页面中使用，不向页面返回 NVR 密码。

2. 已确认的配置策略

采用用户选择的 B 方案：NVR IP、SDK/RTSP 端口、账号和密码固定在 Spring Boot 后端配置中。页面只接收通道、码流类型和时间范围。

配置前缀为 hik.playback.ui：

hik:
  playback:
    ui:
      device-name: 海康 NVR
      nvr-ip: ${HIK_NVR_IP:192.168.1.249}
      sdk-port: ${HIK_NVR_SDK_PORT:8000}
      rtsp-port: ${HIK_NVR_RTSP_PORT:554}
      username: ${HIK_NVR_USERNAME:admin}
      password: ${HIK_NVR_PASSWORD:}
      default-channel: 1
      default-stream-type: 1

密码使用环境变量 HIK_NVR_PASSWORD，不会写入 HTML、Swagger 响应或日志。若密码为空，配置接口仍可打开页面，但创建会话时返回明确的配置错误。

3. 后端接口

3.1 读取页面配置

GET /hik/nvr/playback/hls/ui/config

返回页面需要的非敏感配置、设备树和默认通道。返回对象不包含 password，并通过 configured 标识后端是否已经具备创建会话的必要配置。

3.2 页面创建回放

POST /hik/nvr/playback/hls/ui/sessions

请求体只包含：

{
  "channel": 1,
  "streamType": 1,
  "startTime": "2026-07-13 12:00:00",
  "endTime": "2026-07-13 13:00:00"
}

控制台控制请求继续复用现有 /sessions/{sessionId}/controls 和 DELETE /sessions/{sessionId}，避免复制回放状态机。

4. 前端实现

不引入 Node、React 或 Thymeleaf，使用 Spring Boot 静态资源目录中的 playback.html，通过 http://localhost:18080/playback.html 打开。这样与后端同源，接口无需额外 CORS 配置。

页面采用“工业监控台”视觉方向：冷白工作区、深海军蓝文字、单一高亮蓝色、细边框卡片、淡网格背景和有限的入场动画。布局包含：

左侧设备树：固定 NVR、分组和可选通道；
顶部时间查询栏：日期、开始时间、结束时间、查询和重置；
中央视频舞台：HLS 视频、状态徽标、错误/等待提示和当前北京时间；
下方录像轨道：按请求时间范围绘制实际录像块，点击轨道发送 SEEK；
控制栏：到起点、暂停/恢复、到末尾、当前时间、音量、1/2/4/8 倍速和全屏。

播放器使用 hls.js CDN，在 Chrome/Edge 中加载 HLS；Safari 等支持原生 HLS 的浏览器直接设置 video.src。当后端返回新的 generation 或 HLS 地址时，销毁旧实例并重新加载，防止跳转后继续使用旧切片。

5. 状态与错误处理

页面加载时读取配置；读取失败显示连接错误，不阻止页面布局展示。
查询时禁用查询按钮，创建成功后轮询会话状态；STARTING 显示“等待首个关键帧”，PLAYING 才加载 m3u8。
404、409、502、503 等后端错误解析 message 并显示在视频舞台和顶部状态栏。
页面关闭或切换查询时，删除旧会话，释放 SDK、FFmpeg 和 ZLMediaKit 资源。
暂停、恢复、倍速和跳转均由后端 SDK 控制；前端不使用 video.playbackRate 伪造 NVR 倍速。

6. 文件变更

新增 HikNvrPlaybackUiProperties、页面配置 DTO、页面创建请求 DTO；
新增 HikNvrPlaybackUiController；
在 application.yml 增加 hik.playback.ui 固定配置；
新增 src/main/resources/static/playback.html；
新增后端控制器单元测试和页面接口契约测试；
更新设计文档与实施计划，所有变更不提交 Git。

7. 自审结论

配置策略与用户确认的 B 方案一致，页面不要求用户输入 NVR 账号密码；
页面只依赖现有 HLS 会话服务，不改变 SDK、FFmpeg 或 ZLMediaKit 数据通路；
倍速范围与现有服务的 1/2/4/8 约束一致；
HLS STARTING 轮询和 generation 重载覆盖了此前 VLC/HLS 首帧延迟及跳转旧切片问题；
静态页面无需新增前端构建环境，适合当前 Spring Boot 项目；
密码使用环境变量，避免将用户提供的凭据硬编码到仓库。

4.7 KiB Raw Blame History