附录 C 故障速查表
用法：按现象查表 → 看判据定位 → 按处理步骤操作 → 需要细节时跳到对应章节。 判据列写的是「凭什么断定是这个原因」，不要跳过判据直接照处理做。
C.1 登录与权限
| 现象 | 判据 | 处理 | 章节 |
|---|---|---|---|
| 登录提示「用户名或密码错误」 | 账号密码本身错 | 核对大小写；连续失败会触发锁定 | 2.1 |
| 登录提示账号被锁定 | 失败次数达到「登录失败锁定阈值」 | 等锁定时长到期，或管理员在登录日志页解锁 | 2.1、19.x、21.1.3 |
| 登录后一片空白 / 左侧没有菜单 | 账号没挂角色，或角色没勾菜单 | 角色管理给该角色勾菜单后重新登录 | 21.2、A.3 |
| 能进页面，按钮全灰 | 只给了菜单没给按钮权限码 | 角色 →「分配权限」→ 勾到按钮节点；重新登录 | 21.2.2、A.3 |
| 按钮能点但报「没有权限」/403 | API 权限没配，或接口登记路径不符 | 菜单管理 →「API权限」补配；核对接口路径 | 21.5.3、21.8 |
| 首次登录被要求改密码 | 平台强制首次改密 | 正常流程，按提示改 | 2.2 |
C.2 设备与画面
| 现象 | 判据 | 处理 | 章节 |
|---|---|---|---|
| 设备一直离线 | 平台从未收到该设备的注册/心跳；设备列表「最后心跳」为空或很早 | 查设备侧 SIP 配置（服务器地址、端口、域、ID、密码）与网络可达性 | 4.17、14.x |
| 设备在线，但通道列表为空 | 目录未同步 | 「刷新设备目录」，看进度弹窗的失败原因 | 4.10 |
| 点播后黑屏 | 播放窗口有地址但无画面；播放日志有失败原因 | 先看播放日志的失败归类；再换协议试 | 5.9、19.x |
| 点播提示「点播失败」（47B） | 媒体操作被归属/授权闸门拦住 | 检查设备的归属与授权状态 | 5.9、16.x |
| 画面卡顿、花屏 | 码率与网络不匹配 | 降协议或降码流；用视频探针看码率 / 帧率 | 5.7、5.9 |
| 云台点了没反应 | 设备不支持该指令族，或参数位置不对 | 确认设备支持的云台指令集；用预置位测试连通性 | 5.5 |
| 对讲点了没反应、30 秒后过期 | 媒体节点的回调地址失效（旧地址/无能力） | 由运维核查媒体节点回调配置 | 5.x、18.x |
C.3 录像
| 现象 | 判据 | 处理 | 章节 |
|---|---|---|---|
| 云端录像「设备/通道」两列为空 | 该录像写入时通道已被删除，归属名称只快照一次 | 触发对账回填；无编码的历史记录无法补 | 7.11 |
| 录像缓存任务「秒成功」但文件很短 | 取流未登记保流租约，媒体端 20 秒判无人观看 | 属平台缺陷，需升级到修复版本 | 8.8 |
| 缓存任务进度长时间 0% | 进度只在整片收尾时落库 | 看「速率」是否在跑；速率在跑说明正在传，不是卡死 | 8.5 |
| 缓存任务停不下来 | 任务已进入「合并中」 | 合并中不可停止，等其结束 | 8.6 |
| 下载录像没有反应 | 浏览器拦截了原生下载 | 允许本站下载弹窗；重试 | 7.7 |
| 回放查不到录像 | 设备不在线，或时间范围超出存储卡保留期 | 看设备在线状态；缩小时间范围 | 10.3、10.8 |
| 回放页提示「通道参数无效」 | 地址里的通道号被手改坏 | 从「设备列表 → 查看通道」进入回放，不要手工拼地址 | 10.3 |
C.4 告警与图像
| 现象 | 判据 | 处理 | 章节 |
|---|---|---|---|
| 收不到设备告警 | 设备未订阅报警，或平台未收到报警报文 | 检查「订阅管理」是否有报警订阅；看 SIP 日志有无 Alarm 报文 | 4.11、11.8 |
| 图像库某张图打不开 | 文件已被清理或存储不可达 | 看该记录的存储位置与保留策略 | 12.9 |
| 搜索不到明明存在的图 | 搜索框只在当前页过滤 | 用检索条件让后端过滤（本页搜索走后端） | 12.4 |
C.5 级联
| 现象 | 判据 | 处理 | 章节 |
|---|---|---|---|
| 上级平台看不到本平台 | 注册状态「离线」或「注册失败」 | 核对上级编码、IP、端口、域、传输协议与注册密码 | 13.5、13.8 |
| 上级能看到目录，但点播失败 | 目录共享了，媒体通道未通 | 检查上级与本平台之间的媒体网络与端口 | 13.6 |
C.6 媒体与运维
| 现象 | 判据 | 处理 | 章节 |
|---|---|---|---|
| 点「重启当前节点」没反应 / 一直等 | 停机时间短于离线判定阈值，且启动事件被吞 | 等宽限期结束由心跳兜底；仍失败则查节点详情 | 18.3 |
| 节点「最后心跳」恒为「从未上报」 | 平台接入晚于媒体节点启动 | 触发一次主动探测刷新存活时间 | 18.3 |
| 直播不出画面但 m3u8 地址能播 | 媒体节点录像根路径与 HLS 保存路径错位 | 由运维核对节点路径配置 | 18.6 |
| 日志中心看不到某类日志 | 账号缺对应查看权限 | 角色管理补 gb28181:log:view / gb28181:play-log:view | 19.x、A.1 |
C.7 OpenAPI
| 现象 | 判据 | 处理 | 章节 |
|---|---|---|---|
| 第三方 401 | 认证状态不是「启用」，或 SK 已轮换 | 看列表「认证状态」与「密钥版本」；必要时轮换并重新下发 | 20.5、20.11 |
| 第三方 403 | 能力未授权，或数据范围不含目标设备 | 详情页搜该能力看开关；核实数据范围 | 20.9、20.11 |
| 第三方 429 | 超过调用速度 / 突发容量 / 观看配额 | 让对接方退避重试；确需扩额只能重建客户端 | 20.7、20.11 |
| 授权页全灰 | 客户端处于停用/已撤销，或缺 grant 权限 | 先启用客户端；确认权限 | 20.6、20.9 |
| 保存授权报 503 | 服务端异常 | 稍后重试；持续出现报管理员查服务日志 | 20.9 |
C.8 系统与升级
| 现象 | 判据 | 处理 | 章节 |
|---|---|---|---|
| 某字典改不动、按钮灰 | 系统内置字典（编码带锁图标） | 只读是设计行为，需改请走发版 | 21.4.1 |
| 改了字典界面没变 | 字典缓存持久化在浏览器本地 | 按 F5 刷新 | 21.4 |
| 升级页版本号显示不出来、提示「部署方式暂不可用」 | 升级助手不可用，页面用前端构建身份兜底 | 版本号仍可信；联系运维启动升级助手 | 21.9.1 |
| 升级页提示「升级助手未运行或暂未就绪（HTTP 503）」 | 升级助手未启动或未就绪 | 联系运维；不影响平台其他功能 | 21.9.1 |
| 「开始升级」是灰的 | 升级预检未通过，或已有进行中的任务 | 点「查看原因」看诊断信息；等现有任务结束 | 21.9.2 |
| 升级后界面还是旧的 | 后端已新、前端入口未刷新 | 点「立即刷新前端」或强制刷新（Ctrl/Cmd + Shift + R） | 21.9.2 |
| 升级后仍显示「待迁移 N 项」 | 数据库迁移未执行完 | 看任务详情的失败阶段，按交付文档补迁移 | 21.9.3 |
| 回退后服务起不来 | 回退不撤销数据库迁移，表结构与旧版本不匹配 | 回退前必须确认该次升级未执行迁移，或已备份数据库 | 21.9.3 |
| 定时任务不执行 | 任务被停用，或 Cron 表达式非法，或执行器不可用 | 看列表状态、Cron、以及执行日志里的错误信息 | 21.10 |
| 强退自己那一行按钮是灰的 | 当前会话不允许自我强退 | 用右上角头像菜单退出登录 | 21.7 |