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

184 lines
4.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 摄像头本地流服务接口文档
> 服务地址:`http://localhost:17311`(主端口,备用端口依次为 `17312`、`17313`)
> 服务职责:代理前端与海康威视录像机(NVR)之间的连接,拉取实时视频流并转为 MJPEG 输出。
> 本服务独立于主后端 `/system`,由前端 `src/api/camera_server/localServerApi.ts` 直接调用。
## 目录
- [1. 获取海康通道列表](#1-获取海康通道列表)
- [2. 获取实时流(MJPEG)](#2-获取实时流mjpeg)
- [3. 停止实时流](#3-停止实时流)
---
## 1. 获取海康通道列表
用于测试录像服务器连通性,并获取其通道列表。
- **URL**:`POST /api/hikvision/channels`
- **Content-Type**:`application/json`
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ip | string | 是 | 录像机 IP 地址 |
| port | number | 否 | 录像机端口,默认 `8000` |
| user | string | 是 | 录像机登录账号 |
| pass | string | 是 | 录像机登录密码 |
### 请求示例
```json
{
"ip": "192.168.8.241",
"port": 8000,
"user": "admin",
"pass": "ky666888"
}
```
### 响应示例
```json
{
"success": true,
"channels": [
{ "channel": 1, "name": "通道1" },
{ "channel": 2, "name": "通道2" }
]
}
```
或兼容格式:
```json
{
"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` 作为流实例的定位键,与「获取实时流」一致。
### 请求示例
```json
{
"ip": "192.168.8.241",
"user": "admin",
"pass": "ky666888",
"channel": 9,
"port": 8000
}
```
### 响应示例
成功:
```json
{
"code": 0,
"message": "ok",
"data": {
"stopped": true,
"channel": 9
}
}
```
无对应流(幂等,不报错):
```json
{
"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`