11 KiB
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. 克隆仓库
git clone https://gitea.d-robotics.cc/jiawei.chen/TBC.git
cd TBC
如果使用 SSH:
git clone git@gitea.d-robotics.cc:jiawei.chen/TBC.git
cd TBC
3. 环境配置
3.1 创建 .env 文件
cp .env.example .env
3.2 编辑 .env 填入实际值
# 必填
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 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate
macOS/Linux 均使用 .venv/bin/activate。
4.2 安装依赖
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 浏览器
playwright install chromium
这会下载 Chromium 浏览器到 ~/.cache/ms-playwright/,约 150MB。如果下载失败,设置镜像:
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
playwright install chromium
5. 前端构建
5.1 安装 pnpm(如未安装)
npm install -g pnpm
5.2 安装依赖并构建
cd frontend
pnpm install
pnpm build
cd ..
构建产物在 frontend/dist/,Flask 后端会直接 serve 这个目录。
6. 启动平台
方式一:直接启动(推荐生产环境)
source .venv/bin/activate
python -m backend.app
访问 http://127.0.0.1:5001
方式二:开发模式(前端热重载)
终端 1 — 后端:
source .venv/bin/activate
python -m backend.app
终端 2 — 前端 dev server:
cd frontend
pnpm dev
访问 http://localhost:5173(Vite 自动代理 API 到 5001)
方式三:Docker
# 构建镜像
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 健康检查
curl http://127.0.0.1:5001/api/health
预期响应:
{"status":"ok","version":"2.0.0","tasks_count":0,"reports_count":0}
7.2 前端页面
浏览器打开 http://127.0.0.1:5001,应看到 AutoFlow 平台仪表盘。
7.3 运行测试
# 冒烟测试
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:
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 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 加载与管理
# 创建日志目录
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 验证内网访问
# 在工作站上
curl http://localhost:5001/api/health
# 在其他电脑浏览器访问
# http://<工作站IP>:5001
7.5 防火墙放行(如启用)
# 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 浏览器下载失败
# 设置国内镜像
export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright/
playwright install chromium
# 或手动安装系统依赖 (Ubuntu)
playwright install-deps chromium
10.2 端口被占用
# 修改 .env 中的 PLATFORM_PORT
PLATFORM_PORT=5002
10.3 前端构建失败
# 清理并重试
cd frontend
rm -rf node_modules dist
pnpm install
pnpm build
10.4 Python 版本不兼容
项目要求 Python 3.10–3.12。如果系统默认 Python 版本不对:
# 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/ 是否存在,如果不存在需要先构建:
cd frontend && pnpm build
10.6 测试登录失败
检查 .env 中的 TEST_USERNAME 和 TEST_PASSWORD 是否正确,以及是否能访问 BASE_URL 和 SSO_URL。
12. CI/CD(可选)
当前项目无 CI 配置。建议添加 .gitea/workflows/test.yml:
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:
#!/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 常驻服务
# 复制 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
使用方法:
chmod +x deploy.sh
./deploy.sh