故障排查

本文按故障现象组织排查步骤。通用原则：先执行只读查询收集证据，再做任何修改性操作；每一步记录观察到的现象、执行的命令与退出码、预期与实际的差异。

设备不可达（SSH 连不上）

分层定位，不要混在一起判断：

1. 与设备台账核对地址（相似地址不能互换）；
2. 依次确认地址解析、路由、SSH 端口连通性、认证方式；
3. 设备曾经可达、突然失联时，关联最近的更新或重启时间，必要时请求现场检查串口或物理状态。

启动失败或反复重启

1. 收集启动输出、上一次启动的日志（journalctl -b -1）、看门狗复位原因与文件系统错误；
2. 区分故障阶段：引导程序、内核、系统切换、服务启动、看门狗复位或应用触发；
3. 查看启动计数（bootcount）：连续启动失败会触发自动恢复策略——达到阈值后依次进入恢复模式、分区回滚（见A/B 双系统与切换）；
4. 通过 jelina-info 与 jelina-auto-recovery --state 查看当前恢复状态。

未确认原因前不要手动切换分区或回滚，以免破坏自动恢复流程。

系统进入异常状态（degraded）

systemctl is-system-running
systemctl --failed --no-pager

逐个检查失败的服务，再检查核心服务。注意：可选平台相关服务的失败不代表系统异常；一次性服务执行完毕后处于非活动状态也属正常。

更新卡住

1. 查看更新状态与进度（jelina-info --get ota_status --json、jelina-local-ota -s）；
2. 检查是否有待确认的更新（本地确认机制下，等待确认是策略状态，不是卡死）；
3. 检查设备代理服务与日志；
4. 检查磁盘空间、更新安装器状态与进程；
5. 检查更新包可达性、系统时钟、域名解析与证书；
6. 判断是否其实已安装完成，只是在等待重启或重新挂载生效。

排查期间不要重复提交或确认更新，也不要删除待重启的状态标记。

应用或容器不可用

分开检查各环节：期望状态、镜像下载、容器创建、进程健康、端口与防火墙、应用自身状态。常用命令：

docker ps                # 容器状态
docker logs <容器名>      # 容器日志

保存现场证据前，不要手工重建由系统管理的容器或服务。

磁盘满或根目录只读

1. 对比根分区与数据分区的空间和文件数占用（df -hT、df -i）；
2. 检查是否已进入临时根模式（jelina-enter-tmpfs-root --status，见存储与数据分区）；
3. 区分三种情况：系统分区本来就是只读（正常设计）、数据分区故障、叠加层未正常挂载。

不要删除不认识的系统目录或软件包目录；临时根模式下请勿进行业务操作。

注册失败或云端离线

1. 查看注册状态（jelina-manual-register --check，见设备注册与连接）；
2. 检查是否处于离线模式；
3. 检查系统时钟、域名解析、路由、证书与云端端点可达性；
4. 检查注册服务与设备代理服务的状态与报错；
5. 区分故障类别：初次开通未完成、凭证失效、网络故障、云端拒绝。

服务无法启动

依次检查：服务启动条件、程序文件是否存在与权限、脚本解释器、依赖的挂载是否就绪。

时间或域名解析异常

• 时间异常常表现为证书校验或云端认证失败：对比系统时间、硬件时钟、时间同步服务日志；
• 域名解析异常：检查解析服务状态与网络连接配置，不要手工覆盖系统生成的解析配置文件。

界面（GUI）不可用

通过 SSH 登录的终端通常没有桌面会话环境，显示变量为空不代表界面故障：

1. 确认界面总开关与禁用范围；
2. 检查界面实例与会话状态（jelina-ui-ctl list、jelina-ui-ctl sessions）；
3. 检查活跃的图形登录会话，并在目标用户环境中查看界面进程状态与日志。

重启类问题的历史证据

部分设备启用历史性能归档与持久化日志，可用于回溯重启前的系统状态：

journalctl --list-boots              # 启动列表
journalctl -b -1 -p warning..alert   # 上一次启动的告警日志
ls -1t /var/log/atop | head          # 历史性能归档

意外重启的归因需关联：启动列表、上一次启动的日志、看门狗复位原因、运行时长与更新/分区切换历史。

相关文档

• FAQs — 常见问题解答
• A/B 双系统与切换 — 启动计数与回滚
• 看门狗 — 系统健康守护
• 系统状态与信息 — 状态查询命令