# 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= # 测试账号 TEST_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= ``` ### 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 Label com.autoflow.platform ProgramArguments /Users/用户名/TBC/.venv/bin/python -m backend.app WorkingDirectory /Users/用户名/TBC EnvironmentVariables PLATFORM_PORT 5001 PATH /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Users/用户名/.local/bin:/opt/homebrew/bin RunAtLoad KeepAlive StandardOutPath /Users/用户名/TBC/logs/platform.log StandardErrorPath /Users/用户名/TBC/logs/platform_error.log ProcessType Background ``` **关键字段说明:** | 字段 | 作用 | |------|------| | `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 ```