AI测试平台

环境要求

最低硬件：

• CPU：2 核
• 内存：4 GB（Chromium + Node MCP 子进程吃 1-1.5 GB）
• 磁盘：10 GB（基础镜像 ~4 GB；视频 / trace 按 UI_MEDIA_RETENTION_DAYS 滚动）

3. 安装依赖（首次执行）

./run.sh install

首次或依赖/Dockerfile/nginx/entrypoint 变更后：完整重建

./run.sh up

添加依赖

./run.sh add-backend openai              # 后端：自动改 pyproject + uv.lock
./run.sh add-frontend dayjs              # 前端：自动改 package.json + pnpm-lock

🚀 快速开始

2. 一键初始化（自动 .env / build / up / 健康检查；首次约 10 分钟含 Chromium）

bash scripts/init.sh

（DeepSeek / 通义 / Ollama / GPT 等任选）即可开始使用 AI 功能

```

路径 B：服务器生产部署（3-5 分钟，⭐ 推荐）

不用 git clone 整个仓库，不用本地 build，直接拉 GitHub Actions 预构建好的镜像：

```bash

1. 服务器上准备目录 + 下载部署文件（不是整个仓库！）

mkdir -p ~/aitestplatform && cd ~/aitestplatform curl -fsSL -o docker-compose.prod.yml \ https://raw.githubusercontent.com/<your-username>/AITestPlatform/main/docker-compose.prod.yml curl -fsSL -o .env.example \ https://raw.githubusercontent.com/<your-username>/AITestPlatform/main/.env.example cp .env.example .env

想看其它部署方式？

→ 📦 部署方式（共 5 种方案：本地开发 / Docker 本地 / 服务器自 build / VPN 内网 / GHCR 拉取）

---

📦 部署方式

提供五种部署模式，覆盖从本地开发到生产环境的所有场景：

💡 第一次在服务器上部署？ 强烈推荐方案 E：跳过本地 build（节省 10 分钟），直接拉 GitHub Actions 预构建好的镜像，几行命令搞定。

1. 安装工具链

brew install uv node pnpm # macOS

Linux: curl -LsSf https://astral.sh/uv/install.sh | sh && nvm install 20 && npm i -g pnpm

等价：cd backend && uv sync && cd ../frontend && pnpm install

- docker compose -f docker-compose.dev.yml up -d db # 仅起 PostgreSQL

方案 B：Docker 本地一键部署（推荐）

最常用方式。三个容器（db / backend / frontend），一行命令启动。

B-1：自动化（推荐首次部署）

```bash git clone <repo-url> && cd AITestPlatform

bash scripts/init.sh

1. 检查 docker / docker compose 可用

3. docker compose build （首次约 5–10 分钟，含 Chromium）

4. docker compose up -d

VPN / 公司内网被测系统场景：保留 docker-compose.vpn.yml override

./run.sh up-vpn

docker compose -f docker-compose.yml -f docker-compose.vpn.yml up -d --build

方案 C：Linux 服务器部署

与方案 B 几乎相同，但有几个生产化要点。

生产化清单

```bash

1. 安装 Docker（Ubuntu / Debian）

curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER && newgrp docker

docker-compose.yml

services: db: ports: [] # ← 注释或删除原 5432 行；不写 ports 即不对外

backend 容器仍可经容器网络访问 `db:5432`，无影响。

#### 系统服务化（开机自启）

`docker compose up -d` 加 `restart: unless-stopped` 已能自动重启。如要更严格的开机启动，写一份 systemd unit：

docker-compose.override.yml（与 docker-compose.yml 自动叠加）

services: backend: deploy: resources: limits: cpus: "2.0" memory: 3G ```

docker-compose.sidecar-vpn.yml —— 与 docker-compose.yml 叠加使用

services: vpn: image: lscr.io/linuxserver/wireguard:latest cap_add: - NET_ADMIN - SYS_MODULE sysctls: - net.ipv4.conf.all.src_valid_mark=1 volumes: - ./vpn:/config # 把 .conf 放在 ./vpn/wg_confs/ - /lib/modules:/lib/modules:ro environment: - PUID=1000 - PGID=1000 restart: unless-stopped healthcheck: test: ["CMD", "wg", "show"] interval: 30s

backend: network_mode: "service:vpn" # ← 关键：完全共享 vpn 容器的网络命名空间 depends_on: vpn: condition: service_started db: condition: service_healthy # 注意：当使用 network_mode: service:xxx 时，本服务自身不能再声明 ports。 # backend 的 8000 端口要由 vpn 容器代为暴露： ports: !reset [] vpn: ports: - "${BACKEND_PORT:-8000}:8000" # backend 的 API 端口（宿主机端口随 .env 走） # 6080 不暴露（前端经容器网络反代）

> 注意：`network_mode: service:vpn` 让 backend 完全没有自己的网络栈，**它的 `ports`、`networks`、`extra_hosts` 都不能再写，要写在 vpn 容器上**。

OpenVPN 版本（用 `kylemanna/openvpn` 或 `dperson/openvpn-client`）：

backend: network_mode: "service:vpn" ports: !reset [] depends_on: [vpn, db]

**步骤三：启动**

**步骤四：验证 VPN 隧道与连通性**

方案 E：GHCR 拉取预构建镜像（最快，3-5 分钟部署）⭐ 生产首次部署推荐

适用场景：服务器已装 Docker、希望跳过 5-10 分钟本地 build 的所有部署；首次部署、生产环境、CI/CD 自动化都强烈推荐这种方式。

GitHub Actions 已在仓库 push / tag 时自动构建并推送镜像到 GHCR（GitHub Container Registry），服务器只需 pull 即用，无需 git clone 整个仓库。

镜像地址（假设你的 GitHub 用户名是 your-username）：

ghcr.io/your-username/aitestplatform-backend:latest
ghcr.io/your-username/aitestplatform-frontend:latest

E-1：服务器首次部署（10 步照抄即可）

步骤 1：装 Docker（一次性）

```bash

下载部署所需的 2 个文件（不是整个仓库！）

curl -fsSL -o docker-compose.prod.yml \ https://raw.githubusercontent.com/<your-username>/AITestPlatform/main/docker-compose.prod.yml

curl -fsSL -o .env.example \ https://raw.githubusercontent.com/<your-username>/AITestPlatform/main/.env.example

cp .env.example .env

##### 步骤 3：编辑 `.env`（必填，少一个启动不了）

打开编辑器：

**关键变量**（生产环境每一项都要改！）：

CentOS/RHEL：sudo dnf install caddy

内网代理（VPN 场景；详见 §部署方式 D-1）

UI_HTTP_LOGIN_PROXY= # 仅 http_login 走它；空 = 关闭 UI_BROWSER_PROXY= # chromium 启动时透传给 --proxy-server UI_BROWSER_PROXY_BYPASS=localhost,127.0.0.1,host.docker.internal,db,backend,frontend SKILL_HTTP_PROXY= # 三期 Skill 包 http_get_json/http_post_json 走它；空 = 回退到 UI_HTTP_LOGIN_PROXY → HTTP_PROXY

部署 / 启动

Docker 部署的服务器上：

docker compose exec backend alembic upgrade head ```

3. 拉镜像 + 启动

docker compose -f docker-compose.prod.yml --env-file .env pull docker compose -f docker-compose.prod.yml --env-file .env up -d

4. 一键启动开发环境

./run.sh dev

2. 从 .env.example 复制 .env，并生成随机 SECRET_KEY

4. 启动

docker compose up -d

启动或热更新后做验收前检查

./run.sh docker-smoke ./run.sh docker-smoke-vpn # VPN 场景使用 ```

run.sh 的本地探活会显式绕过宿主机代理；如果你手动 curl localhost 验证，也建议加 --noproxy "*"，避免本机 HTTP_PROXY/ALL_PROXY 把请求送到代理端口。

docker-smoke 会检查：

- GET /api/health 是否可访问； - 前端 nginx 页面是否可访问； - 容器内 alembic current 是否能读取当前迁移； - 三期 failure_diagnosis 的 4 个 system__failure_diagnosis__* 工具是否注册到 backend 运行时。

三期功能验收入口：

- 物料语义化：测试物料集编辑页，检查字段 purpose / semantic / source_type 与 CSV 导入的 semantic 列。 - 风险环境：UI 环境列表/编辑页，检查 risk_level 与严格确认文案。 - 即席用例：聊天里说“帮我测试 xxx 流程”，无匹配用例时应出现可编辑的即席步骤确认卡。 - runtime_data：多用例编排中先保存 runtime_data，后续步骤使用 {{runtime.xxx}}。 - 失败诊断：失败执行事件卡点击“失败诊断”，或直接说“请诊断任务 <task_id> 为什么失败”，应输出 FixActionCard。

4. 启动

docker compose up -d --build

启动（DB 迁移 + 创建 admin 自动完成）

docker compose -f docker-compose.prod.yml --env-file .env up -d

🌐 API 管理使用指南

API 管理是三期新增的接口测试能力，入口在左侧一级菜单 API 管理，包含 环境配置、API 列表、API 自动化 三个页面。

🎬 UI 自动化使用指南

若 .env 改了 FRONTEND_PORT=8080：http://localhost:8080

进入「系统设置 → LLM 配置」，新增一个 OpenAI 协议兼容的 Provider

2. 编辑 .env：填 GHCR_OWNER / SECRET_KEY / ENCRYPT_KEY / ADMIN_PASSWORD / POSTGRES_PASSWORD

nano .env

2. 克隆 + 准备 env

git clone <repo-url> && cd AITestPlatform cp .env.example .env

1. 准备 .env

cp .env.example .env

2. （可选）生成 ENCRYPT_KEY；不设置则用 config.py 的开发默认值

python -c "from cryptography.fernet import Fernet; print('ENCRYPT_KEY=' + Fernet.generate_key().decode())" >> .env

6. 健康检查（宿主机端口默认 8000；若 .env 里改了 BACKEND_PORT 就用新端口）

curl --noproxy "*" http://localhost:${BACKEND_PORT:-8000}/api/health

3. 准备生产 .env（强密码、关 DEBUG）

cp .env.example .env vi .env

方案 1：pproxy（一行 pip，零配置，推荐）

pip install pproxy pproxy -l http://0.0.0.0:8118 &

方案 3：tinyproxy（brew 装，配置简单）

brew install tinyproxy cat >/tmp/tinyproxy.conf <<EOF Listen 0.0.0.0 Port 8118 Allow 127.0.0.1 Allow 192.168.65.0/24 EOF tinyproxy -c /tmp/tinyproxy.conf

**步骤二：宿主机自验证（一定要做）**

WireGuard 看到 "interface created"；OpenVPN 看到 "Initialization Sequence Completed"

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)

2. 配置反代

sudo tee /etc/caddy/Caddyfile > /dev/null <<EOF your-domain.com { reverse_proxy localhost:${FRONTEND_PORT:-80} } EOF

sudo systemctl restart caddy

→ 浏览器访问 `https://your-domain.com`（Caddy 自动申请证书 + 续签）。

**前提**：
- 域名 A 记录已指向服务器公网 IP
- 防火墙放行 80 + 443 端口（80 用于 ACME challenge）

#### E-2：服务器日常升级（已有部署 → 拉新镜像）

每次本地 `git push origin main` 后，GitHub Actions 自动构建新镜像并打 `:latest` tag。服务器升级只需 3 行命令：

改 .env 锁定版本

sed -i 's/^IMAGE_TAG=.*/IMAGE_TAG=v1.2.0/' .env

⚙️ 配置详解

.env（基于 .env.example）所有变量按域分组：

配置环境和变量

1. 进入 API 管理 → 环境配置，按项目创建环境，例如测试环境、预发环境、生产只读环境。
2. 每个环境维护一个基础 URL，例如 https://api.example.com。
3. 在环境变量中维护 token、tenant_id、mid、appid 等值。API 的 Query、Header、Path、Body 都可以用 {{变量名}} 引用，实际执行时会替换为当前环境变量值。

配置环境

1. UI 自动化 → 环境列表 → 创建 2. 关键字段： - Base URL：被测系统首页 - Browser：chromium / firefox / webkit - Headless：是否无头；服务器场景设 false 配合 noVNC 看画面 - 前置步骤： - http_login：直接调登录接口拿 token，最快 - ai_login：让 AI 在登录页操作（复杂场景） - state_inject：注入预录制的 storage_state - 默认物料集：每次执行自动加载

三期增强：Skill 体系 + API 管理

---

5. 健康检查 /api/health 直到就绪

完成后：

| 服务 | 地址 |
|---|---|
| 前端 | http://localhost（端口默认 80，由 `.env` 的 `FRONTEND_PORT` 控制；80 是 HTTP 默认端口，URL 不需要写） |
| 后端 Swagger | http://localhost:8000/docs（端口默认 8000，由 `.env` 的 `BACKEND_PORT` 控制） |

默认管理员：`admin / admin123`，**首次登录后立即修改！**

> **服务器上 80 / 8000 被其它项目占用？** 在 `.env` 里加：
> 

> 然后 `docker compose up -d` 重建即可。容器内 nginx / uvicorn 仍是 80 / 8000，
> 前端反代不受宿主端口影响（详见上文 [端口](#端口) 章节）。

#### B-2：手动逐步（看清楚每一步）

生成 ENCRYPT_KEY（物料 secret / API key 加密；丢了等于丢失所有 secret 数据）

python3 -c "from cryptography.fernet import Fernet; print('ENCRYPT_KEY=' + Fernet.generate_key().decode())" >> .env

服务器没有 python3 时，用 openssl 替代：

##### 步骤 4：（仅 private 包需要）登录 GHCR

GitHub 上每个 GHCR 包默认是 **private**，需要先在 GitHub 上把包改成 public（推荐）或 docker login。

**推荐：把包改 public**（一次性操作）：

> GitHub → 你的头像 → Packages → 选中 `aitestplatform-backend` / `aitestplatform-frontend` → 右侧 `Package settings` → 滚到底 `Change visibility` → `Public`

如果坚持 private，则需要在服务器上登录：

后端 API（按模块）

完整 API 文档：开发模式 DEBUG=true 下访问 http://localhost:${BACKEND_PORT:-8000}/docs（生产模式自动关闭）。

维护 API 列表

1. 进入 API 管理 → API 列表，左侧维护独立的 API 模块树。
2. 新建或编辑 API 时，选择请求方法、环境 URL 或自定义 URL，并填写 Path。
3. 参数、请求头、请求体 使用 Tab 管理。Query / Header 使用 key-value 行；JSON 请求体可直接填写原始 JSON。
4. 断言支持状态码、JSONPath、响应头和正文包含校验。失败时报告会展示期望值和实际值，方便定位数据差异。

API 自动化任务

1. 进入 API 管理 → API 自动化，创建任务并按顺序添加多个 API 步骤。
2. 每个步骤可以从响应 JSON、响应头、正文或状态码中提取字段，保存为 runtime 变量。
3. 后续步骤可在 Query、Header、Body、Path、Base URL 中引用 {{runtime.xxx}}，例如先登录提取 token，再把 Authorization: Bearer {{runtime.token}} 注入后续接口。
4. 任务支持手动执行和定时执行。执行历史保留每一步的实际请求、响应、提取变量、断言结果和错误信息。

---

后续规划：API 管理增强、App 自动化、ARQ + Redis 异步任务队列等。

---

权限勾选：read:packages

📋 模块清单

改完模型之后

./run.sh db-migrate "add foo column" # 自动生成