术语与状态

遇到不认识的 ID 或状态时，先在本页确认它属于“身份、过程状态还是删除语义”，不要只凭名字猜含义。

flowchart LR
    A[设备 DeviceId] --> B[通道 ChannelId]
    B --> C[媒体节点 mediaServerId]
    C --> D[流 vhost/app/stream]
    D --> E[录像 sessionId / fileId]

身份

ZlmNodeId 与 mediaServerId 不是可随意互换的同一字段。

设备、通道与流

• 设备：协议端点和能力集合。
• 通道：用户观看、控制与录像的稳定业务资源。
• 流：某一时刻在 MediaServer 上真实存在的动态媒体会话。
• 录像会话：控制面正在进行的录像动作。
• 录像文件：媒体节点磁盘上的实际文件。
• 录像索引：用于检索和授权访问的数据库记录。

启用与在线

Enabled=true 表示管理意图；在线表示运行结果。通道可以启用但因设备离线而没有流，也可以暂时停用但仍保留历史录像。

节点健康

常见状态包括 Online、Offline、Unknown、Maintenance、Degraded。调度不能只看一个字符串，还要组合心跳、MediaServer、能力、磁盘与维护模式。

命令状态

过程状态常见 Pending、WaitingDependency、Dispatched、Running；终态为 Succeeded、Failed、TimedOut、Cancelled。Queued 和 Running 不是最终成功。

机器状态使用稳定 failureCode；本地化 reason/message 只用于展示，不应驱动自动重试和告警恢复。

协议方向

• GB28181 Server：下级设备或平台接入本系统。
• GB28181 Client：本系统注册到上级平台。
• RTC 发布端通常使用 WHIP，订阅端通常使用 WHEP。

删除与停止

• 停止流：结束当前会话，不删除通道。
• 停用通道：阻止新的业务使用，保留数据。
• 软删除：隐藏资源但保留恢复与历史关系。
• 物理删除：不可逆删除文件或数据，需要专门权限和确认。
• 删除协议库存：不应在仍有统一通道绑定或活动会话时强制执行。

配置状态

• HotReload：运行期生效。
• ZlmReload：MediaServer 受控重载。
• ZlmRestart：需要排空并重启 MediaServer。
• AkStreamRestart：需要 NodeAgent/宿主编排主服务重启。

一组变更以影响最大的级别为最终发布动作。