184 lines
4.7 KiB
Markdown
184 lines
4.7 KiB
Markdown
# 摄像头本地流服务接口文档
|
||
|
||
> 服务地址:`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`
|
||
|