国标接入

开放平台可选接入 GB28181 国标视频：把国标设备（IPC / NVR）或上级国标平台的通道，作为 AI 任务、网页预览与直播比对的视频源。启用后，任务侧只需把视频地址写成逻辑地址 gb28181://<channelID>（20 位国标通道 ID），由平台完成 SIP 点播、RTP 收流与 PS 解封装，无需额外的流媒体网关。uas 角色只面向设备侧注册与取流，不向其他平台提供点播（收到 INVITE 回 501，见「注意事项」）。

该功能默认关闭（gb28181.enable=false），关闭时不监听端口；仅在需要接入国标视频源时开启。配置在安装目录的 config.yaml（默认 /opt/zhimou/config.yaml）的 gb28181 段，修改后需重启服务生效。config.yaml 的整体结构与其余段落见运维配置。

角色与必填项

role 决定平台站在国标链路的哪一端，两种角色的必填项不同：

uac（缺省）：作为下级平台向上级国标平台注册，由本平台发起点播。必填 remote_addr（上级 SIP 地址）与 password（我方作为客户端出示的注册口令）。

uas：作为上级平台接受设备 / IPC 的注册与心跳、查询通道目录，由本平台向设备发 INVITE 收流。必填 device_password（设备注册口令缺省值）或 device_passwords（按设备 ID 单独配置，只填这张表即等于设备白名单）。

还有一种中间级联角色 cascade（既收下级设备注册，也向上级平台注册并把点播转发下去）。

缺少对应角色的口令时启动即被拒绝（而非运行后静默失效），日志会打印原因——这是为避免「谁都能把流推过来」的刻意设计。

端口与防火墙

GB28181 会额外用到下列端口，不在 install.sh 安装前检查的 9 个端口之列，需自行确保空闲并按下表放行：

端口	协议	用途	是否需对外放行
`listen_addr`（缺省 `5060`）	UDP	SIP 信令：注册 / 心跳 / 点播（信令固定 UDP，`transport` 只影响媒体面）	需与对端（上级平台或设备）互通
`rtp_port_range`（如 `30000-30999`）	UDP	接收对端推来的音视频码流	需放行，否则信令全通却一包不收
`relay_port_range`（如 `31000-31999`）	TCP	进程内 PS 中继，仅绑 `127.0.0.1`	不需对外，仅本机

rtp_port_range 与 relay_port_range 不得重叠；中继段仅本机使用，无需也不应对外开放。

开启步骤

编辑 config.yaml 的 gb28181 段

uac（向上级平台注册）示例：

切到 uas（收设备注册）时去掉 remote_addr，改配 listen_addr 与设备侧口令：

放行 SIP 与 RTP 端口

按上方「端口与防火墙」放行 listen_addr（SIP，与对端互通）与 rtp_port_range（UDP 收流）。relay_port_range 仅绑本机，无需放行。

重启服务并查看启动日志

验证注册与收流

签发 token 后查国标状态（接口经同一套 token 鉴权）：

uac 看 registered 是否为 true；uas 下 registered 恒为 false（它只表示「是否已注册到上级」），应看 devices 里是否有设备及其 channels。appkey / appsecret 见 zhimou_openapi -show-license。

持有设备注册表的角色（uas / cascade）下若 devices 有设备但 channels 为空，多为设备没响应目录查询（或配了 auto_catalog: false），可手动补查一次：

查询是异步的（返回只表示「已发出」），目录由设备回推，稍后再看 /api/gb28181/devices。设备不在本机注册表里返回 404，uac 角色下调用返回 400，不必看日志里的字符串。

同一套 token 也能调对外的裁剪视图（不含 media_ip / 监听地址 / 中继计数等内网信息）：

uas 返 role: "uas" + source: "local" + 设备/通道清单；uac 返 role: "uac" + source: "none" + 空列表（本机只向注册的上级取流，不持有设备表，属预期而非故障）；gb28181.enable=false 的节点返 role: "disabled"，HTTP 仍是 200。集群部署（见集群部署）下 devices 走网关同名路径（token 用 cluster.yaml 里的 client_appkey / client_appsecret 换），按节点分组返在 data.backends[]，某节点不可达（或旧版没有这条路由）只在该节点的 error 上体现，整体仍 code: 0。

status 与 probe 不经网关代理：集群下这两条要直连节点，并改用该节点的 appkey / appsecret（zhimou_openapi -show-license）。

若某节点 enable=true 却仍返 role: "disabled"，说明国标启动被拒（未配口令 / media_ip=127.0.0.1 / 5060 被占），查该节点启动日志里的 gb28181 disabled: ... 一行；此时 data.backends[] 里该节点不会有 error。

配置项说明

字段	说明与约束	填错的典型现象
`enable`	总开关，缺省 `false`	本机与设备不在同一可达网段时保持 `false`，否则只是占着 5060 等不到设备
`role`	`uac` 必填 `remote_addr`+`password`；`uas` 必填 `device_password` 或 `device_passwords`	缺口令启动即被拒绝
`server_id`	20 位数字，与上级平台 / 本级规划全网唯一	撞号表现为注册与目录互相顶掉，比配错更难查
`realm`	缺省等于完整的 `server_id`（20 位，不是前 10 位）；设备侧「SIP 域」须与此完全一致	域不一致 → 摘要认证 URI 对不上，设备反复 403 重注册
`media_ip`	★ 对端（上级平台或设备）可达的本机网卡地址；绝不可 `127.0.0.1`，也不能填本机没有的地址	填回环 → 启动期即被拒绝；填了设备到不了的网段 → INVITE 返回 200 但一包不收（`rtp.packets` 不涨）
`password` / `device_password`	前者是我方作为客户端出示的口令（uac），后者是我方作为平台校验设备的口令（uas），不能混用	拿反了会一路 digest mismatch，日志有专门一行提示核对口令
`listen_addr`	`uas` 的 SIP 监听地址，缺省 `0.0.0.0:5060`（仅 IPv4）；要双栈显式写 `"[::]:5060"`	纯 IPv6 / 容器网络下留缺省会收不到 REGISTER；同机再有进程占用 5060 会 bind 失败
`transport`	媒体面传输方式（`udp` \| `tcp`）：决定 SDP 写 `RTP/AVP` 还是 `TCP/RTP/AVP` + `a=setup:passive`；SIP 信令固定 UDP	与设备/平台实际推流方式不一致 → INVITE 回 `488`，或 `200` 之后一包不收
`device_passwords`	按设备 ID 覆盖缺省口令；只填这张表（`device_password` 留空）等于设备白名单	误当「补充清单」用会拒掉所有表外设备
`auto_catalog`	设备注册成功后自动查一次通道目录，缺省 `true`；对持有本机注册表的角色有意义（`uas` / `cascade`；`uac` 不持有设备表）	关掉后 `devices[].channels` 恒空，点播只能靠「通道 ID 等于设备 ID」或「仅一台活设备」两条兜底；`cascade` 下向上级报的是同一份数据，空目录会让上级看不到通道、不再下发 `INVITE`；目录变了也不会自己刷新，需调 `POST /api/gb28181/devices/{device_id}/catalog` 补查
`rtp_port_range`	收流端口段（闭区间），UDP 需防火墙放行，不得与 `relay_port_range` 重叠	不放行 → 信令全通、一包不收
`relay_port_range`	PS 中继端口段，仅绑 `127.0.0.1`，不需对外放行	段太小会让并发通道开不出中继
`register_expire`	注册有效期（秒）。`uac`：按其 60% 提前重注册；`uas`：仅作设备未带 Expires 时的缺省值	过长 → 已离线设备在注册表里多留；过短 → 重注册频繁
`keepalive`	心跳间隔（秒），仅 `uac` 生效，须明显小于 `register_expire`	`keepalive` ≥ `register_expire` → 上级在两次心跳间判我方掉线，期间点播全部失败
`channels`	允许点播的通道白名单，空 = 不限制	非空时白名单外通道直接被拒
`stats_interval` / `log_level`	运行统计行是 debug 级：仅 `log_level: debug` 才每 `stats_interval` 秒打一行；`stats_interval` 留 0 取默认 3s，负数 = 关闭	缺省 `info` 不打统计；负周期需依赖库 v0.2.1+，更早版本会 panic

注意事项

media_ip 绝不可填 127.0.0.1：否则 SDP 的 c= 行会指向对端自己，表现为「INVITE 成功但一包不收」。

平台重启后设备不会自己回来：注册表只在本机内存，重启即为空，而设备在注册有效期内不会主动重注册。需在设备侧关 / 开一次国标接入（或等 register_expire 到期）才会重新走 REGISTER。

收流异常按「先看注册面、再看媒体面」三段定位：信令通（uac 的 registered / INVITE 200）→ 媒体到机器（rtp.packets 在涨）→ 字节能被取走（POST /api/gb28181/channels/{channel_id}/probe 返回的 relay_bytes）。三段分别对应「注册/网络」「media_ip/防火墙」「库侧中继」三类不同故障。

若流是「上级平台点播本机通道」这一路，本服务不支持（收到 INVITE 一律回 501）——取流只能由本机发起。uac 侧点播被拒时先看状态码：404 = 对端是一台不持有该通道的平台（最常见是把 remote_addr 填成了另一台不持有这台摄像头的平台）；401 / 403 才是口令或通道号问题。

501 / 405 是方向问题而非配置问题：标准国标里由上级平台点播下级（此时本机是 uas 那一端），uac 向上级发 INVITE 只有对端支持私有反向点播才能成立。两台本服务之间做不到（两边都不应答 INVITE）。要「取另一平台的流」只有两种途径：对方是会应答 INVITE 的第三方平台/设备时，让其作为下级注册到本机 uas；两台本服务之间只能转推（对方开预览/推 RTMP，本机当普通 rtmp:// 源拉）。

角色与必填项#

端口与防火墙#

开启步骤#

配置项说明#

注意事项#

角色与必填项

端口与防火墙

开启步骤

配置项说明

注意事项