操作手册
一、上手路线图
角色分工
- ②③ 平台管理员(租户管理员即可,无需超管)在【视频中心】页面操作。
- ① 由部署/运维完成(改 yaml、配 ZLM、放通端口)。
- ④ 设备侧由现场人员在设备 web 界面填 SIP 参数。
二、前置部署
| 事项 | 要点 |
|---|---|
| SIP 端口 | 放通平台 vms.gb28181.sip.port(默认 5060)UDP+TCP;设备 → 平台必须连通 |
| 对外信令 IP | 设 vms.gb28181.sip.sip-host 为设备可路由到的平台地址(docker/NAT 必配,见 配置详解 §2.2) |
| ZLM 部署 | 每个 ZLM 实例:① general.mediaServerId 记下备用(配节点要用)② [api] secret 记下 ③ hook 列表配 4 个回调指向平台 webhook(末尾带 ?secret=<hook-secret>) |
| ZLM hook | on_publish / on_stream_changed / on_stream_none_reader / on_server_keepalive → http://平台/blade-iot/vms/webhook/<hook>?secret=<hook-secret> |
| RTP 端口段 | 放通 ZLM 的 rtp_proxy 端口段(设备 → ZLM 推流) |
| OSS | 配好对象存储(抓图/录像);record.zlm-temp-dir 为 ZLM 与平台的共享卷 |
| 总开关 | vms.enabled=true |
完成后启动平台,日志无 fail-fast 报错(hook-secret / public-host / sdp-ip 校验,见 配置详解 §5)即部署就绪。
三、配置 SIP 平台(按租户)
路径:视频中心 → 国标平台 → 新增/编辑。
| 字段 | 说明 |
|---|---|
| SIP 服务器 ID(server-id) | 本租户平台 20 位国标编号;设备端要填的就是它 |
| SIP 域(domain) | 10 位国标编号 |
| 默认密码 | 设备 Digest 鉴权默认口令 |
| 注册模式 | AUTO 自动接入 / MANUAL 手动注册(见第五节) |
SIP 监听信息只读回填
平台页的 SIP 监听 IP/端口是只读的——它们由后端 vms.gb28181.sip 全局配置决定(单端口全局共享),通过 GET /platform/sip-info 回填展示,不在页面改。租户之间靠 server-id 区分,不靠端口。
四、配置媒体节点(按租户)
路径:视频中心 → 节点配置 → 新增。每个租户配自己的 ZLM 节点;配多个即自动组成负载集群。
| 字段 | 必填 | 说明 |
|---|---|---|
| 节点名称 | ✓ | 显示用 |
| 节点编码(node-id) | ✓ | 必须等于该 ZLM 的 general.mediaServerId |
| 节点地址(host) | ✓ | 平台访问 ZLM REST API 的 IP |
| HTTP 端口 | ✓ | ZLM HTTP API 端口(默认 80) |
| 节点密钥(secret) | 等于 ZLM [api] secret;编辑留空保持原值 | |
| 内网 HTTP 端口 | docker 填容器内端口,0 回退 HTTP 端口 | |
| SDP 媒体 IP / 拉流 Host | 留空各自回退 host(语义见 配置详解 §3.2) | |
| TCP 被动收流 | NAT 场景建议「是」 | |
| 是否启用 | 仅启用的节点参与选流 |
节点编码与在线状态
- node-id ≠ ZLM mediaServerId 时,心跳回写与会话关流都命中不到节点,表现为节点永远离线 / 关流异常。
- 「在线」由 ZLM 的
on_server_keepalive心跳驱动(60s 窗口)。新建节点在收到首个心跳前显示离线属正常;若一直离线,检查 ZLM 的on_server_keepalivehook 是否配好、mediaServerId 是否对得上。 - 「并发数」是该节点当前 WAITING+RUNNING 的取流路数,反映实时负载。
既有单节点部署免配
若你是从单节点 yaml 升级而来,启动时平台已自动把 vms.gb28181.zlm 那一个节点植入默认租户 000000,无需在此重复新增。其余租户才需要自助配置。
五、接入设备
5.1 选择注册模式
在【国标平台】把 注册模式 设为 AUTO 或 MANUAL:
| 模式 | 何时用 | 设备未登记时 |
|---|---|---|
| AUTO | 设备可信、批量快速接入 | 密码对即自动落库接入 |
| MANUAL | 强管控、防陌生设备 | REGISTER 被拒(403) |
5.2 自动接入(AUTO)
设备 web 界面填 SIP 参数即可,平台无需预登记:
| 设备端字段 | 填写 |
|---|---|
| SIP 服务器 ID | 平台 server-id |
| SIP 服务器域 | 平台 domain |
| SIP 服务器地址 / 端口 | 平台 sip-host / 5060 |
| SIP 用户名 / 认证 ID | 设备 20 位国标编号 |
| 密码 | 平台默认密码 |
| 注册有效期 / 心跳周期 | 3600 / 60 |
保存重启,设备自动 REGISTER。
5.3 手动注册(MANUAL 白名单)
路径:视频中心 → 国标设备 → 新增(手动注册)。先在平台登记设备国标编号(可选设独立密码),再到设备端填同样的 SIP 参数:
- 独立密码:设备记录上的密码优先于平台默认密码,实现"一机一密"。
- 未登记的设备在 MANUAL 模式下一律 403,日志可见拒绝记录。
5.4 验证接入 + 同步目录
- 接入成功:设备表
online_status=ONLINE,日志出现device registered。 - 点【同步目录】:平台发 Catalog Query,设备分批回通道列表并落库;行政区划自动建分组树。NVR 接入后通道在此出现。
六、日常使用
| 功能 | 路径 / 操作 | 说明 |
|---|---|---|
| 实时直播 | 通道配置 / 视频监控 → 播放 | 主码流默认;通道支持双码流时可切子码流;首帧典型 2-3s |
| PTZ 云台 | 直播画面 PTZ 控件 | 4 方向 + 缩放 + 预置位 set/call/remove(不下发斜向组合) |
| 抓图 | 直播 → 抓图 | 有流直抓 / 无流自动开流;存 OSS |
| 历史回放 | 选通道 + 时间段 → 查询录像 → 回放 | 支持暂停/倍速(0.25-8)/拖动 |
| 录像计划 | 录像计划 → 新增 | cron + 时长 + 保留天数;到点两阶段异步录制归档到 OSS |
| 录像下载 | 录像下载 → 新增任务 | s=Download 加速取流;完成后 OSS 外链下载;单次 ≤ 6h |
| 录像档案 | 录像档案 | 录像计划产生的归档,可下载 |
| 业务分组 | 通道分组 / 通道配置→批量分配 | 行政区划自动建树 + 业务分组多对多 |
顶层菜单与设备详情 Tab 两条入口
回放 / 录像计划 / 录像档案 / 录像下载 / 抓图既可从顶层【录像配置】【视频监控】操作,也可在【国标设备】打开设备详情页,在对应的只读 Tab(视频 / 录像计划 / 录像档案 / 录像下载 等)按设备维度查看。
下载用 `*/url` 不用 `*/file`
抓图/录像/档案均提供返回 OSS 外链 JSON 的 */url 端点,前端拿外链直接显示或 window.open,不要用 XHR/blob 直拉 */file(会跟随 302 把平台凭证发往 OSS 域)。
七、接入上级(国标级联)
把本平台作为下级注册到区/市级上级平台。
路径:视频中心 → 国标级联 → 新增(填上级 server-id / domain / IP / 端口 / 注册账号密码 / 本端虚拟 SIP ID)→ 启用 → 立即注册。
- 注册走 REGISTER + Digest,自动适配 qop=auth 增强模式与 401 二次注册复用 Call-ID(雪亮工程/政务上级常见)。
- 注册成功后周期 Keepalive + 距过期自动续约;响应上级 Catalog 查询 / SUBSCRIBE / INVITE 被点播 / Control 转发 / BYE。
- 状态在级联列表实时显示(已注册/未注册/失败);可【活跃级联会话】查看上级正在点播本端的会话并按需强制停止。
八、运维监控
8.1 Prometheus 指标
| 指标 | 健康基线 | 异常含义 |
|---|---|---|
vms_stream_active_total | 与活跃流一致 | 不一致查 GC/Retry |
vms_stream_gc_pending_total | 长期 0 | 持续 >0 = ZLM 关流失败 |
vms_zlm_open_fail_total | 增量 0 | 增量大 = ZLM 端口耗尽/不可达 |
vms_subscription_active_total | memory/db 一致 | 不一致 = 重启未完整恢复 |
vms_sip_msg_total | 持续增长 | 不增 = SIP 端口被阻断 |
vms_catalog_partial_timeout_total | 增量 0 | 增量大 = 分批 NOTIFY 长期收不齐,触发兜底超时聚合 |
8.2 媒体节点健康
- 【节点配置】页看各节点在线状态 + 并发数:在线靠心跳,负载看并发。
- 多节点时,新流自动落并发最低节点;某节点离线→停用它,在播流断开后新流自动转移。
九、排查清单
设备注册不上
| 检查 | 方法 |
|---|---|
| 参数不匹配 | 设备端 server-id / domain / port / 密码 与平台对齐 |
| 401 循环 | 密码不一致;MANUAL 模式确认设备已登记白名单 |
| 403 拒绝 | MANUAL 模式 + 设备未登记 → 改 AUTO 或先登记设备 |
| 连不通 | 设备 → 平台 5060 UDP/TCP 防火墙/NAT |
| 注册成功但无后续 | sip-host 配成了回环/错误地址,设备回送到错目的地 |
点播信令正常但黑屏 / 拉不到流
| 检查 | 方法 |
|---|---|
| 设备收不到 RTP | 节点 sdp-ip 为回环/错误 → 设备推不上来(改成设备可路由地址) |
| 浏览器拉不到 | 节点 public-host 错 → ws-flv 地址不可达 |
| 多节点错配 | 确认会话落的节点(session.nodeId)与浏览器访问的地址一致;拉流地址跟随承载节点的 public-host |
| 抓图失败 | docker 下 internal-http-port 须为容器内端口 |
| RTP 端口耗尽 | vms_zlm_open_fail_total 增长,放宽 ZLM 端口段 |
媒体节点一直离线
| 检查 | 方法 |
|---|---|
| mediaServerId 不符 | 节点编码 node-id 必须等于 ZLM general.mediaServerId |
| 心跳未配 | ZLM 缺 on_server_keepalive hook 或 URL/secret 错 |
| 节点选不出 | 该租户无启用节点 → 点播报"当前租户无可用媒体节点",去启用/新增 |
其他
| 现象 | 排查 |
|---|---|
| CLOSE_PENDING 累积 | ZLM 关流接口是否健康;超 TTL/失败 5 次会转 EXPIRED |
| Catalog 缺通道 | UDP 丢包,30s 兜底完成;可再次同步目录 |
| MobilePosition 无 NOTIFY | 多为设备无 GPS;或 Event 头不兼容改 mobile-position-event |
| 上传 OSS 失败 | OSS 配置 / 共享卷可读写 |
十、FAQ
Q:一个租户能配几个 ZLM 节点? 不限。配几个即几元自动负载集群,新流落并发最低节点,无需任何集群开关。
Q:不同租户的节点会互相影响吗? 不会。媒体节点按租户隔离,选节点只在当前租户的启用节点里挑。
Q:升级到多节点版本,老的单节点配置还要保留吗? 保留。yaml 的 vms.gb28181.zlm 作为"默认节点种子"被植入默认租户;删了会导致默认租户无节点。
Q:手动注册模式下批量接入很多设备麻烦吗? 批量可信设备建议用 AUTO;MANUAL 用于需要逐台管控的场景。两种模式按平台(租户)切换。
Q:SIP 为什么不给每个租户单独开端口? 单端口 + server-id 路由即可天然多租户,省端口、运维只放通一个端口。详见 配置详解 §2.1。