更新、备份与迁移

三个组件的版本线互相独立。理解这一点，才能判断「点了更新之后到底更新了什么」。

谁在更新什么

组件	更新方式	更新内容	需要重启什么
核心程序	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 ​

备份 ​

自动备份 ​

手动备份什么 ​

迁移到另一台机器 ​

回滚 ​