安裝

裝之前請先確認環境與兼容性。下面四條路徑按「推薦程度」排序，普通用戶優先看啟動器。

桌面啟動器（推薦）

下載

從官網下載頁或 GitHub Releases 獲取對應系統與 CPU 架構的壓縮包。國內網絡選擇帶 -cn 的鏡像版。

解壓縮與運行

解壓縮到固定目錄

啟動器會在自身目錄下建立 .venv、拉取核心倉庫並儲存配置。不要放在臨時目錄或只讀位置，也不要放在中文路徑兼容性差的同步盤裏。

運行啟動器

Windows：雙擊 alas-launcher.exe，需要管理員權限（安裝 ADB 與寫入系統目錄）。會彈 UAC。
macOS：打開 AzurPilot.app。未簽名程序可能被 Gatekeeper 攔截，見下方説明。
Linux：chmod +x alas-launcher && ./alas-launcher。

等待環境初始化

啟動畫面會顯示：建立 .venv → 下載 Python 3.14.6 → 更新倉庫 → uv sync --frozen。首次啟動需要聯網，耗時取決於網絡，通常幾分鐘。

進入 WebUI

窗口打開時已經完成登入，直接進入 AzurPilot WebUI。預設連接埠 22267（啟動器會指定連接埠，核心程序自身的預設連接埠是 25548）。

macOS 首次打開失敗

程序未經 Apple 開發者簽名。若提示「無法驗證開發者」，在終端執行：

bash

xattr -dr com.apple.quarantine /Applications/AzurPilot.app

然後重新打開。不要從「系統設定 → 隱私與安全性」反覆點擊「仍要打開」。

Windows 缺少 WebView2

Tauri 依賴 WebView2。Windows 11 已內置；Windows 10 若提示缺失，安裝 Microsoft Edge WebView2 Runtime 後重試。

Android

完整步驟見 Android 安裝與架構選擇。簡要流程：

確認設備為 Android 9.0+、ARM64 或 x86_64。
下載與架構匹配的完整版 APK（內置 Runtime）或輕量增量 APK（首次啟動下載約 1 GB Runtime）。
安裝並啟動，等待 rootfs 解壓縮（1–3 分鐘）。
按提示啟用 ADB（內置無線配對）或使用 Root。
在應用內打開 AzurPilot 控制台配置實例。

Docker

適合 NAS、伺服器與無桌面環境。容器只跑 WebUI 與調度器，模擬器仍在宿主機：

bash

git clone https://github.com/wess09/AzurPilot.git
cd AzurPilot
docker compose up -d --build

docker-compose.yml 使用 network_mode: host，容器內以 .venv/bin/python gui.py 啟動。國內構建可把 Dockerfile 換成 deploy/docker/Dockerfile.cn，並通過 UV_INDEX_URL 指定鏡像。

首次啟動較慢

鏡像分兩階段構建：Node 24 構建前端，Python 3.14 安裝運行時依賴。首次 --build 會下載較多內容，後續重建會複用快取。

源碼運行

適用於開發、調試與自定義修改。

依賴

Python 3.14（版本要求以 pyproject.toml 為準）
uv
Node.js（前端構建；gui.py 會在 frontend/dist 缺失時自動安裝依賴並構建）

步驟

bash

git clone https://github.com/wess09/AzurPilot.git
cd AzurPilot
uv sync --frozen --no-dev
uv run python gui.py

瀏覽器訪問 http://127.0.0.1:25548。預設監聽 0.0.0.0，連接埠與監聽地址來自 config/deploy.yaml 的 WebuiHost / WebuiPort。

常用啟動參數：

bash

uv run python gui.py --port 25548 --host 127.0.0.1 --key "your-password"

參數	作用
`--host`	覆蓋 `WebuiHost`
`-p, --port`	覆蓋 `WebuiPort`
`-k, --key`	設定訪問密碼
`--ssl-key` / `--ssl-cert`	啟用 HTTPS
`--run <实例名>`	啟動時直接運行指定實例

驗證安裝

bash

# 导入冒烟检查：不连接模拟器，只验证模块可加载
uv run python -m dev_tools.import_smoke_test

# Python 单元测试
uv run python -m unittest discover -s tests

WebUI 能打開、任務列表能渲染、日誌無 traceback，就説明後端裝好了。設備連接是下一步。

安裝

桌面啟動器（推薦） ​

下載 ​

解壓縮與運行 ​

Android ​

Docker ​

源碼運行 ​

依賴 ​

步驟 ​

驗證安裝 ​

安裝完成之後 ​

桌面啟動器（推薦）

下載

解壓縮與運行

Android

Docker

源碼運行

依賴

步驟

驗證安裝

安裝完成之後