TBC/DEPLOY.md

523 lines
11 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
```