トラブルシューティング

症状ごとに調査手順を説明します。まず読み取り専用の照会で証拠を集め、その後で変更操作を行うことが基本です。各段階で観測内容、実行コマンドと終了コード、期待と実際の違いを記録してください。

デバイスにアクセスできない（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 つずつ確認し、その後主要サービスを調べます。任意のプラットフォーム固有サービスの失敗が、必ずしもシステム異常を意味するわけではありません。ワンショットサービスが完了後に非アクティブになるのも正常です。

更新が進まない

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 で、ルートとデータの容量・inode 使用量を比較します。
2. jelina-enter-tmpfs-root --status で一時ルートモードか確認します。ストレージとデータパーティションを参照してください。
3. 設計どおりの読み取り専用システム、データパーティション障害、オーバーレイのマウント失敗を区別します。

不明なシステム・パッケージディレクトリを削除しないでください。一時ルートでは業務操作を行わないでください。

登録失敗・クラウドがオフライン

1. jelina-manual-register --check で登録状態を確認します。デバイスの登録と接続を参照してください。
2. オフラインモードになっていないか確認します。
3. 時刻、名前解決、ルーティング、証明書、クラウドエンドポイントへの到達性を確認します。
4. 登録サービスとエージェントの状態・エラーを確認します。
5. 初回有効化の未完了、認証情報の失効、ネットワーク障害、クラウドの拒否を区別します。

サービスが起動しない

起動条件、プログラムファイルの存在と権限、スクリプトインタープリター、依存するマウントの準備状況を順に確認します。

時刻・名前解決の異常

• 時刻異常は証明書検証やクラウド認証の失敗として現れます。システム時刻、ハードウェアクロック、同期サービスのログを比較します。
• 名前解決異常では、リゾルバーの状態と接続設定を確認します。システムが生成した名前解決設定ファイルを手動で上書きしないでください。

GUI が使用できない

SSH ターミナルには通常デスクトップセッション環境がありません。表示変数が空でも、GUI の故障とは限りません。

1. UI 全体の有効・無効と無効化範囲を確認します。
2. jelina-ui-ctl list と jelina-ui-ctl sessions でインスタンスとセッションを確認します。
3. アクティブなグラフィカルログインセッションを調べ、対象ユーザーの環境で UI プロセスとログを確認します。

再起動問題の履歴調査

一部のデバイスは性能履歴のアーカイブと永続ログを有効にしており、再起動前の状態を追跡できます。

journalctl --list-boots              # 起動一覧
journalctl -b -1 -p warning..alert   # 前回起動時の警告ログ
ls -1t /var/log/atop | head          # 過去の性能アーカイブ

予期しない再起動の原因を特定するには、起動一覧、前回のログ、ウォッチドッグ理由、稼働時間、更新とパーティション切り替えの履歴を照合してください。

関連ドキュメント

• FAQ — よくある質問
• A/B デュアルシステムと切り替え — 起動カウントとロールバック
• ウォッチドッグ — システムの健全性
• システム状態と情報 — 状態照会コマンド