523 lines
11 KiB
Markdown
523 lines
11 KiB
Markdown
# AutoFlow 部署指南
|
||
|
||
本文档是从零开始在全新工作站上部署 AutoFlow 统一自动化测试平台的完整指南,AI 可逐步骤执行。
|
||
|
||
---
|
||
|
||
## 1. 系统要求
|
||
|
||
| 组件 | 版本要求 | 检查命令 |
|
||
|------|---------|---------|
|
||
| 操作系统 | macOS / Linux (Ubuntu 20.04+) | `uname -a` |
|
||
| Python | 3.10 – 3.12 | `python3 --version` |
|
||
| Node.js | >= 18 | `node --version` |
|
||
| pnpm | 最新版 | `pnpm --version` |
|
||
| Git | 任意新版 | `git --version` |
|
||
| Docker (可选) | 20.10+ | `docker --version` |
|
||
|
||
---
|
||
|
||
## 2. 克隆仓库
|
||
|
||
```bash
|
||
git clone https://gitea.d-robotics.cc/jiawei.chen/TBC.git
|
||
cd TBC
|
||
```
|
||
|
||
如果使用 SSH:
|
||
```bash
|
||
git clone git@gitea.d-robotics.cc:jiawei.chen/TBC.git
|
||
cd TBC
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 环境配置
|
||
|
||
### 3.1 创建 .env 文件
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
### 3.2 编辑 .env 填入实际值
|
||
|
||
```bash
|
||
# 必填
|
||
BASE_URL=https://cloud-fat.d-robotics.cc # D-Cloud 测试环境地址
|
||
SSO_URL=https://sso-fat.d-robotics.cc # SSO 认证地址
|
||
TEST_USERNAME=<your-username> # 测试账号
|
||
TEST_PASSWORD=<your-password> # 测试密码
|
||
|
||
# Robogo 配置
|
||
ROBOGO_ENV=FAT # FAT 或 PROD
|
||
ROBOGO_SCOPE=all # 巡检范围
|
||
|
||
# 浏览器配置
|
||
BROWSER=chromium
|
||
HEADLESS=true # 无头模式
|
||
SLOW_MO=0 # 操作间隔(ms),调试时设 500
|
||
|
||
# 平台端口
|
||
PLATFORM_PORT=5001
|
||
|
||
# 飞书告警(可选)
|
||
LARK_WEBHOOK_URL=<your-webhook-url>
|
||
```
|
||
|
||
### 3.3 环境变量说明
|
||
|
||
| 变量 | 必填 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `BASE_URL` | 是 | — | D-Cloud 平台地址 |
|
||
| `SSO_URL` | 是 | — | SSO 单点登录地址 |
|
||
| `TEST_USERNAME` | 是 | — | 测试登录账号 |
|
||
| `TEST_PASSWORD` | 是 | — | 测试登录密码 |
|
||
| `TEST_ENV` | 否 | `dev` | 配置环境:`dev`/`test`/`prod` |
|
||
| `HEADLESS` | 否 | `true` | 浏览器是否无头运行 |
|
||
| `SLOW_MO` | 否 | `0` | Playwright 操作间隔(ms) |
|
||
| `PLATFORM_PORT` | 否 | `5001` | 后端监听端口 |
|
||
| `LARK_WEBHOOK_URL` | 否 | — | 飞书告警 Webhook |
|
||
| `DCLOUD_BASE_URL` | 否 | `https://cloud-fat.d-robotics.cc` | 数据生成页面 URL |
|
||
| `ROBOGO_ENV` | 否 | `PROD` | Robogo 环境:`FAT`/`PROD` |
|
||
|
||
---
|
||
|
||
## 4. Python 环境
|
||
|
||
### 4.1 创建虚拟环境
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
macOS/Linux 均使用 `.venv/bin/activate`。
|
||
|
||
### 4.2 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
依赖清单(26 个包):pytest, playwright, pytest-playwright, pytest-html, pytest-cov, python-dotenv, Pillow, httpx, allure-pytest, flask, flask-cors, requests, lark-oapi, pre-commit, ruff, mypy
|
||
|
||
### 4.3 安装 Playwright 浏览器
|
||
|
||
```bash
|
||
playwright install chromium
|
||
```
|
||
|
||
这会下载 Chromium 浏览器到 `~/.cache/ms-playwright/`,约 150MB。如果下载失败,设置镜像:
|
||
|
||
```bash
|
||
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
|
||
playwright install chromium
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 前端构建
|
||
|
||
### 5.1 安装 pnpm(如未安装)
|
||
|
||
```bash
|
||
npm install -g pnpm
|
||
```
|
||
|
||
### 5.2 安装依赖并构建
|
||
|
||
```bash
|
||
cd frontend
|
||
pnpm install
|
||
pnpm build
|
||
cd ..
|
||
```
|
||
|
||
构建产物在 `frontend/dist/`,Flask 后端会直接 serve 这个目录。
|
||
|
||
---
|
||
|
||
## 6. 启动平台
|
||
|
||
### 方式一:直接启动(推荐生产环境)
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
python -m backend.app
|
||
```
|
||
|
||
访问 `http://127.0.0.1:5001`
|
||
|
||
### 方式二:开发模式(前端热重载)
|
||
|
||
终端 1 — 后端:
|
||
```bash
|
||
source .venv/bin/activate
|
||
python -m backend.app
|
||
```
|
||
|
||
终端 2 — 前端 dev server:
|
||
```bash
|
||
cd frontend
|
||
pnpm dev
|
||
```
|
||
|
||
访问 `http://localhost:5173`(Vite 自动代理 API 到 5001)
|
||
|
||
### 方式三:Docker
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker compose build
|
||
|
||
# 启动平台
|
||
docker compose up -d platform
|
||
|
||
# 运行测试
|
||
docker compose run --rm tests
|
||
docker compose run --rm tests pytest -m smoke
|
||
```
|
||
|
||
访问 `http://127.0.0.1:5001`
|
||
|
||
---
|
||
|
||
## 7. 验证部署
|
||
|
||
### 7.1 健康检查
|
||
|
||
```bash
|
||
curl http://127.0.0.1:5001/api/health
|
||
```
|
||
|
||
预期响应:
|
||
```json
|
||
{"status":"ok","version":"2.0.0","tasks_count":0,"reports_count":0}
|
||
```
|
||
|
||
### 7.2 前端页面
|
||
|
||
浏览器打开 `http://127.0.0.1:5001`,应看到 AutoFlow 平台仪表盘。
|
||
|
||
### 7.3 运行测试
|
||
|
||
```bash
|
||
# 冒烟测试
|
||
pytest tests/ -m smoke -v
|
||
|
||
# 单模块测试
|
||
pytest tests/data_space/ -v
|
||
|
||
# 查看测试收集
|
||
pytest tests/ --collect-only -q
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 无屏幕工作站部署(macOS 常驻服务)
|
||
|
||
部署到无屏幕 MacBook 后,需要解决三个问题:**后台常驻**(SSH 断开不停止)、**开机自启**、**局域网共享**。
|
||
|
||
### 7.1 网络访问
|
||
|
||
后端已绑定 `0.0.0.0:5001`,局域网内其他设备可直接访问。查看工作站 IP:
|
||
|
||
```bash
|
||
ipconfig getifaddr en0
|
||
```
|
||
|
||
假设 IP 为 `192.168.1.100`,局域网内访问 `http://192.168.1.100:5001` 即可。
|
||
|
||
### 7.2 使用 launchd 注册为系统服务
|
||
|
||
macOS 原生服务管理器,无需 Docker。
|
||
|
||
创建 `/Users/<用户名>/Library/LaunchAgents/com.autoflow.platform.plist`:
|
||
|
||
```xml
|
||
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
||
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||
<plist version="1.0">
|
||
<dict>
|
||
<key>Label</key>
|
||
<string>com.autoflow.platform</string>
|
||
|
||
<key>ProgramArguments</key>
|
||
<array>
|
||
<string>/Users/用户名/TBC/.venv/bin/python</string>
|
||
<string>-m</string>
|
||
<string>backend.app</string>
|
||
</array>
|
||
|
||
<key>WorkingDirectory</key>
|
||
<string>/Users/用户名/TBC</string>
|
||
|
||
<key>EnvironmentVariables</key>
|
||
<dict>
|
||
<key>PLATFORM_PORT</key>
|
||
<string>5001</string>
|
||
<key>PATH</key>
|
||
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/用户名/.local/bin:/opt/homebrew/bin</string>
|
||
</dict>
|
||
|
||
<key>RunAtLoad</key>
|
||
<true/>
|
||
|
||
<key>KeepAlive</key>
|
||
<true/>
|
||
|
||
<key>StandardOutPath</key>
|
||
<string>/Users/用户名/TBC/logs/platform.log</string>
|
||
|
||
<key>StandardErrorPath</key>
|
||
<string>/Users/用户名/TBC/logs/platform_error.log</string>
|
||
|
||
<key>ProcessType</key>
|
||
<string>Background</string>
|
||
</dict>
|
||
</plist>
|
||
```
|
||
|
||
**关键字段说明:**
|
||
|
||
| 字段 | 作用 |
|
||
|------|------|
|
||
| `RunAtLoad` | 开机自动启动 |
|
||
| `KeepAlive` | 进程崩溃后自动重启 |
|
||
| `WorkingDirectory` | 确保相对路径(`.env`、`platform_db.json`)正确解析 |
|
||
| `StandardOutPath` / `StandardErrorPath` | 日志输出到文件,方便排查 |
|
||
|
||
### 7.3 加载与管理
|
||
|
||
```bash
|
||
# 创建日志目录
|
||
mkdir -p ~/TBC/logs
|
||
|
||
# 加载服务(立即启动 + 开机自启)
|
||
launchctl load ~/Library/LaunchAgents/com.autoflow.platform.plist
|
||
|
||
# 查看服务状态
|
||
launchctl list | grep autoflow
|
||
|
||
# 停止服务
|
||
launchctl unload ~/Library/LaunchAgents/com.autoflow.platform.plist
|
||
|
||
# 查看日志
|
||
tail -f ~/TBC/logs/platform.log
|
||
```
|
||
|
||
### 7.4 验证内网访问
|
||
|
||
```bash
|
||
# 在工作站上
|
||
curl http://localhost:5001/api/health
|
||
|
||
# 在其他电脑浏览器访问
|
||
# http://<工作站IP>:5001
|
||
```
|
||
|
||
### 7.5 防火墙放行(如启用)
|
||
|
||
```bash
|
||
# macOS 防火墙放行 Python
|
||
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Users/用户名/TBC/.venv/bin/python
|
||
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp /Users/用户名/TBC/.venv/bin/python
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 持久化数据
|
||
|
||
平台使用 JSON 文件存储数据,无需安装数据库:
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `platform_db.json` | 任务和报告状态持久化 |
|
||
| `platform_reports/` | 任务日志 JSON 文件 |
|
||
| `platform_artifacts/screenshots/` | 测试截图 |
|
||
| `.auth/state.json` | SSO 登录状态缓存 |
|
||
|
||
首次启动时这些文件会自动创建。
|
||
|
||
---
|
||
|
||
## 10. 目录结构
|
||
|
||
```
|
||
TBC/
|
||
├── backend/ # Flask 后端
|
||
│ ├── __init__.py
|
||
│ ├── __main__.py # 模块入口
|
||
│ └── app.py # 主应用 (809 行)
|
||
├── frontend/ # React 前端
|
||
│ ├── package.json
|
||
│ ├── vite.config.ts
|
||
│ └── src/
|
||
├── tests/ # D-Cloud 测试 (16 模块, 856 用例)
|
||
├── scenarios/ # Robogo 场景脚本
|
||
├── framework/ # 核心自动化框架
|
||
├── bot/ # 飞书机器人
|
||
├── config/ # 统一配置
|
||
│ └── settings.py
|
||
├── scripts/ # 工具脚本
|
||
├── specs/ # 测试规格文档
|
||
├── requirements.txt # Python 依赖
|
||
├── Dockerfile # Docker 镜像
|
||
├── docker-compose.yml # Docker Compose 编排
|
||
├── .env.example # 环境变量模板
|
||
├── pyproject.toml # 项目元数据
|
||
└── DEPLOY.md # 本文件
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 常见问题
|
||
|
||
### 10.1 Playwright 浏览器下载失败
|
||
|
||
```bash
|
||
# 设置国内镜像
|
||
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
|
||
playwright install chromium
|
||
|
||
# 或手动安装系统依赖 (Ubuntu)
|
||
playwright install-deps chromium
|
||
```
|
||
|
||
### 10.2 端口被占用
|
||
|
||
```bash
|
||
# 修改 .env 中的 PLATFORM_PORT
|
||
PLATFORM_PORT=5002
|
||
```
|
||
|
||
### 10.3 前端构建失败
|
||
|
||
```bash
|
||
# 清理并重试
|
||
cd frontend
|
||
rm -rf node_modules dist
|
||
pnpm install
|
||
pnpm build
|
||
```
|
||
|
||
### 10.4 Python 版本不兼容
|
||
|
||
项目要求 Python 3.10–3.12。如果系统默认 Python 版本不对:
|
||
|
||
```bash
|
||
# macOS (Homebrew)
|
||
brew install python@3.12
|
||
python3.12 -m venv .venv
|
||
|
||
# Ubuntu
|
||
sudo apt install python3.12 python3.12-venv
|
||
python3.12 -m venv .venv
|
||
```
|
||
|
||
### 10.5 前端页面空白
|
||
|
||
检查 `frontend/dist/` 是否存在,如果不存在需要先构建:
|
||
|
||
```bash
|
||
cd frontend && pnpm build
|
||
```
|
||
|
||
### 10.6 测试登录失败
|
||
|
||
检查 `.env` 中的 `TEST_USERNAME` 和 `TEST_PASSWORD` 是否正确,以及是否能访问 `BASE_URL` 和 `SSO_URL`。
|
||
|
||
---
|
||
|
||
## 12. CI/CD(可选)
|
||
|
||
当前项目无 CI 配置。建议添加 `.gitea/workflows/test.yml`:
|
||
|
||
```yaml
|
||
name: AutoFlow Tests
|
||
on: [push, pull_request]
|
||
jobs:
|
||
test:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- uses: actions/setup-python@v5
|
||
with:
|
||
python-version: '3.12'
|
||
- run: pip install -r requirements.txt
|
||
- run: playwright install chromium
|
||
- run: pytest tests/ -m smoke -v
|
||
- run: ruff check .
|
||
```
|
||
|
||
---
|
||
|
||
## 13. 一键部署脚本
|
||
|
||
将以下内容保存为 `deploy.sh`:
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
set -e
|
||
|
||
echo "=== AutoFlow 一键部署 ==="
|
||
|
||
# 检查 Python
|
||
if ! command -v python3 &> /dev/null; then
|
||
echo "❌ python3 未安装,请先安装 Python 3.10–3.12"
|
||
exit 1
|
||
fi
|
||
|
||
# 检查 Node
|
||
if ! command -v node &> /dev/null; then
|
||
echo "❌ node 未安装,请先安装 Node.js >= 18"
|
||
exit 1
|
||
fi
|
||
|
||
# 创建 .env
|
||
if [ ! -f .env ]; then
|
||
cp .env.example .env
|
||
echo "⚠️ 已创建 .env,请编辑填入实际配置后重新运行"
|
||
exit 1
|
||
fi
|
||
|
||
# Python 环境
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
playwright install chromium
|
||
|
||
# 前端
|
||
if ! command -v pnpm &> /dev/null; then
|
||
npm install -g pnpm
|
||
fi
|
||
cd frontend && pnpm install && pnpm build && cd ..
|
||
|
||
# 启动
|
||
echo "✅ 部署完成,启动平台..."
|
||
python -m backend.app
|
||
```
|
||
|
||
### 安装为 macOS 常驻服务
|
||
|
||
```bash
|
||
# 复制 plist 并替换路径
|
||
sed "s|__PROJECT_ROOT__|$(pwd)|g" com.autoflow.platform.plist > ~/Library/LaunchAgents/com.autoflow.platform.plist
|
||
|
||
# 创建日志目录
|
||
mkdir -p logs
|
||
|
||
# 加载服务
|
||
launchctl load ~/Library/LaunchAgents/com.autoflow.platform.plist
|
||
|
||
# 查看状态
|
||
launchctl list | grep autoflow
|
||
```
|
||
|
||
使用方法:
|
||
```bash
|
||
chmod +x deploy.sh
|
||
./deploy.sh
|
||
``` |