更新、修復與移除
啟動器有兩個獨立版本：啟動器自身和核心程序。搞清楚誰更新了誰，才能判斷「為什麼介面變了但功能沒變」。
兩條更新線
| 核心程序 | 啟動器 | |
|---|---|---|
| 更新方式 | 啟動時 git pull + uv sync --frozen | 自更新（mTLS + 多鏡像） |
| 頻率 | 跟隨 master，每天可能有提交 | 帶版本號的 Release |
| 影響 | 遊戲功能、WebUI、API | 外殼、啟動流程、進程管理 |
| 回滾 | git checkout <sha> | 換回舊版壓縮包 |
更新核心後會發生什麼
- 啟動器下次啟動時
git pull拉到新代碼。 uv sync --frozen按新uv.lock調整依賴。gui.py的ensure_frontend()檢查frontend/dist，必要時重新構建（需要 Node.js）。- WebUI 刷新即生效；正在運行的實例會被停止並重新啟動。
前端構建需要 Node
Windows 上啟動器會檢測系統級 Node.js，缺失時可自動下載安裝（SHA-256 校驗）。Linux / macOS 需要自備 Node，否則核心更新後前端可能構建失敗。
更新啟動器後會發生什麼
- 啟動器二進制被替換，
.venv、config/、log/保留。 - 新版本可能要求不同的 Python 版本或工具鏈，此時會重新自舉
.venv（較慢，但配置不動）。 - 不會回退核心代碼。
版本兼容
| 組合 | 結果 |
|---|---|
| 新啟動器 + 舊核心 | 通常可用；若新啟動器依賴核心的新介面，會提示更新 |
| 舊啟動器 + 新核心 | 可能缺少新協議支援（如免密登入、進程回收標記） |
| 兩者都舊 | 功能可用，但可能缺少修復 |
判斷依據是倉庫的 CHANGELOG.md 與發佈説明，不要憑版本號大小猜。
修復環境
依賴損壞
症狀：啟動報 ModuleNotFoundError、ImportError，或 uv sync 失敗。
bash
# 在项目根目录
uv sync --frozen如果仍失敗：
bash
# 删除虚拟环境后让启动器重建（会重新下载依赖）
rm -rf .venv # Windows: rmdir /s /q .venv刪 .venv 不會刪配置
.venv 只裝運行環境，config/ 與日誌在別處。但重建需要聯網，耗時幾分鐘。
Git 倉庫損壞
症狀：更新失敗、fatal: not a git repository、衝突。
bash
git status
git stash # 有本地修改时先暂存
git pull --rebase不要用 git reset --hard 清理——會丟掉你改過的配置模板或本地補丁。
連接埠被佔用
預設連接埠 22267。啟動器會結束佔用該連接埠的進程。若你同時運行了源碼版實例（預設 25548），不會衝突；但兩個啟動器實例會。
快取
| 目錄 | 內容 | 能否刪除 |
|---|---|---|
cache/ | 運行時快取、圖片等 | 可以，會重新生成 |
frontend/node_modules | 前端依賴 | 可以，構建時重裝 |
frontend/dist | 前端產物 | 可以，gui.py 會重建 |
log/ | 日誌 | 可以，但疑難排解前別刪 |
日誌
| 日誌 | 位置 |
|---|---|
| 啟動器 | log/<日期>_launcher.txt |
| 核心程序 | log/<日期>_<实例>.txt |
| 錯誤現場 | log/error/<实例>/<时间戳>/ |
啟動器日誌記錄了每個階段的命令與退出碼；核心日誌記錄任務邊界與識別過程。提 Issue 時兩個都要。
遷移到新機器
01
舊機器停止實例
先停調度，避免複製時配置還在寫。
01
複製 config
config/ 整個目錄，含 deploy.yaml。帳號保險庫綁定設備，換機後需要重新錄入。
01
新機器安裝並首次啟動
讓啟動器完成環境自舉，然後關閉。
01
覆蓋配置
把舊 config/ 覆蓋進去，啟動檢查實例列表與任務開關。
01
重配設備相關項
模擬器 Serial、ADB 路徑、截圖方案按新機器調整。
移除
- 退出啟動器（托盤 → 退出），確認沒有
gui.py殘留。 - 備份
config/與AzurPilot_Data_Backup/。 - 刪除整個目錄。
- 如果設定過開機自啟，在系統設定裏移除對應項（啟動器移除時通常會自動清理）。
疑難排解速查
| 現象 | 檢查 |
|---|---|
| 啟動畫面卡在「下載 Python」 | 網絡 / 鏡像；換 -cn 版或改 deploy.yaml |
| 卡在「更新倉庫」 | 代理、分支名、GitHub 可達性；--skip-update 試啟動 |
| 卡在「同步依賴」 | PyPI 鏡像；uv.lock 與代碼是否同版本 |
| 打開窗口空白 | WebView2 / libwebkit2gtk |
| 提示連接埠被佔用 | 另一個啟動器實例或佔用進程 |
| 關閉窗口後任務繼續 | 正常：最小化到托盤 |
| 托盤退出後仍有 python | 進程回收異常，查啟動器日誌裏的進程掃描記錄 |
| 更新後 WebUI 打不開 | 前端構建失敗，查 frontend/dist 與 Node |
| macOS 提示已損壞 | xattr -dr com.apple.quarantine |
更細的進程問題見後端進程生命週期。