doc: update readme

This commit is contained in:
langhuihui
2025-05-15 09:27:36 +08:00
parent 73e101bc6c
commit ecc3947016
3 changed files with 489 additions and 2 deletions

View File

@@ -10,6 +10,9 @@
<!-- PROJECT LOGO -->
<br />
<div align="center">
<a href="https://m7s.live">
<img src="https://m7s.live/logo+.svg" alt="Logo" width="200">
</a>
<h1 align="center">Monibuca v5</h1>
<p align="center">

View File

@@ -8,11 +8,11 @@
[![Issues][issues-shield]][issues-url]
[![AGPL License][license-shield]][license-url]
[![Go Reference](https://pkg.go.dev/badge/m7s.live/v5.svg)](https://pkg.go.dev/m7s.live/v5)
<a href="https://hellogithub.com/repository/6d7916d851c2481f87568ffd9f1c21d9" target="_blank"><img src="https://api.hellogithub.com/v1/widgets/recommend.svg?rid=6d7916d851c2481f87568ffd9f1c21d9&claim_uid=riBYPOGenUf7kbc&theme=small" alt="FeaturedHelloGitHub" /></a>
<br />
<div align="center">
<a href="https://monibuca.com">
<img src="https://monibuca.com/svg/logo.svg" alt="Logo" width="200">
<img src="https://monibuca.com/logo+.svg" alt="Logo" width="200">
</a>
<h1 align="center">Monibuca v5</h1>

484
plugin/gb28181/README.md Normal file
View File

@@ -0,0 +1,484 @@
# GB28181协议
GB28181协议全称GB/T 28181《公共安全视频监控联网系统信息传输、交换、控制技术要求》是中国公共安全领域的国家标准旨在规范视频监控设备间的互联互通实现统一管理和数据安全传输。本文档描述了 Monibuca (m7s) 流媒体服务器中 GB28181 协议的实现,重点介绍协议的架构、连接处理和媒体流传输功能。
## 架构概述
Monibuca 中的 GB28181 被构建为一个插件,支持下级 GB28181 设备注册到 Monibuca (m7s),并在 Monibuca (m7s) 内部进行多协议的直播和录像点播,能通过 http 接口对下级设备进行云台控制,录像控制,播放控制,预置位设置,订阅报警、目录、移动位置,同时支持级联上级设备,供上级设备播放、录像点播放等功能。该插件默认在 554 端口注册标准 GB28181 服务收流端口默认范围是10001-20000,并可以配置使用自定义端口。
### 核心组件
| 组件 |描述 |
|----------|:----|
| GB28181Plugin | 主插件结构,包含配置和初始化逻辑 |
| Device | 下级设备 |
| Channel | 设备下的通道 |
| Platform | 上级设备 |
## GB28181协议流程
### 与下级设备
#### 注册相关
1. 下级设备向 GB28181 插件发起注册请求
2. GB28181 插件向下级设备获取设备信息及通道信息
3. 下级设备向 GB28181 插件定时发送保活请求
```mermaid
sequenceDiagram
participant D as 下级设备
participant P as GB28181插件 (Monibuca)
D->>P: 发起注册请求 (SIP REGISTER)
P->>D: 请求设备信息 (SIP MESSAGE - Catalog)
D->>P: 回复设备信息和通道信息
loop 定时保活
D->>P: 发送保活请求 (SIP MESSAGE - Keepalive)
P->>D: 回复保活响应
end
```
#### 播放直播
1. 从播放请求里获取目标设备ID和通道ID
2. 向目标设备发送invite请求
3. 下级设备通过invite请求内的参数向 GB28181 插件发送流媒体数据
```mermaid
sequenceDiagram
participant U as 用户/上层应用
participant P as GB28181插件 (Monibuca)
participant D as 下级设备
U->>P: 播放请求 (HTTP API 或其他方式)
P->>D: 发送 INVITE 请求 (携带媒体参数)
D->>P: 回复 INVITE 响应 (e.g., 200 OK)
D->>P: 发送流媒体数据 (RTP/PS)
P->>U: 转发流媒体数据
```
#### 播放录像
1. 从播放请求里获取目标设备ID和通道ID及录像的开始时间和结束时间
2. 向目标设备发送invite请求,invite请求里设置录像的开始时间和结束时间
3. 下级设备通过invite请求内的参数向 GB28181 插件发送流媒体数据
```mermaid
sequenceDiagram
participant U as 用户/上层应用
participant P as GB28181插件 (Monibuca)
participant D as 下级设备
U->>P: 播放录像请求 (HTTP API, 指定时间范围)
P->>D: 发送 INVITE 请求 (携带录像时间范围 sdp)
D->>P: 回复 INVITE 响应 (e.g., 200 OK)
D->>P: 发送录像流媒体数据 (RTP/PS)
P->>U: 转发录像流媒体数据
```
### 与上级设备
#### 注册相关
1. 通过接口添加上级设备的连接信息
2. GB28181 插件向上级设备发起注册
3. 注册成功后定时发送请求保活
```mermaid
sequenceDiagram
participant P as GB28181插件 (Monibuca)
participant S as 上级设备
P->>S: 发起注册请求 (SIP REGISTER)
S->>P: 回复注册响应 (e.g., 200 OK)
loop 定时保活
P->>S: 发送保活请求 (SIP MESSAGE - Keepalive)
S->>P: 回复保活响应
end
```
#### 播放直播
1. 上级设备向 GB28181 插件发起invite请求
2. GB28181插件 从invite请求中解析出下级设备的设备ID和通道ID
3. 向下级目标设备发送invite请求
4. 得到正确回应后,接收下级设备的流媒体数据并转发至上级设备
```mermaid
sequenceDiagram
participant S as 上级设备
participant P as GB28181插件 (Monibuca)
participant D as 下级设备
S->>P: 发起 INVITE 请求 (指定设备ID和通道ID)
P->>D: 发送 INVITE 请求 (向下级设备请求流)
D->>P: 回复 INVITE 响应 (e.g., 200 OK)
D->>P: 发送流媒体数据 (RTP/PS)
P->>S: 转发流媒体数据
```
#### 播放录像
1. 上级设备向 GB28181 插件发起invite请求
2. GB28181插件 从invite请求中解析出下级设备的设备ID和通道ID以及录像的开始时间和结束时间
3. 向下级目标设备发送invite请求,invite请求里设置录像的开始时间和结束时间
4. 得到正确回应后,接收下级设备的流媒体数据并转发至上级设备
```mermaid
sequenceDiagram
participant S as 上级设备
participant P as GB28181插件 (Monibuca)
participant D as 下级设备
S->>P: 发起 INVITE 请求 (指定设备ID、通道ID和时间范围)
P->>D: 发送 INVITE 请求 (向下级设备请求录像流, 包含时间范围 sdp)
D->>P: 回复 INVITE 响应 (e.g., 200 OK)
D->>P: 发送录像流媒体数据 (RTP/PS)
P->>S: 转发录像流媒体数据
```
## 配置和初始化
```yaml
gb28181:
mediaip: 10.15.94.58 #流媒体收流IP,必填
sipip: 10.15.94.58 #SIP通讯IP,必填
mediaport: "10001-20000" #默认收流端口范围,可选
serial: "34020000002000000001" #服务器serverid,可选
realm: "3402000000" #服务器域,可选
password: "123456" #设备验证密码,可选
sip:
listenaddr:
- udp::15060 #SIP通讯端口,必填
onsub:
pull:
^gb_\d+/(.+)$: $1 #播放GB设备请求URL的正则,例如deviceid,channelid分别为34020000001110000003,34020000001320000003,则在系统内的地址为http://localhost:8080/flv/gb_1/34020000001110000003/34020000001320000003.flv,其他协议类同
```
## API接口说明
GB28181插件的API通过gRPC提供并映射到HTTP接口。以下是主要的API端点及其功能均基于 `gb28181.proto` 定义:
### 设备管理 (Device Management)
- **`GET /gb28181/api/list`**
- 描述: 获取设备列表 (同 `GetDevices`)。
- RPC: `List(GetDevicesRequest) returns (DevicesPageInfo)`
- 请求参数: `GetDevicesRequest`
- `page` (int32, 可选): 页码。
- `count` (int32, 可选): 每页数量。
- `query` (string, 可选): 查询关键字 (设备ID或名称)。
- `status` (bool, 可选): 设备在线状态。
- 响应: `DevicesPageInfo`
- **`GET /gb28181/api/devices/{deviceId}`**
- 描述: 使用ID查询国标设备信息。
- RPC: `GetDevice(GetDeviceRequest) returns (DeviceResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- 响应: `DeviceResponse`
- **`GET /gb28181/api/devices`**
- 描述: 分页查询国标设备。
- RPC: `GetDevices(GetDevicesRequest) returns (DevicesPageInfo)`
- 请求参数: `GetDevicesRequest` (同上 `List`)
- 响应: `DevicesPageInfo`
- **`DELETE /gb28181/api/devices/{deviceId}/delete`**
- 描述: 移除设备。
- RPC: `DeleteDevice(DeleteDeviceRequest) returns (DeleteDeviceResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- 响应: `DeleteDeviceResponse`
- **`POST /gb28181/api/device/add`**
- 描述: 添加设备信息。
- RPC: `AddDevice(Device) returns (BaseResponse)`
- 请求体: `Device` message
- 响应: `BaseResponse`
- **`POST /gb28181/api/device/update`**
- 描述: 更新设备信息。
- RPC: `UpdateDevice(Device) returns (BaseResponse)`
- 请求体: `Device` message
- 响应: `BaseResponse`
- **`GET /gb28181/api/devices/{deviceId}/status`**
- 描述: 设备状态查询。
- RPC: `GetDeviceStatus(GetDeviceStatusRequest) returns (DeviceStatusResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- 响应: `DeviceStatusResponse`
### 通道管理 (Channel Management)
- **`GET /gb28181/api/devices/{deviceId}/channels`**
- 描述: 分页查询指定设备的通道。
- RPC: `GetChannels(GetChannelsRequest) returns (ChannelsPageInfo)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- 请求参数: `GetChannelsRequest`
- `page` (int32, 可选): 页码。
- `count` (int32, 可选): 每页数量。
- `query` (string, 可选): 查询关键字 (通道ID或名称)。
- `online` (bool, 可选): 通道在线状态。
- `channelType` (bool, 可选): 是否为设备通道。
- 响应: `ChannelsPageInfo`
- **`GET /gb28181/api/devices/{deviceId}/sync`**
- 描述: 同步设备通道信息。
- RPC: `SyncDevice(SyncDeviceRequest) returns (SyncStatus)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- 响应: `SyncStatus`
- **`GET /gb28181/api/sub_channels/{deviceId}/{channelId}/channels`**
- 描述: 分页查询子目录通道。
- RPC: `GetSubChannels(GetSubChannelsRequest) returns (ChannelsPageInfo)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- `channelId` (string, 必选): 父通道ID。
- 响应: `ChannelsPageInfo`
- **`POST /gb28181/api/channel/audio`**
- 描述: 开启/关闭通道的音频。
- RPC: `ChangeAudio(ChangeAudioRequest) returns (BaseResponse)`
- 请求体: `ChangeAudioRequest`
- 响应: `BaseResponse`
- **`POST /gb28181/api/channel/stream/identification/update`**
- 描述: 修改通道的码流类型。
- RPC: `UpdateChannelStreamIdentification(Channel) returns (BaseResponse)`
- 请求体: `Channel` message
- 响应: `BaseResponse`
- **`GET /gb28181/api/channel/raw`**
- 描述: 国标通道编辑时的数据回显。
- RPC: `GetRawChannel(GetRawChannelRequest) returns (Channel)`
- 请求参数: `GetRawChannelRequest`
- 响应: `Channel`
### 播放与录像 (Playback and Recording)
- **`GET /gb28181/api/records/{deviceId}/{channelId}`**
- 描述: 查询录像记录。
- RPC: `QueryRecord(QueryRecordRequest) returns (QueryRecordResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- `channelId` (string, 必选): 通道ID。
- 请求参数: `QueryRecordRequest` (包含开始/结束时间等)
- 响应: `QueryRecordResponse`
- **`GET /gb28181/api/recording/{cmdType}/{deviceId}/{channelId}`**
- 描述: 录制控制 (开始/停止)。
- RPC: `Recording(RecordingRequest) returns (BaseResponse)`
- URL参数:
- `cmdType` (string, 必选): 命令类型 ("start" 或 "stop")。
- `deviceId` (string, 必选): 设备ID。
- `channelId` (string, 必选): 通道ID。
- 响应: `BaseResponse`
- **`GET /gb28181/api/playback/pause`**
- 描述: 回放暂停。
- RPC: `PlaybackPause(PlaybackPauseRequest) returns (BaseResponse)`
- 请求参数: `PlaybackPauseRequest`
- 响应: `BaseResponse`
- **`GET /gb28181/api/playback/resume`**
- 描述: 回放恢复。
- RPC: `PlaybackResume(PlaybackResumeRequest) returns (BaseResponse)`
- 请求参数: `PlaybackResumeRequest`
- 响应: `BaseResponse`
- **`GET /gb28181/api/playback/seek`**
- 描述: 回放拖动播放。
- RPC: `PlaybackSeek(PlaybackSeekRequest) returns (BaseResponse)`
- 请求参数: `PlaybackSeekRequest` (包含目标时间)
- 响应: `BaseResponse`
- **`GET /gb28181/api/playback/speed`**
- 描述: 回放倍速播放。
- RPC: `PlaybackSpeed(PlaybackSpeedRequest) returns (BaseResponse)`
- 请求参数: `PlaybackSpeedRequest` (包含播放速度)
- 响应: `BaseResponse`
### 云台控制 (PTZ Control)
- **`GET /gb28181/api/ptz/{deviceId}/{channelId}`**
- 描述: PTZ 云台控制。
- RPC: `PtzControl(PtzControlRequest) returns (BaseResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- `channelId` (string, 必选): 通道ID。
- 请求参数: `PtzControlRequest` (包含PTZ命令如 "UP", "DOWN", "ZOOM_IN" 等)
- 响应: `BaseResponse`
- **`GET /gb28181/api/fi/iris/{deviceId}/{channelId}`**
- 描述: 光圈控制。
- RPC: `IrisControl(IrisControlRequest) returns (BaseResponse)`
- URL参数 & 请求参数: 类似于PTZ控制。
- 响应: `BaseResponse`
- **`GET /gb28181/api/fi/focus/{deviceId}/{channelId}`**
- 描述: 聚焦控制。
- RPC: `FocusControl(FocusControlRequest) returns (BaseResponse)`
- URL参数 & 请求参数: 类似于PTZ控制。
- 响应: `BaseResponse`
- **`GET /gb28181/api/preset/query/{deviceId}/{channelId}`**
- 描述: 查询预置位。
- RPC: `QueryPreset(PresetRequest) returns (PresetResponse)`
- URL参数 & 请求参数: 类似于PTZ控制。
- 响应: `PresetResponse`
- **`GET /gb28181/api/preset/{deviceId}/{channelId}`**
- 描述: 设置预置位。
- RPC: `AddPreset(PresetRequest) returns (BaseResponse)`
- URL参数 & 请求参数: 类似于PTZ控制。
- 响应: `BaseResponse`
- **`GET /gb28181/api/preset/call/{deviceId}/{channelId}`**
- 描述: 调用预置位。
- RPC: `CallPreset(PresetRequest) returns (BaseResponse)`
- URL参数 & 请求参数: 类似于PTZ控制。
- 响应: `BaseResponse`
- **`GET /gb28181/api/preset/delete/{deviceId}/{channelId}`**
- 描述: 删除预置位。
- RPC: `DeletePreset(PresetRequest) returns (BaseResponse)`
- URL参数 & 请求参数: 类似于PTZ控制。
- 响应: `BaseResponse`
- **其他PTZ相关控制**: 巡航 (Cruise), 扫描 (Scan), 雨刷 (Wiper), 辅助开关 (Auxiliary) 等其API格式与上述类似具体请参照 `gb28181.proto`
### 平台管理 (Platform Management)
- **`POST /gb28181/api/platform/add`**
- 描述: 添加平台信息。
- RPC: `AddPlatform(Platform) returns (BaseResponse)`
- 请求体: `Platform` message
- 响应: `BaseResponse`
- **`GET /gb28181/api/platform/{id}`**
- 描述: 获取平台信息。
- RPC: `GetPlatform(GetPlatformRequest) returns (PlatformResponse)`
- URL参数:
- `id` (string, 必选): 平台ID。
- 响应: `PlatformResponse`
- **`POST /gb28181/api/platform/update`**
- 描述: 更新平台信息。
- RPC: `UpdatePlatform(Platform) returns (BaseResponse)`
- 请求体: `Platform` message
- 响应: `BaseResponse`
- **`POST /gb28181/api/platform/{id}`**
- 描述: 删除平台信息。
- RPC: `DeletePlatform(DeletePlatformRequest) returns (BaseResponse)`
- URL参数:
- `id` (string, 必选): 平台ID。
- 响应: `BaseResponse`
- **`GET /gb28181/api/platform/list`**
- 描述: 获取平台列表。
- RPC: `ListPlatforms(ListPlatformsRequest) returns (PlatformsPageInfo)`
- 请求参数: `ListPlatformsRequest` (可包含分页等)
- 响应: `PlatformsPageInfo`
- **`POST /gb28181/api/platform/channel/add`**
- 描述: 添加平台通道。
- RPC: `AddPlatformChannel(AddPlatformChannelRequest) returns (BaseResponse)`
- 请求体: `AddPlatformChannelRequest`
- 响应: `BaseResponse`
### 其他功能 (Other Functions)
- **`POST /gb28181/api/transport/{deviceId}/{streamMode}`**
- 描述: 修改数据流传输模式 (TCP/UDP)。
- RPC: `UpdateTransport(UpdateTransportRequest) returns (BaseResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- `streamMode` (string, 必选): 流模式 ("TCP" 或 "UDP")。
- 响应: `BaseResponse`
- **`GET /gb28181/api/alarm/{deviceId}`**
- 描述: 设备报警查询。
- RPC: `GetDeviceAlarm(GetDeviceAlarmRequest) returns (DeviceAlarmResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- 请求参数: `GetDeviceAlarmRequest` (可包含时间范围、报警级别等)
- 响应: `DeviceAlarmResponse`
- **`GET /gb28181/api/{deviceId}/sync_status`**
- 描述: 获取通道同步进度。
- RPC: `GetSyncStatus(GetSyncStatusRequest) returns (SyncStatus)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- 响应: `SyncStatus`
- **`GET /gb28181/api/{deviceId}/subscribe_info`**
- 描述: 获取设备的订阅状态。
- RPC: `GetSubscribeInfo(GetSubscribeInfoRequest) returns (SubscribeInfoResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- 响应: `SubscribeInfoResponse`
- **`GET /gb28181/api/snap/{deviceId}/{channelId}`**
- 描述: 请求截图。
- RPC: `GetSnap(GetSnapRequest) returns (SnapResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- `channelId` (string, 必选): 通道ID。
- 响应: `SnapResponse` (通常包含图片URL或数据)
- **`POST /gb28181/api/play/convertStop/{key}`**
- 描述: 结束转码。
- RPC: `StopConvert(ConvertStopRequest) returns (BaseResponse)`
- URL参数:
- `key` (string, 必选): 转码任务的标识。
- 响应: `BaseResponse`
- **`POST /gb28181/api/play/broadcast/{deviceId}/{channelId}`**
- 描述: 语音广播命令。
- RPC: `StartBroadcast(BroadcastRequest) returns (BroadcastResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- `channelId` (string, 必选): 通道ID。
- 响应: `BroadcastResponse`
- **`POST /gb28181/api/play/broadcast/stop/{deviceId}/{channelId}`**
- 描述: 停止语音广播。
- RPC: `StopBroadcast(BroadcastRequest) returns (BaseResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- `channelId` (string, 必选): 通道ID。
- 响应: `BaseResponse`
- **`GET /gb28181/api/play/ssrc`**
- 描述: 获取所有的SSRC。
- RPC: `GetAllSSRC(google.protobuf.Empty) returns (SSRCListResponse)`
- 响应: `SSRCListResponse`
- **`GET /gb28181/api/testsip`**
- 描述: 测试SIP连接。
- RPC: `TestSip(TestSipRequest) returns (TestSipResponse)`
- 请求参数: `TestSipRequest`
- 响应: `TestSipResponse`
- **`GET /gb28181/api/alarms/{deviceId}`**
- 描述: 分页查询报警记录。
- RPC: `SearchAlarms(SearchAlarmsRequest) returns (SearchAlarmsResponse)`
- URL参数:
- `deviceId` (string, 必选): 设备ID。
- 请求参数: `SearchAlarmsRequest` (可包含分页、时间范围等)
- 响应: `SearchAlarmsResponse`
- **`POST /gb28181/api/snap/upload`**
- 描述: 接收JPEG文件。
- RPC: `UploadJpeg(UploadJpegRequest) returns (BaseResponse)`
- 请求体: `UploadJpegRequest` (包含图片数据)
- 响应: `BaseResponse`
- **分组管理 (Group Management)**: 包括获取、添加、更新、删除分组以及分组与通道的关联管理。具体API请参照 `gb28181.proto` 中的 `GetGroups`, `AddGroup`, `UpdateGroup`, `DeleteGroup`, `AddGroupChannel`, `DeleteGroupChannel`, `GetGroupChannels`
**注意:** 上述列表可能未包含所有API详细信息请直接查阅 `plugin/gb28181/pb/gb28181.proto` 文件。请求和响应的具体字段结构也定义在该 proto 文件中。
## 总结
Monibuca 中的 GB28181 插件支持:
1. 下级设备直播播放,录像查询,录像播放,录像播放暂停(恢复),录像播放倍速,预置位设置,云台控制,订阅目录、移动位置、报警
2. 向上级设备注册及保活,上级设备直播播放,录像查询,录像播放,云台控制,预置位设置,等功能