WEB/docs/camera-local-stream-api.md
2026-08-15 18:16:52 +08:00

4.7 KiB
Raw Permalink Blame History

摄像头本地流服务接口文档

服务地址:http://localhost:17311(主端口,备用端口依次为 17312、17313) 服务职责:代理前端与海康威视录像机(NVR)之间的连接,拉取实时视频流并转为 MJPEG 输出。 本服务独立于主后端 /system,由前端 src/api/camera_server/localServerApi.ts 直接调用。

目录


1. 获取海康通道列表

用于测试录像服务器连通性,并获取其通道列表。

  • URL:POST /api/hikvision/channels
  • Content-Type:application/json

请求参数

字段 类型 必填 说明
ip string 是 录像机 IP 地址
port number 否 录像机端口,默认 8000
user string 是 录像机登录账号
pass string 是 录像机登录密码

请求示例

{
  "ip": "192.168.8.241",
  "port": 8000,
  "user": "admin",
  "pass": "ky666888"
}

响应示例

{
  "success": true,
  "channels": [
    { "channel": 1, "name": "通道1" },
    { "channel": 2, "name": "通道2" }
  ]
}

或兼容格式:

{
  "code": 0,
  "message": "ok",
  "data": [
    { "channel": 1, "name": "通道1" }
  ]
}

2. 获取实时流(MJPEG)

拉取指定通道的实时视频流,以 multipart/x-mixed-replace 的 MJPEG 流返回,前端用 <img src="..."> 直接渲染。

  • URL:GET /api/hikvision/live-stream
  • 返回:multipart/x-mixed-replace 的 MJPEG 流(长连接)

Query 参数

字段 类型 必填 说明
ip string 是 录像机 IP 地址
user string 是 录像机登录账号
pass string 是 录像机登录密码
channel number 是 通道号
streamType number 否 码流类型,0 主码流(默认),1 子码流
port number 否 录像机端口,默认 8000

请求示例

GET /api/hikvision/live-stream?ip=192.168.8.241&user=admin&pass=ky666888&channel=9&streamType=0&port=8000

后端实现要求

  • 每个「录像机 + 通道」应维护独立的 ffmpeg 子进程,并按 ip + channel(或生成的 session id)登记。
  • 客户端断开(req.on('close') / res.on('close'))时,应立即 kill 对应 ffmpeg 子进程,作为兜底回收机制。
  • 同一 ip + channel 若已有活跃进程,建议复用或先停旧再启新,避免重复拉起。

3. 停止实时流

显式停止指定通道的实时流,后端据此 kill 对应 ffmpeg 子进程。前端在关闭预览浮窗、切换摄像头、组件卸载时调用。

  • URL:POST /api/hikvision/stop-stream
  • Content-Type:application/json

请求参数

字段 类型 必填 说明
ip string 是 录像机 IP 地址
user string 是 录像机登录账号
pass string 是 录像机登录密码
channel number 是 通道号
port number 否 录像机端口,默认 8000

ip + channel 作为流实例的定位键,与「获取实时流」一致。

请求示例

{
  "ip": "192.168.8.241",
  "user": "admin",
  "pass": "ky666888",
  "channel": 9,
  "port": 8000
}

响应示例

成功:

{
  "code": 0,
  "message": "ok",
  "data": {
    "stopped": true,
    "channel": 9
  }
}

无对应流(幂等,不报错):

{
  "code": 0,
  "message": "no active stream",
  "data": {
    "stopped": false,
    "channel": 9
  }
}

后端实现要求

  1. 根据 ip + channel 在进程表中查找对应 ffmpeg 子进程;
  2. 找到后 ffmpeg.kill('SIGKILL')(或先 SIGTERM 再兜底 SIGKILL),并从进程表移除;
  3. 幂等:未找到对应流时也应返回成功(stopped: false),不应返回 4xx/5xx;
  4. 若同时存在基于 session id 的实例,应同时支持按 sessionId 定位(可选扩展)。

前端调用关系

returnUnpackwork/index.vue
  └─ 关闭浮窗 closePreview() → livePreviewRef.stop()
CameraLivePreview.vue
  ├─ 拉流成功 → 记录 activeStream
  └─ stopStream() → stopLiveStream(activeStream)   // POST /api/hikvision/stop-stream

前端调用封装位于 src/api/camera_server/localServerApi.ts:

  • getHikvisionChannels(baseUrl, params) → POST /api/hikvision/channels
  • getLiveStreamUrl(params) → 生成 GET /api/hikvision/live-stream 地址
  • stopLiveStream(params) → POST /api/hikvision/stop-stream