API 分层与调用边界

接口不是按“后端代码模块”给用户使用的，而是按调用责任分层。先判断你属于哪一层，再选择接口，可以避免拿管理员接口做普通业务，也能避免误调用内部回调。

flowchart LR
    A[公开入口：健康、登录] --> B[业务接口：设备、视频、录像、RTC]
    B --> C[管理员接口：配置、用户、节点]
    C --> D[节点操作：受控 Agent]
    D --> E[内部回调：仅产品组件]

第一层：公开连接入口

只有健康检查、登录、验证码、刷新会话和首次初始化等少量入口可以在没有 Bearer Token 时访问。公开不等于可以无限调用；登录失败防护、验证码和限流仍会生效。

第二层：第三方业务接口

设备、通道、流、录像、协议统一视图和 RTC 是最常用的业务接口。你的服务端使用 API Token 调用，并按设备查看、设备控制、录像播放、录像下载、RTC 参与等权限拆分。

业务系统优先使用统一接口：

• 查设备与通道，优先从统一资源和 /api/v2/channels 开始。
• 做 PTZ，优先使用通道统一 PTZ，并先读取能力。
• 做播放和录像，围绕统一通道 ID、流会话 ID、录像文件 ID 组织业务。
• 只有国标目录、ONVIF Profile 等协议特有动作才进入协议专用接口。

第三层：管理员接口

用户、角色、令牌、原始配置、服务器文件浏览、主机调优和节点生命周期会改变平台安全或运行方式。它们要求更高权限，有些还强制使用交互式管理员会话，不能只靠普通 API Token 绕过确认。

第四层：实时与异步接口

WebSocket、NDJSON 日志流、WHIP/WHEP、文件流和 Range 下载不是普通 JSON 请求。客户端要分别实现断线重连、序号续传、SDP 协商、媒体会话释放、流式读取和取消。

第五层：内部服务接口

节点心跳、命令结果回填、Agent 本机接口、媒体服务回调和协议结果回填由受信任组件调用。它们可能出现在 OpenAPI 中，是为了版本审计和产品联调，不代表第三方可以模拟调用。

看到这些标识时直接停下来：

• 内部回调
• 节点本机接口
• 节点内部接口
• 集群内部接口

如果你的需求必须调用这一层，通常说明选错了业务接口。先回到统一设备、通道、流、录像或 RTC 层寻找公开动作。

一次业务动作的正确闭环

业务请求 → 权限校验 → 创建资源或命令 → 设备/节点异步执行 → 状态或事件回填 → 查询到最终结果

因此客户端必须保存资源 ID、命令 ID、任务 ID、会话 ID 和 TraceId。超时以后先查询现状，不要不加判断地重复 POST。