部署方案
Agent 部署

Agent 部署

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

什么是 Agent？

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

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

前提条件

  • Docker Desktop 已安装并运行（下载 (opens in a new tab)）
  • 至少一台 Android 或 iOS 设备通过 USB 连接到机器
  • 机器可以访问 PandaTest 平台（SaaS 或私有部署）

生产环境建议通过版本化 manifest 和脚本管理 Agent，不直接使用浮动 latest 标签。

快速部署

获取 Agent Key

登录 PandaTest 控制台，进入 Agent 管理 页面，点击 新建 Agent，复制生成的 Agent Key。

创建部署目录

mkdir panda-agent && cd panda-agent

创建 .env 配置文件

# 必填：从 PandaTest 控制台获取的 Agent Key
AGENT_KEY=sk_你的密钥
 
# 必填：当前机器的局域网 IP（用于设备投屏连接）
AGENT_HOST=192.168.1.100
 
# 后端地址（SaaS 用户无需修改）
MASTER_URL=https://www.pandatest.net
 
# 可选配置
AGENT_NAME=my-agent
PORT=3011
LOG_LEVEL=INFO
⚠️

AGENT_HOST 必须填写机器的真实局域网 IP，不能用 localhost 或 127.0.0.1。 可以通过 ifconfig 或 ip addr 查看。

使用脚本安装固定版本

bash deploy/scripts/agent-install.sh --version 1.1.2

或直接拉取固定版本镜像

docker pull pandatest/panda-agent:0.14.1
 
docker run -d \
  --name pandatest-agent \
  --restart unless-stopped \
  -p 3011:3011 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./logs:/app/logs \
  -v ./media:/app/media \
  --env-file .env \
  -e ANDROID_ADB_SERVER_HOST=host.docker.internal \
  -e ANDROID_ADB_SERVER_PORT=5037 \
  -e ADB_HOST=host.docker.internal \
  --add-host host.docker.internal:host-gateway \
  pandatest/panda-agent:0.14.1

验证

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

启动成功后，回到 PandaTest 控制台，Agent 状态应变为 在线。

安装运行镜像

Agent 执行自动化测试时，依赖基础运行镜像来创建测试容器。推荐与服务端发布版本一起固定：

Python 测试运行镜像

docker pull pandatest/test-runner-python:1.1.2

Agent 启动时会自动检测运行镜像，如果不存在会尝试自动构建。也可以手动提前拉取以加快首次执行速度。

镜像说明预装工具
pandatest/test-runner-python:1.1.2Python 测试运行器pytest、Appium、uiautomator2、airtest、mitmproxy 等

接下来，根据你的设备类型完成接入：

常用操作

# 查看实时日志
docker logs -f pandatest-agent
 
# 重启
docker restart pandatest-agent
 
# 版本化升级
bash deploy/scripts/agent-upgrade.sh --version 1.1.2
 
# 回滚
bash deploy/scripts/agent-rollback.sh --version 1.1.1
 
# 停止
docker rm -f pandatest-agent

环境变量参考

必需配置

变量说明示例
AGENT_KEYAgent 认证密钥sk_xxxx
AGENT_HOST机器局域网 IP192.168.1.100

可选配置

变量说明默认值
MASTER_URLPandaTest 后端地址https://www.pandatest.net
AGENT_NAMEAgent 显示名称docker-agent
PORTAgent 服务端口3011
LOG_LEVEL日志级别INFO
ZHIPUAI_API_KEY智谱 AI Key（AI 功能）-
OPENROUTER_API_KEYOpenRouter Key（AI 功能）-

常见问题

Agent 显示离线

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

投屏连接失败

  1. 确认 AGENT_HOST 填写的是正确的局域网 IP
  2. 确认浏览器和 Agent 在同一局域网，或均可访问公网
  3. 检查防火墙是否放行了 PORT 端口（默认 3011）
  4. 设备相关问题请参考 Android 设备接入 或 iOS 设备接入
前后端部署升级流程