海康威视视频功能集成说明

一、依赖配置

1. Maven 依赖

xml 复制代码

<dependencies>
    <dependency>
        <groupId>com.hikvision.ga</groupId>
        <artifactId>artemis-http-client</artifactId>
       <version>1.1.3</version>
    </dependency>
</dependencies>

二、配置文件

application.yml 配置项

yaml 复制代码

# 摄像头视频配置
hikvision:
  # 链接地址（海康威视平台地址）
  host: xxx.xxx.xxx.xxx:xxxx
  # 替换IP（用于返回给前端的实际访问地址）
  replaceHost: xxx.xxx.xxx.xxx
  # API密钥
  appKey: xxxxxx
  # API密钥密码
  appSecret: xxxxxxxxxxxxxx

配置说明：

host: 海康威视 Artemis 网关地址，格式为 IP:端口
replaceHost: 前端实际访问的 IP 地址（用于内网穿透或代理场景）
appKey: 海康开放平台应用 Key
appSecret: 海康开放平台应用 Secret

三、典型接口示例：获取视频播放地址

接口说明

接口路径: /videoInfor/getVideoUrl

请求方式: POST

功能: 根据摄像头编码获取 WebSocket 实时预览地址

请求参数

java 复制代码

public class VideoUrlParam {
    private String code; // 摄像头编码（cameraIndexCode）
}

Controller 层

java 复制代码

@PostMapping("/getVideoUrl")
@ApiOperation("获取视频url")
public R getVideoUrl(VideoUrlParam param) {
    return R.ok(videoInforService.getVideoUrl(param));
}

Service 层

java 复制代码

public Map getVideoUrl(VideoUrlParam param) {
    try {
        // 1. 初始化海康配置
        ArtemisPostTest.getHostByareaCode(host, appKey, appSecret);
        
        // 2. 调用海康 API 获取视频 URL
        String resultJson = ArtemisPostTest.callPostStringApi(param.getCode());
        
        // 3. 解析返回结果
        JSONObject jsonObject = JSONObject.parseObject(resultJson);
        Object data = jsonObject.get("data");
        if (StringUtils.isNull(data)) {
            throw new ServiceException(jsonObject.get("msg").toString());
        }
        
        // 4. IP 地址替换（内网穿透场景）
        String oldIp = host.substring(0, host.indexOf(":"));
        String result = data.toString().replaceAll(oldIp, replaceHost);
        
        // 5. 返回结果
        ObjectMapper objectMapper = new ObjectMapper();
        return objectMapper.readValue(result, Map.class);
    } catch (ServiceException e) {
        throw e;
    } catch (Exception e) {
        throw new ServiceException("获取视频url失败！" + e.getMessage());
    }
}

返回结果

json 复制代码

{
  "code": 200,
  "data": {
    "url": "ws://xxx.xxx.xxx.xxx:559/openUrl/vsig324hUJ2ca2cf47c4b4a4b1aa2ca6"
  }
}

四、集成海康威视 SDK 过程

1. 添加 Maven 依赖

2. 配置文件设置

在 application.yml 中添加海康威视配置：

yaml 复制代码

hikvision:
  host: xxx.xxx.xxx.xxx:xxxx        # 海康平台地址
  replaceHost: xxx.xxx.xxx.xxx      # 前端访问地址（IP替换用）
  appKey: xxxxxx                    # 应用Key
  appSecret: xxxxxxxxxxxxxx         # 应用密钥

3. 初始化海康配置

在 Service 或 Util 类中注入配置并初始化：

java 复制代码

@Value("${hikvision.host}")
private String host;

@Value("${hikvision.replaceHost}")
private String replaceHost;

@Value("${hikvision.appKey}")
private String appKey;

@Value("${hikvision.appSecret}")
private String appSecret;

// 初始化配置
ArtemisPostTest.getHostByareaCode(host, appKey, appSecret);

4. 调用海康 API

使用 ArtemisHttpUtil 调用海康开放平台接口：

java 复制代码

public static String callPostStringApi(String cameraCode) {
    // API 路径
    final String previewURLsApi = "/artemis" + "/api/video/v2/cameras/previewURLs";
    
    // 构建请求路径
    Map<String, String> path = new HashMap<String, String>(2) {
        {
            put("https://", previewURLsApi); // 根据环境选择 http/https
        }
    };
    
    // 构建请求参数
    JSONObject jsonBody = new JSONObject();
    jsonBody.put("cameraIndexCode", cameraCode);  // 摄像头编码
    jsonBody.put("streamType", 0);                 // 码流类型：0-主码流，1-子码流
    jsonBody.put("protocol", "ws");                // 协议：ws/hls/rtmp
    jsonBody.put("transmode", 1);                  // 传输模式：1-UDP，2-TCP
    
    String body = jsonBody.toJSONString();
    
    // 调用海康 SDK
    String result = ArtemisHttpUtil.doPostStringArtemis(
        path, 
        body, 
        null, 
        null, 
        "application/json", 
        null
    );
    
    return result;
}

5. 处理返回结果

java 复制代码

// 解析海康返回的 JSON
JSONObject jsonObject = JSONObject.parseObject(result);
Object data = jsonObject.get("data");

if (StringUtils.isNull(data)) {
    throw new ServiceException(jsonObject.get("msg").toString());
}

// 提取视频 URL
Map<String, Object> map = objectMapper.readValue(data.toString(), Map.class);
String url = (String) map.get("url");
// 例如: ws://121.28.213.186:559/openUrl/vsig324hUJ2ca2cf47c4b4a4b1aa2ca6

6. IP 地址替换（可选）

如果海康平台在内网，需要替换为公网地址供前端访问：

java 复制代码

// 提取原 IP
String oldIp = host.substring(0, host.indexOf(":"));

// 替换为新 IP
url = url.replaceAll(oldIp, replaceHost);
// 例如: ws://公网IP:559/openUrl/vsig324hUJ2ca2cf47c4b4a4b1aa2ca6

五、常见问题

Q1: 为什么需要 IP 替换？

答: 在海康威视部署在内网的场景下，后端服务器可以直接访问海康平台（内网 IP），但前端浏览器无法直接访问内网。通过 replaceHost 配置，可以将返回的 URL 中的内网 IP 替换为公网 IP 或代理地址，实现内外网隔离下的视频播放。

Q2: 支持哪些视频协议？

答: 目前系统主要使用以下协议：

WebSocket (ws): 实时预览，低延迟
HLS: HTTP Live Streaming，适合移动端
RTMP: 传统流媒体协议

可在 callPostStringApi() 方法中通过 protocol 参数指定。

Q3: 如何添加新的海康 API 接口？

步骤:

在 ArtemisPostTest 中添加新方法
定义 API 路径常量
构建请求参数（JSONObject）
调用 ArtemisHttpUtil.doPostStringArtemis()
在 VideoInforService 中封装业务逻辑
在 VideoInforController 中暴露接口

Q4: 视频播放失败如何排查？

排查步骤:

检查 application.yml 配置是否正确（host、appKey、appSecret）
查看日志中是否有海康 API 返回的错误信息
确认摄像头编码（cameraIndexCode）是否正确
检查网络连通性（后端能否访问海康平台）
验证 IP 替换逻辑是否正确（前端能否访问 replaceHost）
检查浏览器是否支持 WebSocket 协议

Q5: 如何实现视频回放功能？

答: 系统中已预留回放接口方法 playbackURLs()，需要：

传入摄像头编码、开始时间、结束时间
调用海康回放 API 获取回放 URL
前端使用 HLS 播放器播放回放视频

六、安全注意事项

敏感信息保护:
- appKey 和 appSecret 不应硬编码在代码中
- 生产环境建议使用配置中心或环境变量
访问控制:
- 视频接口应进行身份认证
- 根据用户权限过滤可访问的摄像头
IP 白名单:
- 海康平台建议配置 IP 白名单
- 限制只有授权服务器可以调用 API
HTTPS 加密:
- 生产环境建议使用 HTTPS 协议
- 确保 ArtemisConfig 中使用 https:// 前缀
日志脱敏:
- 日志中不应输出完整的 appSecret
- 敏感参数应进行脱敏处理

七、性能优化建议

缓存策略:
- 视频树结构可以缓存（Redis）
- 减少频繁查询数据库
分页加载:
- 批量获取视频时使用分页（每页9条）
- 避免一次性加载过多视频
异步处理:
- 视频同步任务使用异步执行
- 避免阻塞主线程
连接池:
- 复用 ArtemisConfig 配置
- 避免重复初始化
超时设置:
- 合理设置 HTTP 请求超时时间
- 避免长时间等待导致线程阻塞

八、总结

集成步骤概览

添加依赖 : 引入 artemis-http-client SDK
配置参数 : 在 application.yml 中配置海康平台连接信息
初始化配置 : 调用 ArtemisPostTest.getHostByareaCode() 初始化 SDK
调用 API : 使用 ArtemisHttpUtil.doPostStringArtemis() 调用海康接口
处理结果: 解析返回的 JSON，提取视频 URL
IP 替换: 如需内网穿透，替换 URL 中的 IP 地址

核心要点

SDK : 使用海康官方提供的 artemis-http-client
认证 : 通过 appKey 和 appSecret 进行身份认证
协议: 支持 WebSocket、HLS、RTMP 等多种视频协议
灵活: 可根据需求调用不同的海康 API 接口（预览、回放、云台控制等）

通过以上步骤，即可快速集成海康威视视频监控功能到您的系统中。