交互场景
一、典型业务场景
场景一:首次接入新摄像头
客户网点新装一台 IPC,接入平台开始上传画面。
| 步骤 | 操作 | 平台行为 |
|---|---|---|
| ① | 摄像头 web 界面填写国标 SIP 参数(server-id / domain / 端口 / 设备编号 / 密码) | — |
| ② | 摄像头主动 REGISTER | 平台 401 nonce 挑战 |
| ③ | 摄像头重发携 Digest | 验证通过 + 设备状态置 ONLINE + 发布上线事件 |
| ④ | 管理员前端点击"同步目录" | 平台发 Catalog Query |
| ⑤ | 设备 NOTIFY 回通道列表(可能分批) | 平台按 SN 聚合 + 落库通道 |
| ⑥ | 行政区划自动建分组 | 按 civilCode 自动归类到分组树 |
场景二:实时点播一路 IPC
操作员在监控大屏上点开一个通道实时画面。
收流口的两种部署形态
"准备收流口"按媒体节点 rtp_port 分单端口 / 多端口两种形态,直接影响 Docker 放行策略(配置详见 配置详解 §3.5)。TCP 收流模式下平台下发 a=setup:passive(被动收流),设备应答 a=setup:active 主动连入收流口;UDP 收流不带 setup 行。
子码流场景
若网络受限或同屏多路时切换子码流,前提是通道支持双码流。 SDP 中同时下发多厂商兼容字段(streamnumber + streamprofile + i=Stream:1)以适配海康/大华/宇视。
场景三:回放上周某段视频
| 步骤 | 操作 | 平台行为 |
|---|---|---|
| ① | 选定通道 + 时间区间 → 查询录像 | 平台向设备发 RecordInfo Query |
| ② | 平台返回 sn,前端轮询拉结果 | 设备分批 NOTIFY,平台按 SN 聚合 |
| ③ | 选定具体录像段 → 启动回放 | 起 INVITE Playback(s=Playback / t=startUnix endUnix) |
| ④ | 前端 ws-flv 播放 | 与点播一致 |
| ⑤ | 暂停 / 快进 / 拖动 | 平台发 INFO MANSRTSP(PAUSE / SCALE / Range) |
场景四:执法记录仪 GPS 轨迹监控
移动单兵设备每分钟上报 GPS,平台显示运动轨迹。
| 步骤 | 操作 | 平台行为 |
|---|---|---|
| ① | 管理员开启该设备的 GPS 订阅(interval=60) | 平台发 SUBSCRIBE Event=presence(默认,个别固件可配 MobilePosition) |
| ② | 设备每 60s NOTIFY 一次位置 | 平台解析 Time / 经/纬/速/向/海拔 |
| ③ | 业务层校验 WGS84 坐标合理性 | 经度 ∈ [-180,180] / 纬度 ∈ [-90,90] 越界直接丢弃 |
| ④ | 更新通道最近位置 | 入库经/纬/速/向/海拔/最近上报时间 |
| ⑤ | 订阅自动续约 | 平台后台任务每 5 分钟扫描(单条订阅按 expires 约 0.8 倍即默认约 48 分钟到点续约),优先 in-dialog refresh |
MobilePosition 字段
GB28181 NOTIFY 报文携带:Time / Longitude / Latitude / Speed(km/h) / Direction(0-360°) / Altitude(米)。 固定摄像头无 GPS 硬件时订阅无响应,仅适用于车载 / 单兵 / 无人机等移动终端。
场景五:周末自动录像归档
工地每周末 0:00-8:00 自动录制重点通道,归档到 OSS 保留 30 天。
| 步骤 | 操作 | 平台行为 |
|---|---|---|
| ① | 管理员创建录像计划(cron + duration + retainDays) | 计划入库 |
| ② | 计划到点 | 后台任务每 60s 扫描"next_fire_time ≤ now" |
| ③ | 阶段 1 同步:起实时取流(s=Play)→ 等流就绪 → 开启录制 | 立即返回,不阻塞工作线程 |
| ④ | 阶段 2 异步(duration+5s 后自动回调) | 停止录制 → 从 ZLM 拉取 MP4 直传 OSS → 尽力删除 ZLM 端录像文件 → 更新归档状态为完成 |
| ⑤ | 到达保留期 | 平台后台清理任务每天凌晨 02:00 清理 OSS + 数据库记录 |
长录像不占线程的设计
平台把执行拆为两阶段,通过定时器异步回调收尾,避免直接阻塞工作线程数小时。 工作线程只在阶段 1 起流与阶段 2 收尾的瞬间被占用,不会在整段录像时长内被长期持有。
场景六:智能告警 + AI 事件联动
摄像头本地 AI 检测到入侵 → 平台收到智能告警 → 触发下游工单 / 短信。
AI 事件过滤(扩展示例)
平台在告警去重通过后即发布 VmsAlarmReceivedEvent,下游可自行监听并按 AlarmMethod=5 AND AlarmType IN (...) 过滤典型视频分析事件(平台未内置该过滤);AlarmType 各码含义见 通信协议 §7.1。
场景七:运维人员手动抓图存档
巡查时点击"截图",留档到 OSS。
| 步骤 | 操作 | 平台行为 |
|---|---|---|
| ① | 前端触发抓图(channelId) | 平台业务层接收 |
| ② | 检查是否有进行中的直播会话 | 有 → 直接调流媒体抓帧 |
| ③ | 若无现存流 → 自动开流 | 等待流就绪(最多 5s) + 二次校验 |
| ④ | 取关键帧 jpeg byte[] | 流媒体返回图像数据 |
| ⑤ | 上传 OSS | 按"vms/snapshot/{年}/{月}/{日}/{channelId}-{uuid}.jpg" 命名 |
| ⑥ | 自动开流场景下关流 | 释放 SSRC |
| ⑦ | 7 天后过期清理 | 后台任务每天凌晨 02:30 清理 |
场景八:接入区/市级公安上级平台
把本平台作为下级注册到上级国标平台,响应上级 Catalog Query / SUBSCRIBE / INVITE(被点播)/ Control 转发 / BYE。
qop=auth 与 Call-ID 复用(雪亮工程必需)
上级常强制 qop=auth,并要求 401 二次注册复用首次 REGISTER 的 Call-ID——二者缺一都会陷入 401 循环。本实现两者均自动适配,接入侧无需配置。协议细节见 通信协议 §8。
上级被点播 + BYE 的三路收敛
上级 INVITE 命中后,平台申请 SSRC、起本端 RTP 接收并通知流媒体向上转发,会话落库 sessionType=cascade。关闭由三路任一触发——上级 BYE / 下级断流 / ACK 超时 + GC 兜底——任一触发后另两路命中终态即 no-op、保证幂等。完整时序见 通信协议 §8。
二、数据流向总览
三、常见问题
Q:点播延迟为什么有 2-3 秒?
经 RTP/PS → 流媒体 → WS-FLV 链路,首帧延迟主要来自设备首关键帧间隔(通常 1-2s)与流媒体拉流缓冲。WebRTC 输出可降到 500ms 内,但需要部署 STUN/TURN 服务。
Q:为什么订阅 MobilePosition 后没收到 NOTIFY?
90% 概率是设备本身不带 GPS(固定摄像头通常无 GPS)。其余可能是 Event 头不兼容,个别固件需把 vms.gb28181.sip.mobile-position-event 由默认 presence 改为 MobilePosition。
Q:Catalog 同步偶尔丢通道怎么办?
设备分批 NOTIFY 时偶有 UDP 丢包,导致已收数 < 总数。批间静默 15s 后回收该聚合会话(各批通道已随到随入库),本轮不做缺席对账,交下一轮完整目录周期自然对账。可手动再次"同步目录"补全。
Q:CLOSE_PENDING 会一直累积吗?
不会。后台重试任务定期重试关流,累积超时或连续失败达阈值即转入终态 EXPIRED,可由 SQL 报表识别出长期关流失败的孤立会话、人工介入排查流媒体健康。状态机与精确阈值见 核心概念 §六。
Q:跨租户能看到别的租户设备吗?
不能。三条入站路径各自注入租户上下文——前端请求经框架拦截器注入 SQL 条件、设备 SIP 反查租户、异步查询缓存额外做租户比对,跨租户读取一律返回 null。原理见 概念介绍 §五。
Q:设备校时为什么用北京时间?能改吗?
GB28181-2016 §9.10 明确规定校时标准时间是北京时间(UTC+8),协议不携带时区信息。 本实现强制按北京时区构造时间字符串,不受平台服务器系统时区影响(云端跨区部署常见)。 不建议改,改了会与国标合规设备时间冲突。
Q:订阅会丢吗?设备断电再上电会怎样?
订阅在数据库持久化,设备 REGISTER 上线时平台自动重发该设备所有 ACTIVE 订阅, 不依赖设备端订阅状态记忆,即使设备清空全部上下文也能恢复。
Q:抓图和录像存哪里?
走 OSS 抽象,后端可切换 MinIO / 阿里云 / 腾讯云 / 华为云 / 七牛云,业务代码无感知。 下载 / 抓图提供 */url 端点返回 OSS 外链(JSON),前端拿到后直连 OSS,平台不中转流量(亦保留 */file 302 端点);前端优先用 */url,避免 blob 直拉跟随 302 时把平台凭证发往 OSS 域。