Android トラブルシューティング
発生フェーズ別の切り分け
| フェーズ | 主な症状 | 最初に確認すべきポイント |
|---|---|---|
| インストール | パッケージ解析エラー、即時クラッシュ | アーキテクチャの適合、APK 署名の整合性 |
| デプロイ | Checking / Downloading / Extracting で停止 | ネットワーク疎通、空きストレージ容量、ABI |
| 起動 | Runtime が立ち上がらない | アプリ内ログ、WebUI の準備状況 |
| アクティベーション | ペアリング完了後にサービスが起動しない | USB デバッグの常時許可、ポート 5555 の疎通 |
| 周回実行 | 仮想画面が真っ暗、タップが反応しない | 特権サービスの状態、設定された操作方式 |
| バックグラウンド | 画面消灯後に処理が停止する | バッテリー最適化設定、プロセスの常駐保護 |
| アップデート | ホットアップデート失敗、起動時クラッシュ | トランザクションログの確認、ロールバック |
インストールとデプロイ
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| パッケージ解析エラー | ダウンロード不完全、または非対応アーキテクチャ | 端末の ABI に合致する APK を再ダウンロード |
| 起動直後にアプリがクラッシュ | 32ビット端末、または非対応アーキテクチャ | 64ビット対応の端末を使用してください |
ステータスが NotBundled | 軽量版 APK かつ該当 ABI の Runtime が未配置 | 完全版 APK をダウンロードしてインストール |
ステータスが LowDisk | 空きストレージ容量が 2GB 未満 | 端末の不要データを削除して空き容量を確保 |
| ダウンロードが途中で停止 | ミラーサイトのアクセス制限、プロキシによる遮断 | ダウンロードソースを切り替え |
| ハッシュ検証エラー | ダウンロード成果物の破損 | 不完全ファイルを削除して再ダウンロード |
| 展開処理の失敗 | ストレージ不足、または展開処理の中断 | 再試行。解決しない場合は完全版 APK を使用 |
初回の WebUI 起動遅延について
初期状態では __pycache__ が除去されているため、初回起動時のバイトコードコンパイルに90秒以上かかる場合があります。ログに出力される WebUI not ready within 90000ms は想定内の警告メッセージです。
権限とアクティベーション
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| ペアリング成功後もサービス未起動 | USB デバッグの認証ダイアログが未許可 | 再ペアリングし「このPCから常に許可」をチェック |
| 端末再起動後に権限が喪失 | adbd のデバッグ認可は再起動でリセット | 再度アクティベーションを実行（Android の正常な仕様です） |
Binder 通信タイムアウト | 特権サービスプロセスがシステムに強制終了された | バッテリー最適化を解除し、再度アクティベーション |
| 外部 Shizuku に接続できない | Shizuku マネージャーが停止、または権限が剥奪された | Shizuku アプリを開き再認可を実行 |
| MediaTek 搭載端末でのクラッシュ | メーカー製 ROM による独自プロセス注入 | 本アプリは Context-only パスを採用済み。解決しない場合はログを添付 |
| ネットワーク切断後に再接続不可 | OS によりデバッグポートが回収された | 同一起動内であれば再接続可能。再起動後は再アクティベーションが必要 |
仮想画面と描画
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| 周回画面が真っ暗 | 特権サービスがアクティベートされていない | アクティベーション状態を確認 |
| 画面は表示されるがタップ不能 | 操作方式が azurpilot_android 以外に設定されている | 操作方式をホスト専用の方式に変更 |
| 画面がフリーズする | ゲームクライアントプロセスが無応答 | ゲームアプリまたはインスタンスを再起動 |
| メイン画面がゲームに奪われる | ゲームが仮想画面ではなく実画面で起動された | 仮想画面が正常に生成されているか確認 |
| 外部 SDK ログイン画面が実画面に飛ぶ | OEM によるアクティビティのリダイレクト | SdkTaskRepatriator が自動回収を試みます。戻らない場合は手動操作 |
バックグラウンド強制終了への対策
| 手がかり | 主な原因 | 対処方法 |
|---|---|---|
| ログがある時点で突然途絶 | OS によるプロセス kill | バッテリー使用量を「制限なし」に設定 |
| 画面消灯から数分で停止 | メーカー独自の省電力タスクキラー | 自動起動許可およびタスクキル除外リストに登録 |
| 特定のメーカー ROM でのみ頻発 | 各社独自のアグレッシブな省電力機能 | 当該 ROM 固有のバックグラウンド実行ガイドラインを確認 |
| フォアグラウンド通知が消滅 | フォアグラウンドサービスが終了された | Runtime サービスを再起動 |
常駐対策の限界
極端な省電力設定が適用された一部の端末では、OS による強制終了を完全に防ぐことはできません。極めて重要な周回処理は PC 環境での実行をお勧めします。
ホットアップデートと完全更新
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| 「完全パッケージ更新が必要」と警告 | uv.lock（依存関係）に変更あり | 完全パッケージまたは Runtime イメージの更新を実施 |
| ホットアップデート後にクラッシュ | トランザクションロールバックの失敗 | config/android-update-transaction.json を確認 |
| フロントエンドのビルドがタイムアウト | 端末スペック不足またはネットワーク遅延 | 旧バージョンを維持し、通信環境が安定した際に再試行 |
| 更新後に設定が消失 | プロセス異常終了によるディスク破損 | バックアップから config/ を復元 |
| アプリ更新がインストールできない | 署名鍵の不一致（ビルド元が異なる） | データをエクスポートした上で、アンインストール後に再導入 |
リモートクライアントモード
| 現象 | 主な原因 | 対処方法 |
|---|---|---|
| QR コードをスキャンしても無反応 | QR コードの有効期限切れ | ホスト側で QR コードを再生成 |
| 接続は完了したが読み込みが完了しない | 中継経路での WebSocket 遮断 | ネットワーク環境を変更 |
UNAUTHORIZED が返却される | ペアリングがホスト側で解除された | 再度ペアリングを実施 |
| アプリをバックグラウンドに回すと切断 | バックグラウンド通信の制限 | アプリのバックグラウンドデータ通信を許可 |
ログの確認とエクスポート
bash
adb logcat -v time --pid=$(adb shell pidof com.azurpilot.ghio)
adb shell tail -n 200 /sdcard/Android/data/com.azurpilot.ghio/files/log/proot/session.log
adb forward tcp:25548 tcp:25548アプリ内の「ログ → エクスポート」機能により zip アーカイブを出力可能です。共有前に機密情報が含まれていないか確認してください。
互換性の目安
| デバイス | サポート状況 |
|---|---|
| Android 12〜15 ARM64 主要メーカー端末 | 推奨環境 |
| Android 9〜10 | 動作可能（ペアリングに adb tcpip 5555 が必要） |
| x86_64 エミュレーター | 動作可能（専用 Runtime が必要） |
| 32ビット端末 | 非サポート |
| 一部の高度にカスタマイズされた ROM | フローティング表示や常駐保護の挙動要実測 |
| Samsung Exynos / Google Tensor | OCR は CPU フォールバック動作 |