Agent 部署

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

什么是 Agent？

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

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

前提条件

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

快速部署

获取 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 查看。

启动 Agent

在部署目录下创建 docker-compose.yml：

services:
  panda-agent:
    image: pandatestgrid/panda-agent:latest
    container_name: pandatest-agent
    restart: unless-stopped
    ports:
      - "${PORT:-3011}:3011"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./logs:/app/logs
      - ./media:/app/media
      - ./certs:/app/certs
    env_file:
      - .env
    environment:
      - ANDROID_ADB_SERVER_HOST=host.docker.internal
      - ANDROID_ADB_SERVER_PORT=5037
      - ADB_HOST=host.docker.internal
      - USBMUXD_SOCKET_ADDRESS=${USBMUXD_SOCKET_ADDRESS:-host.docker.internal:27015}
      - GO_IOS_AGENT_HOST=host.docker.internal
      - GO_IOS_AGENT_PORT=60105
    extra_hosts:
      - "host.docker.internal:host-gateway"
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "curl -sf http://localhost:3011/health || curl -skf https://localhost:3011/health"
        ]
      interval: 30s
      timeout: 10s
      start_period: 40s
      retries: 3

启动：

docker compose up -d

验证

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

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

常用操作

# 查看实时日志
docker compose logs -f panda-agent
 
# 重启
docker compose restart panda-agent
 
# 升级到最新版本
docker compose pull && docker compose up -d
 
# 停止
docker compose down

环境变量参考

必需配置

变量	说明	示例
`AGENT_KEY`	Agent 认证密钥	`sk_xxxx`
`AGENT_HOST`	机器局域网 IP	`192.168.1.100`

常用可选配置

变量	说明	默认值
`MASTER_URL`	PandaTest 后端地址	`https://www.pandatest.net`
`AGENT_NAME`	Agent 显示名称	`docker-agent`
`PORT`	Agent 服务端口	`3011`
`LOG_LEVEL`	日志级别（`DEBUG` / `INFO` / `WARNING` / `ERROR`）	`INFO`

设备桥接（高级）

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

变量	说明	默认值
`ANDROID_ADB_SERVER_HOST`	Android ADB Server 地址	`host.docker.internal`
`ANDROID_ADB_SERVER_PORT`	Android ADB Server 端口	`5037`
`USBMUXD_SOCKET_ADDRESS`	iOS usbmuxd 服务地址	`host.docker.internal:27015`
`GO_IOS_AGENT_HOST`	go-ios 代理地址	`host.docker.internal`
`GO_IOS_AGENT_PORT`	go-ios 代理端口	`60105`
`HDC_SERVER_ADDRESS`	鸿蒙 HDC 服务地址	`host.docker.internal:8710`

HTTPS / 证书

变量	说明	默认值
`SSL_ENABLED`	是否对外启用 HTTPS	`true`
`SSL_AUTO_CERT`	无证书时由 entrypoint 自签生成到 `certs/`	`true`
`SSL_CERT_PATH`	证书路径（容器内）	`certs/cert.pem`
`SSL_KEY_PATH`	私钥路径（容器内）	`certs/key.pem`

AI 功能（可选）

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

常见问题

Agent 显示离线

检查 AGENT_KEY 是否正确

检查容器是否能访问 MASTER_URL：

docker exec pandatest-agent curl -s https://www.pandatest.net/health/

查看日志：docker logs -f pandatest-agent（compose 部署用 docker compose logs -f panda-agent）

投屏连接失败

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

前后端部署升级流程