部署方案
Agent 部署

Agent 部署

部署 PandaTest Agent，将物理设备连接到平台。

什么是 Agent？

Agent 是运行在设备旁边的代理服务，负责：

  • 管理连接到服务器的 Android / iOS 物理设备
  • 提供实时投屏、远程控制
  • 执行自动化测试任务

前提条件

  • Docker 已安装并运行
  • 至少一台 Android 或 iOS 设备通过 USB 连接到本机
  • 本机可以访问已部署好的平台控制台
  • 实施人员已提供 Agent 镜像（或含 Agent 的发行包）

快速部署

获取 Agent Key

登录平台控制台，进入 Agent 管理，点击 新建 Agent，复制 Agent Key。

准备目录与镜像

mkdir panda-agent && cd panda-agent

按交付说明导入 Agent 镜像，例如：

docker load -i panda-agent.tar

创建 .env

AGENT_KEY=sk_你的密钥
AGENT_HOST=192.168.1.100
MASTER_URL=http://192.168.1.10
 
AGENT_NAME=my-agent
PORT=3011
LOG_LEVEL=INFO
  • MASTER_URL：平台控制台地址（与平台 FRONTEND_URL 一致）
  • AGENT_HOST：本机局域网 IP

启动 Agent

使用交付包中的 docker-compose.yml 启动：

docker compose up -d

若交付包提供的是 docker run 命令，按交付说明执行即可。

验证

# 检查容器状态
docker ps | grep pandatest-agent
 
# 检查健康状态
curl http://localhost:3011/health
 
# 查看日志
docker logs -f pandatest-agent

启动成功后，回到平台控制台，Agent 状态应变为 在线。接下来根据设备类型完成接入：

常用操作

docker compose logs -f panda-agent
docker compose restart panda-agent
docker compose down

升级时使用实施人员提供的新版本镜像包导入后重启。

环境变量参考

必需配置

变量说明示例
AGENT_KEYAgent 认证密钥sk_xxxx
AGENT_HOST机器局域网 IP192.168.1.100
MASTER_URL平台控制台地址http://192.168.1.10

常用可选配置

变量说明默认值
AGENT_NAME显示名称docker-agent
PORT服务端口3011
LOG_LEVEL日志级别INFO

设备桥接（高级）

宿主机为 Docker Desktop 时，以下默认值通常无需调整。在自建 ADB / usbmuxd / HDC 代理时可覆盖：

变量说明默认值
ANDROID_ADB_SERVER_HOSTAndroid ADB Server 地址host.docker.internal
ANDROID_ADB_SERVER_PORTAndroid ADB Server 端口5037
USBMUXD_SOCKET_ADDRESSiOS usbmuxd 地址host.docker.internal:27015
HDC_SERVER_ADDRESS鸿蒙 HDC 服务地址host.docker.internal:8710

AI 功能（可选）

变量说明默认值
ZHIPUAI_API_KEY智谱 AI Key（AI 功能）-
OPENROUTER_API_KEYOpenRouter Key（AI 功能）-

常见问题

Agent 显示离线

  1. 检查 AGENT_KEY 是否正确
  2. 检查容器能否访问 MASTER_URL： 
    docker exec pandatest-agent curl -s "$MASTER_URL"/health/
  3. 查看日志：docker compose logs -f panda-agent

投屏连接失败

  1. 确认 AGENT_HOST 为本机局域网 IP，防火墙已放行 PORT（默认 3011）
  2. 确认平台能访问该 IP 和端口
  3. 设备相关问题请参考 Android 设备接入 或 iOS 设备接入
前后端部署升级流程