更新・バックアップ・トラブルシューティング

Android 版には3つの独立した更新チャネルが存在します。これらを明確に区別しておくことで、「更新を実行したのに機能が変わらない」あるいは「UI を変えたいだけなのに無駄に 1 GB のダウンロードが発生した」といった事態を防止できます。

3つの更新チャネル

チャネル	更新対象	トリガー契機	ユーザー設定の保持
App（APK）	Kotlin ホスト、ネイティブブリッジ、UI	アプリ内更新確認 / APK 上書きインストール	保持
Runtime（完全パッケージ）	Ubuntu rootfs、Python、依存関係、OCR ライブラリ	設定画面からの完全更新	保持（config / log を退避維持）
スクリプトホットアップデート	アップストリーム AzurPilot ソースコード ＋ WebUI dist	アイドル時の自動更新 / 手動更新	保持

App（APK）の更新

• 軽量増分 APK はデュアル ABI に対応し rootfs を内包しないため、ダウンロード容量が非常にコンパクトです。
• ダウンロード完了時にサイズと SHA-256 チェックサムを照合し、その後 OS 標準のインストーラーへ引き渡されます。
• 署名鍵の一致が必須です：debug ビルドと release ビルドは相互に上書きできず、INSTALL_FAILED_UPDATE_INCOMPATIBLE が発生した場合はアンインストール（全データ消去）が必要になります。
• バージョンコードのダウングレード時は adb install -r -d を使用してください。

Runtime 完全パッケージ更新

更新の判定は BUILD_MANIFEST.rootfs_version に基づいて行われます：

<アップストリームコミット先頭12文字>-<ビルド入力ハッシュ先頭10文字>

• ハッシュが同一でコミットのみが異なる場合 → commitOnly フラグが立ち、軽量なホットアップデートが優先されます。
• ハッシュ自体が異なる場合 → Python、システムライブラリ、ネイティブバイナリに変更があるため、完全パッケージの再デプロイが必須となります。

完全更新時も config/（SQLite データベース、インスタンス設定含む）、password.txt、log/ は安全に新環境へ引き継がれます。

スクリプトホットアップデート

ホットアップデートは Python やシステムライブラリには手を触れず、AzurPilot のソースコードとフロントエンドのみを置き換えます。処理シーケンス：

1. 対象コミットを確認（デフォルトではビルドマニフェストが指定するブランチを追従）。
2. 指定コミットを /opt/azurpilot-update/source へシャロークローン（CNB を優先し、失敗時は GitHub ミラーへフォールバック）。
3. uv.lock を比較：差分が存在する場合は requiresRuntimeUpdate=true を返し、ホットアップデートを中止して完全更新を要求。
4. 候補ディレクトリ内で npm ci ＋ npm run build を実行（タイムアウト600秒）。
5. ビルド成功後、トランザクションログを記録し、実行中のインスタンスを安全に一時停止。
6. 旧 dist を退避 → ソースコードの差し替え → 新 dist の配置 → マニフェストのアトミック更新 → インスタンスの復旧再起動。
7. いずれかのステップで異常が発生した場合は、直ちに旧ソースコード、dist、マニフェストへロールバック。

ホットアップデートでは Python 依存ライブラリを更新しません

OCR 検証やビルド検証を経ていない未検証ライブラリの混入を防ぐため、ホットアップデート時の Python 依存関係更新は意図的に遮断されています。uv.lock に変更が生じた場合は必ず完全パッケージ更新を行ってください。

自動ホットアップデートはスケジューラーおよびツールが完全に待機状態にある時のみ適用されます。手動更新時は更新完了後に以前の実行状態が自動復帰します。

適切な更新手段の選び方

ユーザーの状況	選択すべき手段
アップストリームの自動化スクリプトのみ更新された（依存変更なし）	スクリプトホットアップデート
アップストリームで Python ライブラリや基本依存が更新された	Runtime 完全パッケージ更新
Android ホストの画面、UI、ネイティブブリッジ機能が更新された	App（APK）の更新
機種変更、端末の初期化時	完全版 APK の導入 ＋ 設定復元
更新後にアプリが起動時クラッシュする	トランザクションログを確認しロールバック。解決しない場合は完全更新

バックアップ対象と手順

対象データ	格納パス	重要度
インスタンス設定	Runtime 内 config/*.json	最重要（タスク構成とスケジュール）
デプロイ設定	config/deploy.yaml	パスワードを含むため取り扱いに注意
統計データベース	config/azurpilot.db	周回履歴、資材推移、ドロップ記録
ログファイル	log/ および proot/session.log	障害調査用（7日間自動ローテーション）
リモート認証情報	config/remote-access.json	固定接続先を維持したい場合に必要

エクスポート方法：

1. アプリ内：設定 → ログ → 「ログと設定のエクスポート」（ZIP 形式）。
2. または PC から ADB を使用：adb pull /sdcard/Android/data/com.azurpilot.ghio/files/（一部ファイルはアクセス制限あり）。

アンインストール時の全消去

アプリをアンインストールすると、Runtime、設定ファイル、統計データベース、ログがすべて消去され、復旧手段はありません。バージョンアップや端末移行の前には必ずバックアップを出力してください。

トラブルシューティング

Runtime が起動しない

症状	確認事項
ステータスが NotInstalled	ホーム画面で「Runtime をダウンロード」をタップして展開したか確認
ステータスが LowDisk	端末の空き容量が 2 GB 以上あるか確認
ステータスが NotBundled	軽量版 APK を使用しているが Release に当該アーキテクチャのファイルがない
ステータスが Failed	詳細の reason を確認。ダウンロードソースを変更して再試行
WebUI が90秒以上開かない	初回起動時のバイトコード再コンパイル中。異常ではないため待機

起動直後にアプリがクラッシュする

• CPU アーキテクチャの不一致（ARM 端末に x86 パッケージを導入しているなど）。
• 外部ストレージのアクセス権限不備（アプリ起動時に即時終了します）。
• 異なるビルド署名間の上書き失敗によるバイナリ破損。

権限が OS に勝手に剥奪される

メーカー製 ROM のバックグラウンドオプティマイザによる介入：

• オーバーレイ権限の剥奪 → フローティングパネルが消滅。
• バッテリー最適化除外のリセット → 画面消灯直後にプロセスが終了される。
• ADB デバッグ認可の失効 → 特権サービスが停止。再アクティベーションが必要。

対処：アプリをシステムの「自動起動」「バックグラウンド動作許可」リストに登録してください。

周回タスクが途中で停止する

手がかり	推定原因と対策
ログがある時刻で突然途絶えている	OS によりプロセスがメモリから強制終了された
EmulatorNotRunningError	仮想ディスプレイまたは特権サービスが終了した
ScriptError が3回連続発生	スクリプトの不具合。最新版へのホットアップデートを確認
ホットアップデート後に起動クラッシュ	トランザクションロールバックの失敗。/config/android-update-transaction.json を確認
フロントエンドビルドのタイムアウト	端末スペック不足または通信遅延。旧バージョンを維持して後ほど再試行

診断ログの採取コマンド

# アプリケーションログのリアルタイム取得
adb logcat -v time --pid=$(adb shell pidof com.azurpilot.ghio)

# Runtime 内部の標準出力ログ
adb shell tail -n 200 /sdcard/Android/data/com.azurpilot.ghio/files/log/proot/session.log

# WebUI ポートの PC 側へのフォワーディング
adb forward tcp:25548 tcp:25548

Windows 環境ではリポジトリ付属の tools/watch-android-logs.ps1 スクリプトが利用可能です。

Issue 報告時は以下の情報を添えてください：端末モデル名、Android バージョン、CPU アーキテクチャ、Runtime バージョン、不具合の再現手順、ログ抜粋。deploy.yaml、password.txt、remote-access.json などの機密ファイルは絶対に添付しないでください。