按现象定位问题 · AKStream.Next Docs

按现象定位问题

从最接近用户的现象进入。先确认影响范围，再沿依赖链找到第一处不一致。

flowchart LR
    A[用户看到什么] --> B{全部还是局部?}
    B --> C[锁定设备 / 节点 / 协议 / 网络]
    C --> D[从页面向后逐层核对]
    D --> E[第一处没有证据的层]
    E --> F[修复并回到用户路径验证]

快速入口

现象	先确认	进入
页面打不开或登录失败	DNS、HTTPS、服务 health、账号状态	本页“平台不可访问”
设备离线、ONVIF 发现不到、GB 注册失败	网络方向、时间、凭据、SIP/发现日志	设备离线
API 成功但没有画面	MediaServer 是否有对应流	没有画面
流能播但录像列表为空	会话、磁盘文件、索引哪层断开	录像缺失
RTC 只在内网成功	ICE candidate、TURN、防火墙	RTC 失败
health 正常但业务不可用	readiness、数据库、MediaServer、后台任务	本页“健康不等于业务可用”
配置保存后不生效	生效版本、待重启、运行时回读	本页“配置不生效”
Agent 在线但主服务离线	宿主守护、Agent 职责、最近操作	本页“进程恢复”
升级后异常	版本、Schema、配置迁移与回滚点	备份与升级

按顺序检查：

在服务器本机可访问而用户网不可访问，优先排 DNS、防火墙、代理和路由，不要重建数据库。

liveness 只说明进程能响应。readiness 才会综合依赖项，但它也不能替代真实用户路径。按失败业务检查数据库、MediaServer、协议模块、录像根、授权额度和第三方服务。

直接修改磁盘 JSON 可能被已运行进程忽略，也可能在下一次平台保存时覆盖。

NodeAgent 在线不表示主服务一定在线。Linux 主服务使用 Restart=no，由 NodeAgent 独立保存期望状态并通过固定 systemd Provider 恢复；先检查 Agent 的期望状态、实际状态、恢复尝试和退避原因。其他平台以当前发布清单声明的唯一恢复所有者为准。

检查宿主服务定义、失败计数、启动账号、工作目录、端口占用和最近退出码。保存崩溃日志后再重启。

最小故障包包括：

不要提交密码、Token、MediaServer secret、完整授权码、私钥或 Cookie。