更新、備份與疑難排解

Android 版有三條獨立的更新通道。分不清它們，就會出現「點了更新但功能沒變」或者「只想換介面卻重下了 1 GB」。

三條通道

通道	更新什麼	觸發	保留數據
App（APK）	Kotlin 宿主、原生橋、UI	應用內檢查 / 覆蓋安裝	是
Runtime（整包）	Ubuntu rootfs、Python、依賴、OCR	設定頁整包更新	是（config / log 保留）
腳本熱更	上游 AzurPilot 原始碼 + 前端 dist	自動（空閒時）/ 手動	是

App 更新

• 輕量增量 APK 雙 ABI、無 rootfs，下載量小。
• 下載完成後校驗大小與 SHA-256，再交給系統安裝器。
• 簽名必須一致：debug 與 release 不能互相覆蓋，否則 INSTALL_FAILED_UPDATE_INCOMPATIBLE，只能解除安裝重裝（數據全丟）。
• 版本碼回落時用 adb install -r -d。

Runtime 整包更新

判定依據是 BUILD_MANIFEST.rootfs_version：

<上游提交前 12 位>-<构建输入哈希前 10 位>

• 哈希相同、提交不同 → 設定 commitOnly，優先熱更。
• 哈希不同 → 必須整包重部署（Python、系統庫、overlay、依賴變了）。

整包更新會保留 config/（含 SQLite、實例目錄）、password.txt 與 log/；模板與部署種子用新鏡像的版本。

腳本熱更

熱更只換原始碼與前端，不換 Python 與系統庫。流程：

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 與清單。

熱更不會裝依賴

依賴安裝被刻意關閉，避免未經構建與 OCR 驗證的環境進入正式版本。uv.lock 一變，就必須整包。

自動熱更只在排程器與工具空閒時應用；手動更新會恢復原有的實例執行狀態。熱更與整包共用同一把流水線鎖。

什麼時候該用哪種

你的情況	應該
只是上游腳本更新（無依賴變化）	熱更
上游改了依賴 / Python 版本	整包
宿主介面或原生橋變化	APK
換手機、重裝	完整版 APK + 恢復配置
更新後啟動崩潰	看事務日誌，回滾；仍失敗則整包

備份

內容	位置	說明
實例配置	Runtime config/*.json	最重要
部署配置	config/deploy.yaml	含密碼，勿外傳
統計資料庫	config/azurpilot.db	歷史數據
日誌	log/ 與 proot/session.log	疑難排解用，7 天輪轉
遠端身份	config/remote-access.json	需要保留固定入口時

匯出方式：

1. 設定 → 日誌 → 匯出（zip）。
2. 或 adb pull /sdcard/Android/data/com.azurpilot.ghio/files/（部分檔案需 root）。

解除安裝即清空

解除安裝應用會刪除 Runtime、配置、統計與日誌，沒有云端副本。升級前先匯出。

疑難排解

Runtime 起不來

現象	檢查
狀態 NotInstalled	是否點了「下載 Runtime」
狀態 LowDisk	可用空間是否 ≥ 2 GB
狀態 NotBundled	是否裝了輕量包但 Release 無本架構
Failed	展開 reason；換下載源重試
WebUI 90 秒未就緒	首次啟動重建字節碼，屬預期；等待

啟動後閃退

• 架構不符（x86 包裝到 ARM 機）。
• 外部存儲未掛載（應用會快速失敗）。
• 簽名衝突導致實際沒裝上。

權限被系統回收

廠商 ROM 會在後臺清理權限：

• 懸浮窗權限被撤銷 → 浮窗消失。
• 電池最佳化白名單被重置 → 息屏後處理程序被殺。
• 調試授權被撤銷 → 特權服務失效，需重新啟用。

處理：重新授權，並把應用加入自啟動/後臺白名單。

任務中斷

線索	可能原因
日誌突然截斷，無異常棧	處理程序被系統殺死
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 端口
adb forward tcp:25548 tcp:25548

Windows 可用倉庫的 tools/watch-android-logs.ps1，預設跟蹤 com.azurpilot.ghio。

提 Issue 時附：設備型號、Android 版本、架構、Runtime 版本、操作步驟、日誌片段。不要附 deploy.yaml、password.txt、remote-access.json。