TBC/DEPLOY.md

11 KiB
Raw Blame History

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