常见问题：
故障决策表 | 故障现象 | 只读检查与判断 | 受控恢复 | 必须停止的条件 |
|---|---|---|---|
| 无法连接 | 查 LAN、本机网段、ping、REST 9091、SSH 22 | 修正开发电脑网卡或使用已知正常链路 | 不重置路由器、改机器人静态 IP 或恢复出厂 |
| service list 有服务但 node info 无节点 | source 两个环境，执行 ros2 daemon stop 后重查；用精确进程名核对 | daemon 重建；只有确认无进程、无录制且获授权才恢复 recorder | 已有同名进程、正在录制或版本不明 |
| Topic 无数据 | topic type/info -v/echo --once，查发布者、QoS、Domain ID | 修正消息包、QoS 或订阅配置 | 不因单 Topic 超时就切模式、重启整机或停未知服务 |
| 控制无运动 | 查控制权、模式、急停、使能、错误位、限位、单位和回读 | 使用已验证停止，恢复前保存原状态 | 不因响应成功就连续重发、盲使能/清错/改限位 |
| 录制失败/超时 | 核对六字段和整数 operate，查 Service、精确进程、录制中/完成目录 | 结果未知时先 stop 和查唯一 run ID | 不盲重试 start、启第二实例或清空根目录 |
| 整栈服务重启慢或启动日志报错 | 查 systemctl show/status、MainPID、Result、精确时间段 journal，再验版本、Topic/Service、错误位、零速、相机和录制服务 | 只允许一次已授权 start 恢复；记录退出超时和无 TTY 命令以供单元整改 | 不反复 restart、不用模糊进程匹配强制终止、不因单条报错就声称整栈失败或成功 |
| 相机帧率波动 | 一次只测一路；查 camera FPS 状态和 MCAP count/duration，对比 camera_info/image | 评估降路数/分辨率或错开负载 | 不用并行多路 topic hz 定责，不直接套全局调优 |
| camera FPS 数组为 0，但 H.264 有流 | 对目标 .../h264 用 BEST_EFFORT 只取 header，再查编码日志的计数、队列、丢帧和耗时 | 先确认监控数组映射；按目标流的连续解码结果判定 | 不因 FPS 数组为 0 重启相机，也不因单帧时间戳宣称画面正常 |
| 聚合健康 100，但日志有部件连接失败 | 核对当前硬件变体、目标端点、/diagnostics、关节错误位和精确时间段日志 | 可选部件不适用时记录配置；必需部件不可达时升级支持 | 不把聚合分数作为唯一判据，不盲目清错或持续 ping 未知设备 |
| 数据追踪心跳频率与定义不一致 | 查 TraceHeartbeat 接口、节点启动日志、当前配置和 35 秒以上观察窗口 | 由后续版本统一修正接口注释与配置后再使用 | 修正前不把 /trace/heartbeat/status 作为可用性判据，不调用写配置接口 |
| 录制目录存在但 NVMe 未挂载 | findmnt -T /home/realman/ssd、df -h、块设备来源和目录水位交叉确认 | 停止新录制并由管理员恢复正确挂载 | 不把空挂载点目录当作 SSD，不让数据回落系统盘 |
| TF 不完整 | 查 /tf、/tf_static、连通关系与 TRANSIENT_LOCAL | 臂/头/腰用 URDF+关节角，相机用标定外参 | 不伪造静态变换掩盖断树 |
| HTTP 桥 401/502/超时 | 401 查 token 注入但不打印；502/超时查 ROS2 与真实录制状态 | 修复凭据、隧道或服务，保持 loopback | 不改绑 0.0.0.0 绕故障，不盲重试 start |
| 磁盘不足 | df、精确目录 du、run ID、拉取/解析/校验结果 | 仅对已确认且经授权的直接子目录精确清理 | 禁止通配、前缀匹配、整根目录或“拉取即删” |