故障排查

本文按故障現象組織排查步驟。通用原則：先執行唯讀查詢收集證據，再做任何修改性操作；每一步記錄觀察到的現象、執行的命令與退出碼、預期與實際的差異。

裝置不可達（SSH 連不上）

分層定位，不要混在一起判斷：

與裝置清冊核對位址（相似位址不能互換）；
依次確認位址解析、路由、SSH 埠連通性、驗證方式；
裝置曾經可達、突然失聯時，關聯最近的更新或重新啟動時間，必要時請求現場檢查序列埠或實體狀態。

啟動失敗或反覆重新啟動

收集啟動輸出、上一次啟動的記錄（journalctl -b -1）、看門狗復位原因與檔案系統錯誤；
區分故障階段：載入程式、核心、系統切換、服務啟動、看門狗復位或應用觸發；
檢視啟動計數（bootcount）：連續啟動失敗會觸發自動復原策略——達到閾值後依次進入復原模式、分割區回復（見A/B 雙系統與切換）；
透過 jelina-info 與 jelina-auto-recovery --state 檢視目前恢復狀態。

未確認原因前不要手動切換分割區或回復，以免破壞自動復原流程。

系統進入異常狀態（degraded）

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

逐個檢查失敗的服務，再檢查核心服務。注意：可選平台相關服務的失敗不代表系統異常；一次性服務執行完畢後處於非活動狀態也屬正常。

更新卡住

檢視更新狀態與進度（jelina-info --get ota_status --json、jelina-local-ota -s）；
檢查是否有待確認的更新（本機確認機制下，等待確認是策略狀態，不是卡死）；
檢查裝置代理程式服務與記錄；
檢查磁碟空間、更新安裝器狀態與行程；
檢查更新套件可達性、系統時鐘、網域名稱解析與憑證；
判斷是否其實已安裝完成，只是在等待重新啟動或重新掛載生效。

排查期間不要重複提交或確認更新，也不要刪除待重新啟動的狀態標記。

應用或容器不可用

分開檢查各環節：期望狀態、映像下載、容器建立、行程健康、埠與防火牆、應用自身狀態。常用命令：

docker ps                # 容器狀態
docker logs <容器名>      # 容器記錄

儲存現場證據前，不要手工重建由系統管理的容器或服務。

磁碟滿或根目錄唯讀

對比根分割區與資料分割區的空間和檔案數佔用（df -hT、df -i）；
檢查是否已進入臨時根模式（jelina-enter-tmpfs-root --status，見儲存與資料分割區）；
區分三種情況：系統分割區本來就是唯讀（正常設計）、資料分割區故障、疊加層未正常掛載。

不要刪除不認識的系統目錄或軟體套件目錄；臨時根模式下請勿進行業務操作。

註冊失敗或雲端離線

檢視註冊狀態（jelina-manual-register --check，見裝置註冊與連線）；
檢查是否處於離線模式；
檢查系統時鐘、網域名稱解析、路由、憑證與雲端端點可達性；
檢查註冊服務與裝置代理程式服務的狀態與錯誤訊息；
區分故障類別：初次開通未完成、憑證失效、網路故障、雲端拒絕。

服務無法啟動

依次檢查：服務啟動條件、程式檔案是否存在與權限、指令碼直譯器、依賴的掛載是否就緒。

時間或網域名稱解析異常

時間異常常表現為憑證檢查或雲端驗證失敗：對比系統時間、硬體時鐘、時間同步服務記錄；
網域名稱解析異常：檢查解析服務狀態與網路連線設定，不要手工覆蓋系統產生的解析設定檔案。

介面（GUI）不可用

透過 SSH 登入的終端通常沒有桌面工作階段環境，顯示變數為空不代表介面故障：

確認介面總開關與停用範圍；
檢查介面實例與工作階段狀態（jelina-ui-ctl list、jelina-ui-ctl sessions）；
檢查活躍的圖形登入工作階段，並在目標使用者環境中檢視介面行程狀態與記錄。

重新啟動類問題的歷史證據

部分裝置啟用歷史效能歸檔與持久化記錄，可用於回溯重新啟動前的系統狀態：

journalctl --list-boots              # 啟動清單
journalctl -b -1 -p warning..alert   # 上一次啟動的告警記錄
ls -1t /var/log/atop | head          # 歷史效能歸檔

意外重新啟動的歸因需關聯：啟動清單、上一次啟動的記錄、看門狗復位原因、執行時長與更新/分割區切換歷史。

相關文件

FAQs — 常見問題解答
A/B 雙系統與切換 — 啟動計數與回復
看門狗 — 系統健康守護
系統狀態與資訊 — 狀態查詢命令