hikvision-video-api/README.md

海康威视视频应用服务 API — Spring Boot 集成

功能概述

接口	说明
GET /api/cameras	分页获取摄像头资源列表
GET /api/cameras/{cameraIndexCode}	查询摄像头详情
GET /api/cameras/{cameraIndexCode}/preview-url	快捷获取实时预览播放地址
POST /api/cameras/preview-url	获取实时预览播放地址（完整参数）
POST /api/cameras/playback-url	获取录像回放播放地址

---

Web 监控界面

启动后访问 http://localhost:8080 即可打开视频监控界面：

• 左侧配置平台 IP / AppKey / AppSecret，点击「连接插件 & 初始化」
• 自动加载摄像头列表，点击任意摄像头即可播放实时视频
• 支持实时预览 / 录像回放切换
• 支持 1/4/9 分屏显示
• 抓图、本地录像等快捷操作

前提： 在 Windows 客户端安装海康官方 VideoWebPlugin.exe， 并将 JS 插件文件放入 src/main/resources/static/js/ 目录。

---

快速开始

1. 配置 application.yml

hikvision:
  api:
    host: https://192.168.1.100       # 平台IP或域名
    app-key: your_app_key             # 开放平台应用AppKey
    app-secret: your_app_secret       # 开放平台应用AppSecret

AppKey/AppSecret 在海康 iSecure Center 开放平台 → 应用管理 → 创建应用 后获取。

2. 编译运行

mvn clean package -DskipTests
java -jar target/hikvision-video-api-1.0.0.jar

---

接口调用示例

获取摄像头列表

curl "http://localhost:8080/api/cameras?pageNo=1&pageSize=20"

响应：

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 100,
    "pageNo": 1,
    "pageSize": 20,
    "totalPage": 5,
    "list": [
      {
        "cameraIndexCode": "abc123",
        "cameraName": "1号楼入口",
        "onlineStatus": "1",
        "installPlace": "1号楼大门"
      }
    ]
  }
}

---

获取实时预览播放地址（RTSP）

curl "http://localhost:8080/api/cameras/abc123/preview-url?protocol=1"

响应：

{
  "code": 200,
  "data": {
    "url": "rtsp://192.168.1.100:554/openUrl/xxxtoken"
  }
}

获取实时预览播放地址（HLS）

curl -X POST http://localhost:8080/api/cameras/preview-url \
  -H "Content-Type: application/json" \
  -d '{
    "cameraIndexCode": "abc123",
    "streamType": 0,
    "protocol": 3,
    "transmode": 1
  }'

响应：

{
  "code": 200,
  "data": {
    "url": "https://192.168.1.100/openUrl/xxxtoken/index.m3u8"
  }
}

---

获取录像回放播放地址

curl -X POST http://localhost:8080/api/cameras/playback-url \
  -H "Content-Type: application/json" \
  -d '{
    "cameraIndexCode": "abc123",
    "beginTime": "2024-01-01T00:00:00.000+08:00",
    "endTime":   "2024-01-01T01:00:00.000+08:00",
    "protocol": 1,
    "recordType": 0
  }'

---

协议类型说明

protocol值	协议	说明
1	RTSP	适合 VLC、ffmpeg 等本地播放
2	RTMP	适合 Flash/流媒体服务器转发
3	HLS	适合 Web 页面播放（video.js、hls.js）
4	FLV (HTTP-FLV)	适合 Web 低延时播放（flv.js）

---

项目结构

src/main/java/com/hikvision/video/
├── HikvisionVideoApplication.java     # 启动类
├── config/
│   └── HikvisionProperties.java       # 配置读取
├── controller/
│   └── VideoController.java           # REST接口
├── model/
│   └── HikModels.java                 # 请求/响应模型
├── service/
│   └── HikvisionVideoService.java     # 业务逻辑 & API调用
└── util/
    ├── HikvisionSignUtil.java          # HMAC-SHA256签名
    └── HttpUtil.java                   # HTTP请求工具

---

签名说明

海康 API 采用 HMAC-SHA256 签名鉴权，签名字符串格式：

{METHOD}\n
{Accept}\n
{Content-Type}\n
x-ca-key:{AppKey}\n
x-ca-nonce:{随机UUID}\n
x-ca-timestamp:{毫秒时间戳}\n
{请求路径}

签名结果 Base64 编码后放入请求头 X-Ca-Signature。

---

常见错误码

code	含义	解决方案
0	成功	—
401	鉴权失败	检查 AppKey/AppSecret 配置
1001	参数错误	检查 cameraIndexCode 是否存在
17004	摄像头离线	检查设备在线状态
10001	无权限	检查应用是否有摄像头访问权限