GB28181 服务器 - Monibuca 国标视频监控

GB28181 是中国国家标准《安全防范视频监控联网系统信息传输、交换、控制技术要求》（GB/T 28181），广泛应用于视频监控系统的互联互通。Monibuca V6 提供完整的 GB28181 信令和媒体支持。

HTTP API（内嵌）

默认基地址：http://localhost:8180
路由前缀：/gb28181/api

最小可用调用序列（3 步）

# 1) 设备列表
curl http://localhost:8180/gb28181/api/devices

# 2) 通道列表
curl http://localhost:8180/gb28181/api/channels

# 3) PTZ 控制（左转）— 路径含 deviceId
curl -X POST http://localhost:8180/gb28181/api/devices/34020000001110000001/ptz \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "34020000001320000001",
    "cmd": "left",
    "param": 1,
    "speed": 50
  }'

常用接口清单

模块	方法	路径	说明
设备	GET	/gb28181/api/devices	设备列表
设备	POST	/gb28181/api/devices	预登记设备
设备	GET	/gb28181/api/devices/{id}	设备详情
设备	PUT	/gb28181/api/devices/{id}	更新设备
设备	DELETE	/gb28181/api/devices/{id}	删除设备
设备	POST	/gb28181/api/devices/{id}/refresh	刷新设备通道
通道	GET	/gb28181/api/channels	通道列表
通道	POST	/gb28181/api/channel/add	添加通道
通道	DELETE	/gb28181/api/channel/delete/{id}	删除通道
流控制	POST	/gb28181/api/devices/{id}/invite	邀请设备推流
流控制	POST	/gb28181/api/devices/{id}/bye	停止设备推流
PTZ	POST	/gb28181/api/devices/{id}/ptz	云台控制
录像	GET	/gb28181/api/devices/{id}/records	录像查询
录像	POST	/gb28181/api/devices/{id}/playback	开始回放
录像	POST	/gb28181/api/recording	平台侧录制控制
平台级联	GET	/gb28181/api/platforms	平台列表
平台级联	POST	/gb28181/api/platform/add	新增平台
平台级联	POST	/gb28181/api/platform/channel/shared	共享通道到平台

基本信息

属性	值
信令协议	SIP（UDP/TCP 可选）
信令端口	5060（默认）
媒体协议	RTP over UDP
媒体端口	10000-20000（默认范围）
推流	✅ 支持（设备推流到平台）
拉流	✅ 支持（平台向设备请求流）
延迟	1-3 秒
配置节	gb28181

功能特性

• 设备注册与管理：支持设备注册、心跳保活、目录查询
• 实时视频：支持设备实时视频预览
• 云台控制（PTZ）：支持上下左右旋转、变焦、预置位等
• 通道管理：支持多通道设备，独立管理每个通道
• 平台级联：支持上下级平台对接
• 录像查询与回放：支持设备端录像检索和远程回放
• 录像下载：支持从设备下载历史录像
• WebSocket 通知：实时推送设备状态变化

配置

启用插件

预编译二进制已内置该插件，在 config.yaml 中配置即可：

配置文件

gb28181:
  enable: true
  sip:
    - domain: "3402000000"
      domain_id: "34020000002000000001"
      username: "34020000002000000001"
      password: "your_sip_password"
      digest_retry_limit: 2
      digest_stale_retry_limit: 2
      lan_ip: "192.168.1.100"
      wan_ip: "203.0.113.1"
      port: 5060
      network: udp
  rtp_port_min: 10000
  rtp_port_max: 20000
  heartbeat_timeout: 60
  register_timeout: 300
  download_storage_path: "./downloads"
  download_retention_days: 7

SIP 服务器配置

配置项	类型	默认值	说明
domain	string	"3402000000"	SIP 域名（行政区划编码）
domain_id	string	"34020000002000000001"	SIP 域 ID（20 位编码）
username	string?	null	Digest 认证用户名（可选）
password	string?	null	Digest 认证密码（可选）
digest_retry_limit	u8	2	普通 401 挑战最大重试次数
digest_stale_retry_limit	u8	2	stale=true 挑战最大重试次数
lan_ip	string	"127.0.0.1"	SIP 内网 IP
wan_ip	string	"127.0.0.1"	SIP 公网 IP（NAT 穿透用）
port	u16	5060	SIP 信令端口
network	string	"udp"	网络协议（udp 或 tcp）

全局配置

配置项	类型	默认值	说明
enable	bool	true	是否启用插件
rtp_port_min	u16	10000	RTP 媒体端口范围起始
rtp_port_max	u16	20000	RTP 媒体端口范围结束
heartbeat_timeout	u64	60	心跳超时时间（秒）
register_timeout	u64	300	注册超时时间（秒）
alert_ws_keepalive_timeout_secs	u64?	未设置	告警 WebSocket 空闲断开超时（秒）；省略或 0 表示禁用服务端保活
download_storage_path	string	"./downloads"	录像下载存储路径
download_retention_days	i64	7	下载文件保留天数

提示

RTP 端口采用按需分配策略，不会预先占用所有端口。只有在建立媒体会话时才从端口池中分配可用端口。

设备接入

设备编码规则

GB28181 设备 ID 遵循 20 位编码规则：

中心编码(8位) + 行业编码(2位) + 类型编码(3位) + 序号(7位)

例如：34020000001320000001

• 34020000：行政区划编码（安徽省）
• 00：行业编码
• 132：类型编码（IPC 摄像机）
• 0000001：序号

设备注册流程

sequenceDiagram
  participant D as 设备
  participant S as Monibuca (SIP Server)
  D->>S: REGISTER
  S-->>D: 401 Unauthorized
  D->>S: REGISTER (Auth)
  S-->>D: 200 OK
  D->>S: 心跳 (MESSAGE)
  S-->>D: 200 OK

设备配置示例

在摄像头或 NVR 的国标配置页面，填写以下信息：

参数	值	说明
SIP 服务器 ID	34020000002000000001	对应配置中的 domain_id
SIP 服务器域	3402000000	对应配置中的 domain
SIP 服务器地址	192.168.1.100	Monibuca 服务器 IP
SIP 服务器端口	5060	对应配置中的 port
设备编号	34020000001320000001	设备自身的 20 位编码
传输协议	UDP	对应配置中的 network

云台控制（PTZ）

支持的 PTZ 操作：

操作	说明
方向控制	上、下、左、右、左上、左下、右上、右下
变焦控制	放大、缩小
光圈控制	打开、关闭
预置位	设置、调用、删除预置位

PTZ 控制通过 /gb28181/api/devices/{id}/ptz 调用（见上方清单）。

通道管理

GB28181 设备可以有多个通道（如 NVR 下挂多个摄像头）。Monibuca 支持：

• 自动发现设备通道（通过 Catalog 查询）
• 对每个通道独立发起实时预览
• 对每个通道独立进行 PTZ 控制
• 通道状态实时更新

平台级联

Monibuca 可以作为下级平台，向上级平台注册并推送流数据：

下级设备 → Monibuca (下级平台) → 上级平台

级联功能支持：

• 向上级平台注册
• 响应上级平台的目录查询
• 按需向上级平台推送实时流
• 同步设备状态变化

录像查询与回放

查询设备端录像

通过 GB28181 信令查询设备端的历史录像列表，支持按时间范围和录像类型过滤。

远程回放

支持从设备端拉取历史录像进行回放，支持：

• 正常播放
• 快进 / 慢放
• 定位（Seek）
• 暂停 / 恢复

录像下载

支持将设备端的历史录像下载到本地存储，下载完成后自动保存到配置的存储路径。

WebSocket

设备事件推送

实时推送设备/通道上线离线、目录（通道）更新、报警等：

const ws = new WebSocket('ws://localhost:8180/gb28181/ws?clientId=admin');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // 协议帧：{ "action": "connected" | "ping" | "pong" | "error", ... }
  // 业务事件：{ "type": "deviceOnline" | "deviceOffline" | "channelOnline" | "channelOffline" | "heartbeatTimeout" | "catalogUpdate" | "alarm", ... }
  if (data.action === 'ping') {
    // 服务端保活探测：必须回 pong（timestamp 原样带回）
    ws.send(JSON.stringify({ action: 'pong', timestamp: data.timestamp ?? Date.now() }));
    return;
  }
  console.log('GB28181 事件:', data);
};

type	说明	主要字段
deviceOnline	设备注册成功或心跳恢复上线	deviceId, status, timestamp
deviceOffline / heartbeatTimeout	设备心跳超时离线	deviceId, status, timestamp, 可选 reason
channelOnline	通道状态变为在线（仅状态变化时推送）	deviceId, channelId, status, timestamp
channelOffline	通道状态变为离线（仅状态变化时推送）	deviceId, channelId, status, timestamp
catalogUpdate	通道目录同步完成	deviceId, timestamp, data.channelCount
alarm	设备报警	deviceId, 可选 channelId, 报警字段

通道事件示例：

{ "type": "channelOnline", "deviceId": "34020000001110000001", "channelId": "34020000001320000001", "status": "Online", "timestamp": 1710000000000 }

连接保活：默认禁用服务端保活（配置项 alert_ws_keepalive_timeout_secs 省略或为 0），连接不会因空闲被服务端断开。启用时（例如设为 60），服务端按约 min(30, max(1, N/2)) 秒间隔发送应用层 { "action": "ping", "timestamp": <unix_ms> }，客户端应回复 { "action": "pong", "timestamp": <same> }；空闲超过 N 秒未收到客户端响应则断开。WebSocket 协议层 Pong 同样有效。为兼容旧客户端，服务端仍接受客户端主动 { "type": "ping" } / { "action": "ping" }（并回 pong），但新接入应以服务端 ping / 客户端 pong 为准。

可选查询参数：clientId（连接标识）。裸路径 /gb28181 不会升级；必须使用 /gb28181/ws。

裸 MPEG-PS 播放

当 relay_mode 为 dual 或 forward 时，可通过 WebSocket 订阅裸 PS：

ws://localhost:8180/ps/{streamPath}

例如流路径 gb28181/34020000001320000001 → ws://localhost:8180/ps/gb28181/34020000001320000001。

跨协议播放

GB28181 设备推送的流可以通过其他协议播放：

# 通过 HTTP-FLV 播放设备流
ffplay http://localhost:8180/flv/gb28181/34020000001320000001.flv

# 通过 HLS 播放
ffplay http://localhost:8180/hls/gb28181/34020000001320000001/index.m3u8

# 通过 RTMP 播放
ffplay rtmp://localhost:1935/gb28181/34020000001320000001

防火墙配置

部署 GB28181 服务需要开放以下端口：

# SIP 信令端口
sudo ufw allow 5060/udp

# RTP 媒体端口范围
sudo ufw allow 10000:20000/udp

警告

如果在 NAT 环境下部署，请确保 wan_ip 配置正确，否则设备可能无法将媒体流发送到正确的地址。