安装
装之前请先确认环境与兼容性。下面四条路径按「推荐程度」排序，普通用户优先看启动器。
桌面启动器（推荐）
下载
从 官网下载页 或 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。首次启动需要联网，耗时取决于网络，通常几分钟。
窗口打开时已经完成登录，直接进入 AzurPilot WebUI。默认端口 22267（启动器会指定端口，核心程序自身的默认端口是 25548）。
macOS 首次打开失败
程序未经 Apple 开发者签名。若提示「无法验证开发者」，在终端执行：
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 与调度器，模拟器仍在宿主机：
git clone https://github.com/wess09/AzurPilot.git
cd AzurPilot
docker compose up -d --builddocker-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缺失时自动安装依赖并构建）
步骤
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。
常用启动参数：
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 <实例名> | 启动时直接运行指定实例 |
验证安装
# 导入冒烟检查：不连接模拟器，只验证模块可加载
uv run python -m dev_tools.import_smoke_test
# Python 单元测试
uv run python -m unittest discover -s testsWebUI 能打开、任务列表能渲染、日志无 traceback，就说明后端装好了。设备连接是下一步。