kaeawc/auto-mobile

Docker快速开始

本项目提供Docker支持，用于在容器化环境中运行AutoMobile，包含所有必要的Android开发工具。

适用于MCP客户端（Claude Desktop、Continue.dev等）

要将此Docker镜像与MCP客户端一起使用，请参阅MCP客户端配置指南获取完整的设置说明。

Claude Desktop快速示例：

json
{
  "mcpServers": {
    "auto-mobile": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--privileged", "--network", "host", "auto-mobile:latest"]
    }
  }
}

适用于开发与测试

bash
# 构建镜像
docker-compose build

# 以生产模式运行
docker-compose up auto-mobile

# 以开发模式运行（带自动重载）
docker-compose up auto-mobile-dev

预构建镜像

已发布的镜像可在Docker Hub获取：https://hub.docker.com/r/kaeawc/auto-mobile

bash
# 拉取最新版本
docker pull kaeawc/auto-mobile:latest

# 拉取特定版本
docker pull kaeawc/auto-mobile:0.0.7

# 拉取主版本.次版本（推荐用于稳定性）
docker pull kaeawc/auto-mobile:0.0

# 拉取特定提交
docker pull kaeawc/auto-mobile:main-abc1234

维护者注意：有关发布凭据和工作流配置，请参阅Docker Hub设置指南。

包含内容

Docker镜像包含：

• Bun 1.3.x
• Java 21
• Android SDK（API 36，构建工具35.0.0）
• 平台工具（ADB）
• 所有必要的开发工具（ripgrep、ktfmt、lychee、shellcheck、xmlstarlet）

要包含Android模拟器/系统镜像，请使用以下命令构建：

bash
docker build --platform=linux/amd64 --build-arg ANDROID_INSTALL_EMULATOR=true -t auto-mobile:latest .

常用命令

bash
# 交互shell
docker-compose exec auto-mobile bash

# 运行测试
docker-compose exec auto-mobile npm test

# 运行代码检查
docker-compose exec auto-mobile npm run lint

# 检查已连接设备
docker-compose exec auto-mobile adb devices

# 构建Android组件
docker-compose exec auto-mobile bash -c "cd android && ./gradlew build"

要求

• Docker Engine 20.10+
• Docker Compose v2.0+
• 如需ADB设备访问：特权模式和主机网络（已配置）
• 如需不含模拟器的精简镜像：主机Android SDK + AVDs挂载到容器中

文档

完整文档请参阅docs/docker.md

平台说明

• Linux：完全支持
• macOS：ADB设备访问受限（Docker Desktop限制）。在Apple Silicon上使用--platform=linux/amd64
• Windows：需要带USB透传的WSL2
• iOS：不支持（需要macOS和Apple硬件）

故障排除

使用精简镜像与主机模拟器

当镜像构建时未包含模拟器（ANDROID_INSTALL_EMULATOR=false），请为您的操作系统使用主机模拟器设置，以便容器可以访问已安装的AVD和运行中的模拟器。

Linux（主机SDK + 容器内模拟器）：

bash
docker run --platform=linux/amd64 -it --rm --name auto-mobile \
  --network host \
  -e ANDROID_HOME=/opt/android-sdk \
  -e ANDROID_SDK_ROOT=/opt/android-sdk \
  -e AUTOMOBILE_EMULATOR_HEADLESS=true \
  -v "$HOME/Android/Sdk:/opt/android-sdk" \
  -v "$HOME/.android:/home/automobile/.android" \
  -v "$HOME/.auto-mobile:/home/automobile/.auto-mobile" \
  auto-mobile:latest

macOS（主机模拟器，容器通过ADB自动连接）：

bash
docker run --platform=linux/amd64 -it --rm --name auto-mobile \
  -e ANDROID_HOME=/opt/android-sdk \
  -e ANDROID_SDK_ROOT=/opt/android-sdk \
  -e AUTOMOBILE_EMULATOR_EXTERNAL=true \
  -v "$HOME/.android:/home/automobile/.android" \
  -v "$HOME/.auto-mobile:/home/automobile/.auto-mobile" \
  auto-mobile:latest

启用AUTOMOBILE_EMULATOR_EXTERNAL=true后，容器会自动连接到运行在host.docker.internal:5555-5585的主机模拟器。自动连接服务每10秒扫描一次模拟器，并在模拟器重启时重新连接。无需手动执行adb connect。

不要将macOS SDK挂载到/opt/android-sdk（Linux容器中无法运行macOS二进制文件）。

自动连接环境变量：

高级：ADB服务器隧道模式

如需完整ADB命令支持（包括adb emu kill和其他控制台命令），可将容器连接到主机的ADB服务器，而非单个设备端口：

bash
# 在主机上，确保ADB服务器正在运行
adb start-server

# 使用ADB服务器隧道运行容器
docker run --platform=linux/amd64 -it --rm --name auto-mobile \
  -e ANDROID_HOME=/opt/android-sdk \
  -e ANDROID_SDK_ROOT=/opt/android-sdk \
  -e AUTOMOBILE_EMULATOR_EXTERNAL=true \
  -e AUTOMOBILE_ADB_SERVER_HOST=host.docker.internal \
  -e AUTOMOBILE_ADB_SERVER_PORT=5037 \
  -v "$HOME/.android:/home/automobile/.android" \
  -v "$HOME/.auto-mobile:/home/automobile/.auto-mobile" \
  auto-mobile:latest

ADB服务器隧道优势：

• 自动显示所有设备（模拟器和物理设备）
• 完整ADB命令支持，包括控制台命令（emu kill等）
• 单个连接点，无需按设备端口扫描

高级：主机控制守护进程

要从容器内部启动/停止模拟器和运行SDK命令，请在macOS主机上运行主机控制守护进程：

bash
# 启动主机控制守护进程（运行在端口15037）
node scripts/docker/host-control-daemon.js

# 或使用自定义设置
node scripts/docker/host-control-daemon.js --port 15037 --host 0.0.0.0

守护进程提供JSON-RPC接口，支持：

• list-avds - 列出可用AVD
• start-emulator - 按AVD名称启动模拟器
• stop-emulator - 停止模拟器
• list-running - 列出运行中的模拟器
• avdmanager - 运行avdmanager命令
• sdkmanager - 运行sdkmanager命令

使用主机控制运行容器：

bash
docker run --platform=linux/amd64 -it --rm --name auto-mobile \
  -e AUTOMOBILE_EMULATOR_EXTERNAL=true \
  -e AUTOMOBILE_HOST_CONTROL_HOST=host.docker.internal \
  -e AUTOMOBILE_HOST_CONTROL_PORT=15037 \
  -v "$HOME/.android:/home/automobile/.android" \
  -v "$HOME/.auto-mobile:/home/automobile/.auto-mobile" \
  auto-mobile:latest

ADB无法检测到设备？

1. 确保设备已连接到主机：adb要求
2. 重启ADB服务器：adb kill-server && adb start-server
3. 检查是否以--privileged标志运行容器

构建失败？

bash
# 清理并重建
docker-compose down -v
docker-compose build --no-cache
docker-compose up

测试

验证Dockerfile

bash
# 检查Dockerfile
./scripts/docker/validate_dockerfile.sh

# 运行容器结构测试
./scripts/docker/test_container.sh

# 测试主机模拟器访问（自动启动主机模拟器）
./scripts/docker/test_host_emulator_mcp.sh

测试MCP协议

bash
# 构建镜像
docker build --platform=linux/amd64 -it --rm --init auto-mobile:latest

# 测试交互
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | docker run --platform=linux/amd64 -i --rm --init auto-mobile:latest

更多帮助，请参阅完整的Docker文档和MCP配置指南。