---
title: 更新・バックアップ・トラブルシューティング
description: APK、Runtime、スクリプトホットアップデートの3系統の更新仕様、判定ロジック、データ保護と復旧手順。
updated: 2026-10-20
---

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

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

## <DocIcon name="refresh" /> 3つの更新チャネル

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

### <DocIcon name="smartphone" /> App（APK）の更新

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

### <DocIcon name="package" /> Runtime 完全パッケージ更新

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

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

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

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

### <DocIcon name="zap" /> スクリプトホットアップデート

ホットアップデートは 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、マニフェストへロールバック。

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

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

## <DocIcon name="compass" /> 適切な更新手段の選び方

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

## <DocIcon name="drive" /> バックアップ対象と手順

| 対象データ | 格納パス | 重要度 |
| --- | --- | --- |
| インスタンス設定 | 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/`（一部ファイルはアクセス制限あり）。

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

## <DocIcon name="wrench" /> トラブルシューティング

### <DocIcon name="circle-alert" /> Runtime が起動しない

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

### <DocIcon name="circle-alert" /> 起動直後にアプリがクラッシュする

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

### <DocIcon name="lock" /> 権限が OS に勝手に剥奪される

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

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

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

### <DocIcon name="circle-alert" /> 周回タスクが途中で停止する

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

### <DocIcon name="clipboard" /> 診断ログの採取コマンド

```bash
# アプリケーションログのリアルタイム取得
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` などの機密ファイルは絶対に添付しないでください。**