# 系统、运维与节点接口

这一层回答“平台是否正常、节点是否在线、配置是否生效、日志去哪里查”。业务系统通常只读取状态；配置、进程和节点生命周期操作应留给管理员。

本页覆盖 **168** 个接口。每一行都回答五件事：接口地址、它做什么、何时调用、如何确认完成、谁可以调用。参数字段的精确定义以同版本 OpenAPI 为准。

> “业务接口”可以由 WebUI 或第三方系统按权限调用；“管理员接口”需要后台管理员；“内部接口/内部回调”只允许产品组件之间使用。

## 系统与健康

| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/config/center` | 查看配置中心快照。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.view` | 无业务参数 |
| `PUT /api/v2/config/center` | 按白名单更新 JSON 配置。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.config.manage` | AkConfigurationPatchRequest |
| `GET /api/v2/config/raw` | 查看受控原始 JSON 配置文件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.raw.manage` | fileName |
| `PUT /api/v2/config/raw` | 确认写入原始 JSON 配置。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.config.raw.manage` | AkRawConfigurationApplyRequest |
| `POST /api/v2/config/raw/plan` | 预览原始 JSON 配置差异。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 管理员接口<br>`system.config.raw.manage` | AkRawConfigurationPlanRequest |
| `GET /api/v2/config/runtime` | 查看.NET Runtime / GC 配置。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.view` | 无业务参数 |
| `PUT /api/v2/config/runtime` | 确认写入 .NET Runtime / GC 配置。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.config.manage` | AkRuntimeConfigurationApplyRequest |
| `POST /api/v2/config/runtime/plan` | 预览 .NET Runtime / GC 配置差异。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 管理员接口<br>`system.config.manage` | AkRuntimeConfigurationPlanRequest |
| `GET /api/v2/events/outbox` | 查询 Outbox 事件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.logs.view` | page、pageSize |
| `GET /api/v2/events/runtime/info` | 查询运行状态 WebSocket 协议说明。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`authenticated` | 无业务参数 |
| `GET /api/v2/events/runtime/ws` | 建立已认证的运行状态 WebSocket。 | 页面加载、刷新状态或按条件检索数据时调用。 | 连接升级为 WebSocket 只是开始；还要处理鉴权失败、断线重连和事件序号。 | 业务接口<br>`authenticated` | 无业务参数 |
| `GET /api/v2/setup/catalog` | 查看首次配置选项。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填） |
| `POST /api/v2/setup/complete` | 提交首次配置并查看结果。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填）、FirstRunInstallationRequest |
| `POST /api/v2/setup/database/test` | 测试安装数据库连接。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填）、FirstRunDatabaseInput |
| `GET /api/v2/setup/detect/network` | 检查安装网络环境。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填） |
| `POST /api/v2/setup/detect/nginx` | 检查 HTTPS 代理环境。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填）、FirstRunEnvironmentDetectionRequest |
| `POST /api/v2/setup/files/browse` | 浏览安装目录。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填）、FirstRunPathRequest |
| `POST /api/v2/setup/files/directories` | 创建安装目录。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填）、FirstRunDirectoryCreateRequest |
| `GET /api/v2/setup/files/roots` | 列出安装目录选择入口。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填） |
| `POST /api/v2/setup/files/validate` | 验证安装目录。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填）、FirstRunPathRequest |
| `GET /api/v2/setup/media/build/inspect` | 检查媒体服务准备条件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 仅首次初始化<br>`setup-token` | sourceMode、X-AK-Setup-Token（必填） |
| `POST /api/v2/setup/media/build/start` | 启动媒体服务准备任务。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填）、FirstRunMediaBuildRequest |
| `GET /api/v2/setup/media/build/status` | 查看媒体服务准备状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 仅首次初始化<br>`专用流程` | 无业务参数 |
| `POST /api/v2/setup/notifications/test` | 测试通知配置。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填）、FirstRunNotificationInput |
| `POST /api/v2/setup/preflight` | 预检首次配置。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 仅首次初始化<br>`setup-token` | X-AK-Setup-Token（必填）、FirstRunInstallationRequest |
| `GET /api/v2/setup/status` | 查看安装状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 公开入口<br>`专用流程` | 无业务参数 |
| `GET /api/v2/system/api-docs` | 跳转到受登录保护的 Knife4j API 文档。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 诊断接口<br>`system.view` | 无业务参数 |
| `GET /api/v2/system/background-tasks` | 查询当前进程后台任务注册结果。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `POST /api/v2/system/config/deploy` | 部署配置版本。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.config.manage` | SystemConfigDeployRequest |
| `GET /api/v2/system/config/effective` | 查看带来源和生效方式的有效配置。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.view` | scopeType、scopeId |
| `POST /api/v2/system/config/plan` | 预览白名单配置差异和最高生效级别。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 管理员接口<br>`system.config.manage` | SystemConfigPlanRequest |
| `GET /api/v2/system/config/revisions` | 查看配置版本历史。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.view` | scopeType、scopeId、limit |
| `POST /api/v2/system/config/rollback` | 回滚到历史配置版本。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.config.manage` | SystemConfigRollbackRequest |
| `GET /api/v2/system/config/scopes` | 列出配置作用域。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.view` | 无业务参数 |
| `POST /api/v2/system/config/wizard/apply` | 确认后分组应用向导计划。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.config.manage` | ConfigurationWizardApplyRequest |
| `GET /api/v2/system/config/wizard/assessment` | 评估目标节点资源、媒体负载、流媒体配置可读性和端口环境。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.view` | nodeId |
| `GET /api/v2/system/config/wizard/catalog` | 查看AKStream.Next、流媒体服务与宿主机的完整向导参数目录。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.view` | nodeId |
| `POST /api/v2/system/config/wizard/plan` | 把选中的向导建议转换为 AKStream、流媒体服务、宿主和外部操作计划。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 管理员接口<br>`system.config.manage` | ConfigurationWizardPlanRequest |
| `POST /api/v2/system/config/wizard/recommend` | 按业务峰值、延迟与弱网目标逐项生成配置建议。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.config.manage` | ConfigurationWizardRecommendRequest |
| `GET /api/v2/system/console/summary` | 查看系统中枢运行总览。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `GET /api/v2/system/data-retention/cleanup/preview` | 预览中间数据保留清理范围。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>`system.config.view` | actor、reason |
| `POST /api/v2/system/data-retention/cleanup/run-once` | 立即执行一轮中间数据保留清理。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | DataRetentionCleanupRunRequest |
| `GET /api/v2/system/database-schema-audit` | GET /api/v2/system/database-schema-audit。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | includeDdl、maxDdlChars |
| `POST /api/v2/system/filesystem/directories` | 在当前服务器目录中创建并回读验证一个直接子目录。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.config.manage` | SystemDirectoryCreateRequest |
| `GET /api/v2/system/filesystem/entries` | 按配置字段语义浏览当前服务所在服务器的目录或文件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.manage` | fieldPath（必填）、path |
| `GET /api/v2/system/filesystem/roots` | 列出当前服务所在服务器的文件系统选择入口。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.config.manage` | fieldPath（必填） |
| `POST /api/v2/system/filesystem/validate` | 校验手写服务器路径的存在性、类型、读取权限与可执行权限。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.config.manage` | SystemPathValidationRequest |
| `GET /api/v2/system/info` | 查看系统基础信息。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `GET /api/v2/system/lifecycle/agents` | 查看Node Agent 在线和版本状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.lifecycle.view` | 无业务参数 |
| `POST /api/v2/system/lifecycle/agents/{nodeId}/enrollment` | 创建一次性 Node Agent 注册码。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.lifecycle.manage` | nodeId（必填）、CreateNodeAgentEnrollmentRequest |
| `GET /api/v2/system/lifecycle/operations` | 查看节点生命周期操作。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口<br>`system.lifecycle.view` | nodeId、limit |
| `POST /api/v2/system/lifecycle/operations` | 创建受 Agent 执行的节点生命周期操作。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口<br>`system.lifecycle.manage` | CreateNodeLifecycleOperationRequest |
| `POST /api/v2/system/logs/agent/sessions` | 围绕所选日志创建只读、多轮大语言模型智能诊断会话。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.logs.view` | LogDiagnosticAgentStartRequest |
| `GET /api/v2/system/logs/agent/sessions/{id}` | 查看日志智能诊断会话状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.logs.view` | id（必填） |
| `POST /api/v2/system/logs/agent/sessions/{id}/cancel` | 取消日志智能诊断当前轮次，不删除已经采集的会话证据。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.logs.view` | id（必填） |
| `GET /api/v2/system/logs/agent/sessions/{id}/events` | 增量读取日志智能诊断中的模型消息、工具参数、工具结果与最终结论。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.logs.view` | id（必填）、after |
| `POST /api/v2/system/logs/agent/sessions/{id}/messages` | 在已有日志智能诊断上下文中继续追问并允许模型追加只读查询。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.logs.view` | id（必填）、LogDiagnosticAgentMessageRequest |
| `GET /api/v2/system/logs/analysis/status` | 查看日志大语言模型分析能力状态，不返回 API Key。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.logs.view` | 无业务参数 |
| `POST /api/v2/system/logs/analyze` | 选择服务器环形缓冲中的日志，自动关联原始上下文并进行大语言模型故障分析。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.logs.view` | LogAnalysisRequest |
| `GET /api/v2/system/logs/files/{fileId}/download` | 下载白名单目录内的日志文件。 | 页面加载、刷新状态或按条件检索数据时调用。 | 检查 Content-Type、文件长度或 Range 响应，不要按普通 JSON 解析。 | 业务接口<br>`system.logs.download` | fileId（必填） |
| `GET /api/v2/system/logs/query` | 按来源、级别、关键字和 TraceId 查询系统日志。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.logs.view` | Source（必填）、FileId、Level、Keyword、TraceId、From、To、TailLines |
| `GET /api/v2/system/logs/sources` | 列出系统日志来源、集群节点、媒体服务和安全文件标识。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.logs.view` | 无业务参数 |
| `GET /api/v2/system/logs/stream` | 以 NDJSON 长连接实时输出可断线续传的 日志。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.logs.view` | after、sessionId、tail、nodeIds、mediaServerIds |
| `GET /api/v2/system/migration-audit` | 执行 迁移数据体检。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | clusterId、includeSamples、sampleSize、includePassed |
| `POST /api/v2/system/migration-audit/removed-protocol-residues/cleanup` | 清理已移除协议历史残留数据。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | RemovedProtocolResidueCleanupRequest |
| `POST /api/v2/system/notifications/email/test` | 登录后台后测试系统 SMTP 运维通知配置。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.view` | SystemEmailTestRequest |
| `GET /api/v2/system/openapi-audit` | 审计 Swagger/Knife4j 接口文档质量。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 诊断接口<br>`system.view` | onlyProblems |
| `GET /api/v2/system/parity-audit` | 审计旧 AKStream 关键能力在 Next 中的覆盖关系。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | clusterId、checkDatabase、includeDetails、includePassed |
| `GET /api/v2/system/readiness` | 执行系统验收检查。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | checkDatabase、checkZlm |
| `GET /api/v2/system/roles` | 查看当前进程角色。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `GET /api/v2/system/runtime/diagnostics` | 查看当前 运行环境诊断。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `GET /api/v2/system/runtime/ports` | 按当前启用模块、实际配置和监听状态生成端口开放清单。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `GET /api/v2/system/runtime/tuning` | 查看当前宿主机白名单调优参数与执行能力。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `PUT /api/v2/system/runtime/tuning` | 通过 NodeAgent 与固定 root helper 应用并验证 Linux 宿主调优参数。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.host.manage` | HostTuningApplyRequest |
| `POST /api/v2/system/runtime/tuning/plan` | 预览 Linux 宿主句柄、IPv6 与 TCP 白名单参数差异。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>`system.host.manage` | HostTuningPlanRequest |
| `GET /api/v2/system/source-documentation-audit` | 审计服务端接口注释覆盖情况。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 诊断接口<br>`system.view` | onlyProblems、checkParameterAndReturnTags、maxResults |
| `GET /api/v2/system/swagger` | 跳转到受登录保护的 Swagger UI。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 诊断接口<br>`system.view` | 无业务参数 |
| `GET /api/v2/system/tasks` | 查看内置后台任务注册和运行状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.tasks.view` | 无业务参数 |
| `POST /api/v2/system/tasks/{taskName}/run` | 预览或人工执行受支持的内置任务。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`system.tasks.execute` | taskName（必填）、RunSystemTaskRequest |
| `GET /api/v2/system/tls/acme` | 查看内置 .NET ACME、Let's Encrypt 证书、待验证订单和自动续签状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.config.view` | 无业务参数 |
| `POST /api/v2/system/tls/acme/apply-nginx` | 将已签发的正式 ACME 证书写入 Nginx 站点配置，校验成功后 Reload，失败自动恢复。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | 无业务参数 |
| `PUT /api/v2/system/tls/acme/automation` | 开启或关闭 每 12 小时的自动续签检查及 Nginx 自动 Reload。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | AcmeAutomationRequest |
| `POST /api/v2/system/tls/acme/complete` | 检查已生成的 HTTP/DNS 验证内容，完成 ACME 验证、CSR 和证书下载。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | AcmeCompleteRequest |
| `POST /api/v2/system/tls/acme/issue` | 使用 Let's Encrypt 测试或正式环境签发证书，并登记自动续签状态。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | AcmeCertificateRequest |
| `POST /api/v2/system/tls/acme/preflight` | 在签发前检查公网域名、HTTP 验证目录或手工 DNS TXT 前置条件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | AcmeCertificateRequest |
| `POST /api/v2/system/tls/acme/prepare` | 由内置 .NET ACME 客户端创建订单并生成 HTTP 文件或 DNS TXT 验证内容。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | AcmeCertificateRequest |
| `POST /api/v2/system/tls/acme/renew` | 执行指定证书的续签演练或真实续签。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | AcmeRenewRequest |
| `GET /api/v2/system/tls/deployment` | 探测 Nginx、Kestrel、域名网络入口与 MediaServer 证书生效状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.config.view` | 无业务参数 |
| `POST /api/v2/system/tls/nginx/reload` | 校验成功后审计并重新加载 Nginx。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | NginxReloadRequest |
| `POST /api/v2/system/tls/nginx/template` | 生成不会自动落盘的 Nginx HTTPS/WSS 反向代理模板。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | NginxTemplateRequest |
| `POST /api/v2/system/tls/nginx/validate` | 使用已探测的可执行文件和配置路径执行 nginx -t。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | 无业务参数 |
| `GET /api/v2/system/upgrades` | 查看当前实例最近的正式包升级记录和持久化执行状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.upgrade.view` | 无业务参数 |
| `GET /api/v2/system/upgrades/{id}` | 查看一个升级任务。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.upgrade.view` | id（必填） |
| `POST /api/v2/system/upgrades/{id}/start` | 二次确认后由本机高权限 NodeAgent 调度脱离主进程的升级事务。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`system.upgrade.manage` | id（必填）、StartSystemUpgradeRequest |
| `POST /api/v2/system/upgrades/packages` | 以流式请求体上传并预检当前平台正式升级包。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.upgrade.manage` | 无业务参数 |
| `GET /api/v2/system/version` | 查看版本信息。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `GET /api/v2/system/webhooks/catalog` | 查看第三方 Webhook 可选事件目录。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `POST /api/v2/system/webhooks/deliveries/{id}/retry` | 重试指定方案的一条失败投递。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`system.config.manage` | id（必填） |
| `POST /api/v2/system/webhooks/outbox/{id}/retry` | 人工重试第三方 Webhook。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`system.config.manage` | id（必填） |
| `GET /api/v2/system/webhooks/status` | 查询第三方 Webhook 状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | 无业务参数 |
| `GET /api/v2/system/webhooks/subscriptions` | 列出第三方 Webhook 推送方案。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | includeArchived |
| `POST /api/v2/system/webhooks/subscriptions` | 创建一个地址对应的 Webhook 推送方案。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | OutboundWebhookSubscriptionRequest |
| `PUT /api/v2/system/webhooks/subscriptions/{id}` | 修改 Webhook 推送方案。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | id（必填）、OutboundWebhookSubscriptionRequest |
| `POST /api/v2/system/webhooks/subscriptions/{id}/archive` | 归档 Webhook 推送方案并保留历史。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | id（必填） |
| `GET /api/v2/system/webhooks/subscriptions/{id}/deliveries` | 分页读取指定方案的独立投递历史。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.view` | id（必填）、page、pageSize |
| `POST /api/v2/system/webhooks/subscriptions/{id}/test` | 向指定 Webhook 推送方案发送真实测试事件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | id（必填）、OutboundWebhookTestRequest |
| `POST /api/v2/system/webhooks/test` | 发送第三方 Webhook 测试事件。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | OutboundWebhookTestRequest |
| `POST /api/v2/system/zlm-configuration/apply` | 确认完整预览集合后向原目标节点下发配置写入。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.manage` | MediaServiceConfigurationApplyRequest |
| `GET /api/v2/system/zlm-configuration/operations/{id}` | 查看目标媒体配置任务的真实状态和脱敏回读结果。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | id（必填） |
| `POST /api/v2/system/zlm-configuration/plan` | 逐节点预览媒体配置差异，不写入文件。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>`system.config.manage` | MediaServiceConfigurationPlanRequest |
| `POST /api/v2/system/zlm-configuration/read` | 按顶部管理上下文读取目标媒体节点的真实配置。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.view` | MediaServiceConfigurationContext |
| `GET /health` | 查看健康状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 公开入口<br>`*` | 无业务参数 |

## 日志与安全

| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/logging/level` | 查看当前日志级别配置。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.logs.view` | 无业务参数 |
| `PUT /api/v2/logging/level` | 设置全局日志级别。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.logs.manage` | GlobalLogLevelRequest |
| `POST /api/v2/logging/overrides` | 设置模块、节点、设备、流或接口的日志级别覆盖。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.logs.manage` | LogLevelOverrideRequest |
| `DELETE /api/v2/logging/overrides/{scope}/{key}` | 删除日志级别覆盖规则。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.logs.manage` | scope（必填）、key（必填） |
| `PUT /api/v2/logging/zlm-module-output` | 设置 内部流媒体服务模块常规日志开关。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.logs.manage` | MediaServiceModuleOutputLogRequest |
| `PUT /api/v2/logging/zlm-process-output` | 设置流媒体服务子进程输出日志开关。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.logs.manage` | MediaServiceProcessOutputLogRequest |

## 集群与节点

| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/cluster/monitoring` | 查询全局监控快照。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | clusterId、historyMinutes、historyNodeId、historyStart、historyEnd、historyBucketSeconds |
| `GET /api/v2/cluster/monitoring/current` | 查询不含历史趋势的当前监控快照。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | clusterId |
| `GET /api/v2/cluster/monitoring/local-runtime` | 查询当前节点最新的轻量进程资源快照。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | 无业务参数 |
| `GET /api/v2/cluster/status` | 查询集群运行状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | clusterId |
| `GET /api/v2/media-servers` | 查询流媒体服务节点列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | clusterId |
| `GET /api/v2/media-servers/{mediaServerId}/references` | 查询流媒体服务节点退役前的业务引用明细。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | mediaServerId（必填）、clusterId、sampleSize |
| `POST /api/v2/media-servers/{mediaServerId}/retire` | 预览或退役流媒体服务节点。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | mediaServerId（必填）、clusterId、RetireMediaServerRequest |
| `GET /api/v2/node/commands` | 分页查询当前集群的 node 命令。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | page、pageSize、nodeId、zlmNodeId、status、commandType、requestedBy、localOnly、from、to、sinceHours、keyword |
| `GET /api/v2/node/commands/{commandId}` | 查看node 命令详情。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | commandId（必填） |
| `GET /api/v2/node/commands/{commandId}/detail` | 查看node 命令详情。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | commandId（必填） |
| `GET /api/v2/node/commands/local` | 查询当前 node 的本机命令。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | status |
| `GET /api/v2/node/commands/stats` | 统计当前集群的 node 命令状态。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | nodeId、zlmNodeId、status、commandType、requestedBy、localOnly、from、to、sinceHours、keyword |
| `GET /api/v2/node/ffmpeg-templates` | 查询 FFmpeg 模板列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | mediaServerId |
| `POST /api/v2/node/ffmpeg-templates` | 新增 FFmpeg 模板。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | SaveFfmpegTemplateRequest |
| `DELETE /api/v2/node/ffmpeg-templates/{templateName}` | 删除 FFmpeg 模板。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | templateName（必填）、mediaServerId |
| `PUT /api/v2/node/ffmpeg-templates/{templateName}` | 修改 FFmpeg 模板。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | templateName（必填）、SaveFfmpegTemplateRequest |
| `GET /api/v2/node/rtp/leases` | 查询 RTP 端口租约。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | status、direction |
| `POST /api/v2/node/rtp/leases` | 申请 RTP 端口租约。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | RtpPortLeaseRequest |
| `POST /api/v2/node/rtp/leases/{leaseId}/release` | 释放 RTP 端口租约。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | leaseId（必填）、RtpPortReleaseRequest |
| `POST /api/v2/node/rtp/ports/{port}/release` | 按端口释放 RTP 端口租约。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | port（必填）、direction、RtpPortReleaseRequest |
| `GET /api/v2/node/zlm/config` | 查看本机流媒体服务config.ini。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | 无业务参数 |
| `POST /api/v2/node/zlm/config/apply` | 应用本机流媒体服务config.ini 写入计划。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | 无业务参数 |
| `POST /api/v2/node/zlm/config/plan` | 生成本机流媒体服务config.ini 写入计划。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>`nodes.manage` | 无业务参数 |
| `GET /api/v2/node/zlm/config/raw` | 查看原始 MediaServer config.ini。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.config.raw.manage` | 无业务参数 |
| `PUT /api/v2/node/zlm/config/raw` | 备份并写入原始 MediaServer config.ini。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`system.config.raw.manage` | MediaServiceRawConfigurationApplyRequest |
| `POST /api/v2/node/zlm/config/raw/plan` | 校验并预览原始 MediaServer config.ini 差异。 | 准备执行变更前先调用，用来预览影响范围，确认无误后再调用真正执行接口。 | 返回的是计划或评估结果，不会自动执行真正变更。 | 业务接口<br>`system.config.raw.manage` | MediaServiceRawConfigurationPlanRequest |
| `GET /api/v2/node/zlm/core-settings` | 查看流媒体服务核心协议、延迟、端口和 HTTP 页面配置。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | 无业务参数 |
| `PUT /api/v2/node/zlm/core-settings` | 校验、备份并写入流媒体服务核心配置。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | SaveMediaServiceCoreSettingsRequest |
| `GET /api/v2/node/zlm/process` | 查看本机流媒体服务进程状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | 无业务参数 |
| `POST /api/v2/node/zlm/process/reload` | 向本机流媒体服务进程发送热加载信号。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | 无业务参数 |
| `POST /api/v2/node/zlm/process/restart` | 重启本机流媒体服务进程。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | 无业务参数 |
| `POST /api/v2/node/zlm/process/start` | 启动本机流媒体服务进程。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`nodes.manage` | 无业务参数 |
| `POST /api/v2/node/zlm/process/stop` | 停止本机流媒体服务进程。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`nodes.manage` | 无业务参数 |
| `GET /api/v2/nodes` | 查询 节点列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | clusterId |
| `POST /api/v2/nodes/{nodeId}/commands` | 创建 node 命令。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`nodes.manage` | nodeId（必填）、clusterId、CreateNodeCommandRequest |
| `POST /api/v2/nodes/self/heartbeat` | 手动触发当前进程 node 心跳。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`nodes.manage` | firstPost |

## MediaServer 适配

| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/zlm/nodes` | 查看已配置的流媒体服务节点。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | 无业务参数 |
| `GET /api/v2/zlm/nodes/{nodeId}/apis` | 查看指定流媒体服务节点 API 列表。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | nodeId（必填） |
| `GET /api/v2/zlm/nodes/{nodeId}/capabilities` | 执行指定流媒体服务节点能力发现。 | 在展示功能、生成表单或发起控制前，先用它确认当前版本和目标设备真正支持什么。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | nodeId（必填） |
| `GET /api/v2/zlm/nodes/{nodeId}/recording-status` | 查询指定流媒体服务节点上某路流的实际录像状态。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | nodeId（必填）、vhost、app、stream、type |
| `GET /api/v2/zlm/nodes/{nodeId}/version` | 查看指定流媒体服务节点版本。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`nodes.view` | nodeId（必填） |
| `GET /api/v2/zlm/webhook-inbox` | 查询流媒体服务 WebHook 收件箱。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`system.logs.view` | page、pageSize、hookName、mediaServerId、status、businessStatus |

## 其他接口

| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/display-wall/programs` | 查询显示墙节目。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`display-wall.view` | 无业务参数 |
| `POST /api/v2/display-wall/programs` | 创建显示墙节目。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`display-wall.manage` | SaveDisplayWallProgramRequest |
| `DELETE /api/v2/display-wall/programs/{id}` | 删除未在播出的显示墙节目。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`display-wall.manage` | id（必填） |
| `GET /api/v2/display-wall/programs/{id}` | 查看一个显示墙节目。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`display-wall.view` | id（必填） |
| `PUT /api/v2/display-wall/programs/{id}` | 保存显示墙节目，并通过修订号防止并发覆盖。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口<br>`display-wall.manage` | id（必填）、SaveDisplayWallProgramRequest |
| `GET /api/v2/display-wall/runtime` | 查看显示墙播出控制与轻量通道在线快照。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口<br>`display-wall.view` | 无业务参数 |
| `POST /api/v2/display-wall/runtime/start` | 从第一个场景启动节目轮询，所有已打开大屏按同一服务端时间同步播出。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`display-wall.manage` | StartDisplayWallProgramRequest |
| `POST /api/v2/display-wall/runtime/stop` | 停止节目轮询并冻结在当前场景，不清空已经上墙的画面。 | 用户提交业务动作或配置变更时调用。 | HTTP 成功只表示请求被接收；继续查询命令、任务、通道或会话状态，直到成功或失败终态。 | 业务接口<br>`display-wall.manage` | 无业务参数 |

## 接口字段与示例

本页故意先讲清业务用途，不把几百个字段塞进说明文字。真正编码时，请使用与部署版本一起提供的 OpenAPI 和 Postman 资产查看请求体、响应体、枚举、文件类型与示例；不要拿网站最新契约调用旧版本服务。