crosstyan/srs-spi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc (#29)

Browse Source 
* update log

* update log level

* Enhance config.yaml by adding a comment for log-level options

* update log

* Refactor SIP service start method to accept configuration parameter for log level management

* 增加文档
This commit is contained in:
Haibo Chen(陈海博)
2025-08-26 13:59:18 +08:00
committed by GitHub
parent c034bfdae5
commit f59c92162b
3 changed files with 597 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
README.md
View File

@ -79,25 +79,31 @@ sequenceDiagram
## API 接口
- 请求与响应数据格式为JSON
- 所有响应的统一结构为：
```json
{
"code": 0,
"data": {}
}
```
SRS-SIP 提供了完整的 HTTP API 接口，用于设备管理、视频流控制、PTZ控制等功能。
错误响应示例：
```
{
"code": 500,
"data": {
"msg": "error message"
}
}
```
详细的API接口文档请参考：[API接口文档](doc/API.md)
### 接口列表
### 主要功能
暂无，请参考demo。
- **设备管理**：获取设备列表、通道信息
- **视频流控制**：发起视频邀请、暂停/恢复、调整播放速度
- **PTZ控制**：云台控制（上下左右、缩放）
- **录像查询**：查询历史录像记录
- **媒体服务器管理**：配置和管理媒体服务器
### 快速开始
```bash
# 获取设备列表
curl -X GET "http://localhost:8025/srs-sip/v1/devices"
# 发起视频邀请
curl -X POST "http://localhost:8025/srs-sip/v1/invite" \
-H "Content-Type: application/json" \
-d '{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"media_server_id": 1,
"play_type": 0
}'
```

571
doc/API.md Normal file
View File

@ -0,0 +1,571 @@
# SRS-SIP API 接口文档
## 概述
SRS-SIP 是一个基于 GB28181 协议的视频监控系统，提供设备管理、视频流控制、PTZ控制等功能。本文档描述了系统提供的 HTTP API 接口。
**基础信息：**
- 基础URL: `/srs-sip/v1`
- 内容类型: `application/json`
- 响应格式: JSON
## 通用响应格式
所有API接口都使用统一的响应格式：
```json
{
"code": 0,
"data": {}
}
```
- `code`: 状态码，0表示成功，其他值表示错误
- `data`: 响应数据，具体内容根据接口而定
## 1. 系统信息接口
### 1.1 获取API版本信息
**接口地址：** `GET /srs-sip`
**描述：** 获取API版本信息
**响应示例：**
```json
{
"version": "v1"
}
```
### 1.2 获取所有API路由
**接口地址：** `GET /srs-sip/v1`
**描述：** 获取系统所有可用的API路由列表
**响应示例：**
```json
{
"code": 0,
"data": [
{
"method": "GET",
"path": "/srs-sip/v1/devices"
},
{
"method": "POST",
"path": "/srs-sip/v1/invite"
}
]
}
```
## 2. 设备管理接口
### 2.1 获取设备列表
**接口地址：** `GET /srs-sip/v1/devices`
**描述：** 获取所有已注册的设备列表
**响应示例：**
```json
{
"code": 0,
"data": [
{
"device_id": "34020000001320000001",
"source_addr": "192.168.1.100:5060",
"network_type": "UDP",
"online": true,
"heart_beat_interval": 60,
"heart_beat_count": 3
}
]
}
```
**响应字段说明：**
- `device_id`: 设备ID
- `source_addr`: 设备源地址
- `network_type`: 网络类型（UDP/TCP）
- `online`: 设备在线状态
- `heart_beat_interval`: 心跳间隔时间（秒）
- `heart_beat_count`: 心跳超时次数
### 2.2 获取设备通道列表
**接口地址：** `GET /srs-sip/v1/devices/{id}/channels`
**描述：** 获取指定设备的所有通道信息
**路径参数：**
- `id`: 设备ID
**响应示例：**
```json
{
"code": 0,
"data": [
{
"device_id": "34020000001320000002",
"parent_id": "34020000001320000001",
"name": "摄像头01",
"manufacturer": "HIKVISION",
"model": "DS-2CD2T47G1-L",
"owner": "Camera Owner",
"civil_code": "320100",
"address": "测试地址",
"port": 5060,
"parental": 1,
"safety_way": 0,
"register_way": 1,
"secrecy": 0,
"ip_address": "192.168.1.100",
"status": "ON",
"longitude": 120.123456,
"latitude": 30.123456,
"info": {
"ptz_type": 1,
"resolution": "1920*1080",
"download_speed": "4"
},
"ssrc": "1234567890"
}
]
}
```
### 2.3 获取所有通道列表
**接口地址：** `GET /srs-sip/v1/channels`
**描述：** 获取系统中所有设备的通道信息
**响应格式：** 与2.2接口相同，返回所有设备的通道列表
## 3. 视频流控制接口
### 3.1 发起视频邀请
**接口地址：** `POST /srs-sip/v1/invite`
**描述：** 向指定通道发起视频流邀请
**请求参数：**
```json
{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"media_server_id": 1,
"play_type": 0,
"sub_stream": 0,
"start_time": 1640995200,
"end_time": 1640998800
}
```
**参数说明：**
- `device_id`: 设备ID
- `channel_id`: 通道ID
- `media_server_id`: 媒体服务器ID
- `play_type`: 播放类型（0:实时播放, 1:回放, 2:下载）
- `sub_stream`: 子码流（0:主码流, 1:子码流）
- `start_time`: 开始时间（Unix时间戳，回放时使用）
- `end_time`: 结束时间（Unix时间戳，回放时使用）
**响应示例：**
```json
{
"code": 0,
"data": {
"channel_id": "34020000001320000002",
"url": "rtmp://192.168.1.200:1935/live/34020000001320000002"
}
}
```
### 3.2 结束视频会话
**接口地址：** `POST /srs-sip/v1/bye`
**描述：** 结束指定的视频会话
**请求参数：**
```json
{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"url": "rtmp://192.168.1.200:1935/live/34020000001320000002"
}
```
**响应示例：**
```json
{
"code": 0,
"data": {
"msg": "success"
}
}
```
### 3.3 暂停视频流
**接口地址：** `POST /srs-sip/v1/pause`
**描述：** 暂停指定的视频流
**请求参数：**
```json
{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"url": "rtmp://192.168.1.200:1935/live/34020000001320000002"
}
```
### 3.4 恢复视频流
**接口地址：** `POST /srs-sip/v1/resume`
**描述：** 恢复已暂停的视频流
**请求参数：** 与暂停接口相同
### 3.5 调整播放速度
**接口地址：** `POST /srs-sip/v1/speed`
**描述：** 调整视频播放速度（用于回放）
**请求参数：**
```json
{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"url": "rtmp://192.168.1.200:1935/live/34020000001320000002",
"speed": 2.0
}
```
**参数说明：**
- `speed`: 播放速度倍数（0.5表示0.5倍速，2.0表示2倍速）
## 4. PTZ控制接口
### 4.1 PTZ控制
**接口地址：** `POST /srs-sip/v1/ptz`
**描述：** 控制摄像头的PTZ（云台）功能
**请求参数：**
```json
{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"ptz": "up",
"speed": "5"
}
```
**参数说明：**
- `ptz`: PTZ控制命令
- `up`: 向上
- `down`: 向下
- `left`: 向左
- `right`: 向右
- `zoom_in`: 放大
- `zoom_out`: 缩小
- `stop`: 停止
- `speed`: 控制速度（1-9）
**响应示例：**
```json
{
"code": 0,
"data": {
"msg": "success"
}
}
```
## 5. 录像查询接口
### 5.1 查询录像记录
**接口地址：** `POST /srs-sip/v1/query-record`
**描述：** 查询指定设备通道的录像记录
**请求参数：**
```json
{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"start_time": 1640995200,
"end_time": 1640998800
}
```
**参数说明：**
- `device_id`: 设备ID
- `channel_id`: 通道ID
- `start_time`: 查询开始时间（Unix时间戳）
- `end_time`: 查询结束时间（Unix时间戳）
**响应示例：**
```json
{
"code": 0,
"data": [
{
"device_id": "34020000001320000002",
"name": "录像文件01",
"file_path": "/record/20220101/001.mp4",
"address": "192.168.1.100",
"start_time": "2022-01-01T10:00:00Z",
"end_time": "2022-01-01T11:00:00Z",
"secrecy": 0,
"type": "time"
}
]
}
```
**响应字段说明：**
- `device_id`: 设备ID
- `name`: 录像文件名称
- `file_path`: 录像文件路径
- `address`: 录像文件地址
- `start_time`: 录像开始时间
- `end_time`: 录像结束时间
- `secrecy`: 保密属性（0:不保密, 1:保密）
- `type`: 录像类型
## 6. 媒体服务器管理接口
### 6.1 获取媒体服务器列表
**接口地址：** `GET /srs-sip/v1/media-servers`
**描述：** 获取所有已配置的媒体服务器列表
**响应示例：**
```json
{
"code": 0,
"data": [
{
"id": 1,
"name": "SRS服务器01",
"type": "SRS",
"ip": "192.168.1.200",
"port": 1935,
"username": "admin",
"password": "123456",
"secret": "secret_key",
"is_default": 1,
"created_at": "2022-01-01T10:00:00Z"
}
]
}
```
**响应字段说明：**
- `id`: 媒体服务器ID
- `name`: 服务器名称
- `type`: 服务器类型（SRS、ZLM等）
- `ip`: 服务器IP地址
- `port`: 服务器端口
- `username`: 用户名
- `password`: 密码
- `secret`: 密钥
- `is_default`: 是否为默认服务器（1:是, 0:否）
- `created_at`: 创建时间
### 6.2 添加媒体服务器
**接口地址：** `POST /srs-sip/v1/media-servers`
**描述：** 添加新的媒体服务器配置
**请求参数：**
```json
{
"name": "SRS服务器02",
"type": "SRS",
"ip": "192.168.1.201",
"port": 1935,
"username": "admin",
"password": "123456",
"secret": "secret_key",
"is_default": 0
}
```
**参数说明：**
- `name`: 服务器名称（必填）
- `type`: 服务器类型（必填，支持SRS、ZLM等）
- `ip`: 服务器IP地址（必填）
- `port`: 服务器端口（必填）
- `username`: 用户名（可选）
- `password`: 密码（可选）
- `secret`: 密钥（可选）
- `is_default`: 是否设为默认服务器（可选，默认为0）
**响应示例：**
```json
{
"code": 0,
"data": {
"msg": "success"
}
}
```
### 6.3 删除媒体服务器
**接口地址：** `DELETE /srs-sip/v1/media-servers/{id}`
**描述：** 删除指定的媒体服务器配置
**路径参数：**
- `id`: 媒体服务器ID
**响应示例：**
```json
{
"code": 0,
"data": {
"msg": "success"
}
}
```
### 6.4 设置默认媒体服务器
**接口地址：** `POST /srs-sip/v1/media-servers/default/{id}`
**描述：** 将指定的媒体服务器设置为默认服务器
**路径参数：**
- `id`: 媒体服务器ID
**响应示例：**
```json
{
"code": 0,
"data": {
"msg": "success"
}
}
```
## 7. 错误码说明
| 错误码 | HTTP状态码 | 说明 |
|--------|------------|------|
| 0 | 200 | 成功 |
| 400 | 400 | 请求参数错误 |
| 500 | 500 | 服务器内部错误 |
## 8. 使用示例
### 8.1 获取设备列表并播放视频
```bash
# 1. 获取设备列表
curl -X GET "http://localhost:8080/srs-sip/v1/devices"
# 2. 获取设备通道
curl -X GET "http://localhost:8080/srs-sip/v1/devices/34020000001320000001/channels"
# 3. 发起视频邀请
curl -X POST "http://localhost:8080/srs-sip/v1/invite" \
-H "Content-Type: application/json" \
-d '{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"media_server_id": 1,
"play_type": 0,
"sub_stream": 0
}'
```
### 8.2 PTZ控制示例
```bash
# 控制摄像头向上移动
curl -X POST "http://localhost:8080/srs-sip/v1/ptz" \
-H "Content-Type: application/json" \
-d '{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"ptz": "up",
"speed": "5"
}'
# 停止PTZ控制
curl -X POST "http://localhost:8080/srs-sip/v1/ptz" \
-H "Content-Type: application/json" \
-d '{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"ptz": "stop",
"speed": "0"
}'
```
### 8.3 录像查询和回放示例
```bash
# 查询录像记录
curl -X POST "http://localhost:8080/srs-sip/v1/query-record" \
-H "Content-Type: application/json" \
-d '{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"start_time": 1640995200,
"end_time": 1640998800
}'
# 回放录像
curl -X POST "http://localhost:8080/srs-sip/v1/invite" \
-H "Content-Type: application/json" \
-d '{
"device_id": "34020000001320000001",
"channel_id": "34020000001320000002",
"media_server_id": 1,
"play_type": 1,
"start_time": 1640995200,
"end_time": 1640998800
}'
```
## 9. 注意事项
1. **设备ID格式**：设备ID需要符合GB28181标准，通常为20位数字
2. **时间格式**：所有时间参数使用Unix时间戳格式
3. **媒体服务器**：在发起视频邀请前，需要确保已配置可用的媒体服务器
4. **网络连接**：确保SIP服务器与设备、媒体服务器之间网络连通
5. **权限控制**：部分接口可能需要认证，具体根据系统配置而定
6. **设备状态**：只有在线状态的设备才能进行视频邀请和PTZ控制
7. **并发限制**：同一通道同时只能有一个活跃的视频会话
## 10. 常见问题
### Q1: 设备离线怎么办？
A: 检查设备网络连接，确保设备能正常发送心跳包到SIP服务器。
### Q2: 视频邀请失败？
A: 检查媒体服务器状态，确保设备支持对应的编码格式。
### Q3: PTZ控制无响应？
A: 确认设备支持PTZ功能，检查PTZ控制命令格式是否正确。
## 11. 更新日志
- **v1.0.0** (2024-01-01): 初始版本，包含基础的设备管理、视频控制、PTZ控制功能

2
main/main.go
View File

@ -54,7 +54,7 @@ func main() {
slog.Info("*****************************************************")
slog.Info(" ☆☆☆ 欢迎使用 SRS-SIP 服务 ☆☆☆")
slog.Info("*****************************************************")
slog.Info("srs-sip service starting", "config", *configPath, "log_file", conf.Common.LogFile)
slog.Info("srs-sip service starting", "config", *configPath, "log_file", conf.Common.LogFile, "log_level", conf.Common.LogLevel)
sipSvr, err := service.NewService(ctx, conf)
if err != nil {