更新、備份與遷移

三個組件的版本線互相獨立。理解這一點，才能判斷「點了更新之後到底更新了什麼」。

誰在更新什麼

組件	更新方式	更新內容	需要重新啟動什麼
核心程序	WebUI 更新頁（`updater.*`）	`git pull` 源碼 + 依賴同步	停止並重新啟動實例 worker
啟動器	啟動器自更新（mTLS + 鏡像）	啟動器二進制本身	啟動器
Android App	系統安裝器覆蓋安裝	宿主 Kotlin/C++ 代碼	App
Android Runtime	宿主內 Runtime 更新	rootfs 鏡像（含核心源碼與前端 dist）	Runtime
Android 核心腳本	熱更新通道	上游源碼 + 本地構建前端	Runtime

更新前先備份

任何更新都可能引入不兼容的配置變更。更新前把 config/ 整個目錄複製一份，比事後回滾省事得多。

核心程序

WebUI 的「更新」頁會列出上游提交、當前提交與差異。流程是：

檢查更新（updater.status / updater.commits）。
拉取（updater.fetch）。
應用（updater.apply）：先停止所有 worker，再切換代碼並同步依賴，最後按需重新啟動。

更新頁支援取消（updater.cancel）。如果你在容器裏運行，也可以宿主機手動 git pull + uv sync --frozen 後重新啟動容器。

更新後配置不兼容

配置由 module/config/config_updater.py 生成新模板，舊配置在加載時遷移。遇到字段缺失：

對比 config/<实例>.json 與 config/template.json。
不要手改 args.json、menu.json、config_generated.py——它們是生成產物。
遷移失敗時用備份回滾，再單獨疑難排解是哪個任務組出錯。

啟動器

啟動器啟動時會先更新核心倉庫（git pull，失敗重試至多 20 次），然後 uv sync --frozen。啟動器自身的更新走獨立通道：

預設清單地址：https://launcher-api.azurpilot.com/updata/stable.json。
可用 LAUNCHER_UPDATE_URL 覆蓋，供測試或私有部署使用。
載荷通過 mTLS 校驗，並支援多鏡像回退。

啟動參數 --skip-update 可以跳過倉庫更新，用於斷網或疑難排解「更新後啟動失敗」。

Android

Android 有三條獨立通道，見更新、備份與疑難排解。簡要區分：

只改宿主代碼 → 下載輕量增量 APK 覆蓋安裝，Runtime 與配置保留。
改了 Runtime（依賴、Python 版本、前端構建方式） → 更新 rootfs 鏡像，停服務後替換，保留 /config。
只改上游腳本 → 熱更新：比較 uv.lock，依賴未變則拉源碼並在本地構建前端；失敗自動回滾。

備份

自動備份

核心程序預設開啟每日備份（Alas.Backup.Enable，保留 7 天）。備份寫入項目根目錄：

text

AzurPilot_Data_Backup/
└── 2026-10-20/
    ├── azurpilot.db
    ├── ap.json
    ├── ap-2.json
    └── backup_info.json

備份包含 SQLite 總庫與全部實例配置。資料庫通過 SQLite 備份介面匯出，包含已提交的 WAL。

配置項	預設	説明
`Alas.Backup.Enable`	開	每日首次進入調度循環時執行
`Alas.Backup.KeepDays`	7	超過天數的目錄會被清理

手動備份什麼

路徑	內容	是否必須
`config/*.json`	實例配置（含任務開關與下次運行時間）	必須
`config/deploy.yaml`	後端監聽、密碼、語言	建議
`config/remote-access.json`	遠程訪問設備身份與配對摘要	需要保留固定入口時
`azurpilot.db`（數據目錄）	統計、掉落、資源歷史	需要歷史數據時
`log/`	運行日誌與錯誤現場	疑難排解時
`AzurPilot_Data_Backup/`	自動備份	可選

不要備份進 Git

config/remote-access.json、config/deploy.yaml、password.txt 含憑據。把它們提交到公開倉庫等於公開你的實例入口。

遷移到另一台機器

在舊機器上停止調度

先停止所有實例，避免遷移過程中配置還在被寫入。

複製 config 目錄

連同 deploy.yaml 一起復制。新機器的路徑可以不同，配置裏不寫絕對路徑。

在新機器上安裝

裝啟動器或源碼環境，先啟動一次讓 .venv 與依賴就緒，然後關閉。

覆蓋配置並啟動

把 config/ 覆蓋進新項目根目錄，啟動 WebUI。檢查實例列表是否完整、任務開關是否保留。

重新處理設備相關項

模擬器 Serial、ADB 路徑、截圖方案可能需要按新機器調整。帳號保險庫綁定設備密鑰，換機後需要重新解鎖或錄入。

回滾

核心程序：git log 找到上一個可用提交，git checkout <sha>，再 uv sync --frozen。不要用 git reset --hard 清掉本地修改。
配置：從 AzurPilot_Data_Backup/<日期>/ 複製回 config/。
Android Runtime：宿主保留上一版 rootfs 目錄，熱更新失敗會自動回滾；手動回滾見 Android 維護頁。
啟動器：重新下載上一版壓縮包，覆蓋可執行檔案即可；.venv 與配置不受影響。

更新、備份與遷移

誰在更新什麼 ​

核心程序 ​

更新後配置不兼容 ​

啟動器 ​

Android ​

備份 ​

自動備份 ​

手動備份什麼 ​

遷移到另一台機器 ​

回滾 ​