backend/openapi-service/README.zh.md
RPA OpenAPI Service 是一个基于 FastAPI 构建的 RPA 工作流管理服务，提供工作流创建、执行、监控和 API 密钥管理等功能。该服务集成了 WebSocket 实时通信、MCP (Model Context Protocol) 支持、Redis 缓存、请求链路追踪等现代化技术栈，为 RPA 平台提供完整的 API 服务能力。
该服务采用了清晰的分层架构设计，专门为 RPA 工作流管理而设计：
app/routers/)workflows.py) - 工作流的 CRUD 操作executions.py) - 工作流执行和状态监控api_keys.py) - API 密钥的生成和验证websocket.py) - 实时通信和状态推送streamable_mcp.py) - Model Context Protocol 支持app/services/)workflow.py) - 工作流业务逻辑处理execution.py) - 工作流执行逻辑websocket.py) - 实时通信管理api_key.py) - 密钥生成和验证逻辑app/schemas/)workflow.py) - 工作流数据结构定义execution.py) - 执行状态和结果定义api_key.py) - 密钥相关数据结构app/dependencies/) - 用户认证、服务依赖管理app/middlewares/) - 请求追踪中间件app/internal/) - 管理和维护接口app/config.py) - 环境变量和配置项管理app/redis.py) - 异步 Redis 连接池app/logger.py) - 统一的日志配置| 组件 | 技术选型 | 版本要求 |
|---|---|---|
| 后端框架 | FastAPI | >=0.115.12 |
| Python | Python | >=3.11 |
| 数据库 | MySQL + SQLAlchemy | >=2.0.41 |
| 缓存 | Redis | >=6.1.0 |
| 异步支持 | asyncio + aiomysql | >=0.2.10 |
| 配置管理 | Pydantic Settings | >=2.9.1 |
| 容器化 | Docker + Docker Compose | - |
| 测试框架 | pytest + pytest-asyncio | >=8.3.5 |
| 代码质量 | Ruff | >=0.11.11 |
| 依赖管理 | uv | - |
rpa-openapi-service/
├── app/ # 应用主目录
│ ├── main.py # FastAPI 应用入口
│ ├── config.py # 配置管理
│ ├── redis.py # Redis 连接池管理
│ ├── logger.py # 日志配置
│ ├── dependencies/ # 依赖注入模块
│ │ └── __init__.py # 通用依赖注入
│ ├── schemas/ # Pydantic 数据模式
│ │ ├── workflow.py # 工作流数据结构
│ │ ├── execution.py # 执行状态和结果
│ │ └── api_key.py # API 密钥数据结构
│ ├── routers/ # API 路由
│ │ ├── workflows.py # 工作流管理路由
│ │ ├── executions.py # 执行管理路由
│ │ ├── api_keys.py # API 密钥管理路由
│ │ ├── websocket.py # WebSocket 通信路由
│ │ └── streamable_mcp.py # MCP 协议支持
│ ├── services/ # 业务逻辑服务
│ │ ├── workflow.py # 工作流服务
│ │ ├── execution.py # 执行服务
│ │ ├── api_key.py # API 密钥服务
│ │ └── websocket.py # WebSocket 服务
│ ├── middlewares/ # 中间件
│ │ └── tracing.py # 请求追踪中间件
│ └── internal/ # 内部管理接口
│ └── admin.py # 管理员接口
├── tests/ # 测试代码
│ ├── conftest.py # 测试配置
│ ├── test_main.py # 主应用测试
│ └── routers/ # 路由测试
├── logs/ # 日志目录
├── Dockerfile # Docker 镜像构建
├── pyproject.toml # 项目依赖配置
├── uv.lock # uv 依赖锁定文件
└── README.md # 项目说明文档
/workflows)/workflows/upsert) - 支持工作流的创建和更新/workflows/{project_id}) - 根据项目ID查询工作流详情/workflows) - 分页查询工作流列表/workflows/{project_id}) - 删除指定工作流/executions)/executions) - 创建工作流执行任务/executions/{execution_id}) - 获取执行状态和结果/executions) - 分页查询执行记录/executions/{execution_id}/cancel) - 取消正在执行的流程/api-keys)/api-keys) - 创建新的 API 密钥/api-keys) - 查询用户的 API 密钥列表/api-keys/{key_id}) - 删除指定的 API 密钥/ws)/mcp)# 使用 pip 安装
pip install -e .
# 或使用 uv (推荐)
uv sync
推荐使用 uv 进行依赖管理，
uv.lock文件已锁定依赖版本，确保环境一致性。
配置文件有三个，按优先级从低到高排序：.env.default < .env < .env.local，其中 .env.local 仅用于本地调试，切勿在生产环境使用。
创建 .env 文件，配置必要的环境变量：
# 数据库配置
DATABASE_URL=mysql+aiomysql://username:password@localhost:3306/my_service
# Redis 配置
REDIS_URL=redis://localhost:6379/0
# 应用名称
APP_NAME="My New Service"
# 使用 uvicorn 直接启动（开发环境）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8020
# 或使用 uv 启动
uv run python run.py dev
访问 http://localhost:8020/docs 查看 API 文档。
配置环境变量
创建 .env 文件并配置相关环境变量。
启动服务
docker-compose up -d
查看服务状态
docker-compose ps
docker-compose logs -f app
启动测试依赖服务
docker-compose -f docker-compose.test.yaml up -d
运行测试
pytest
FastAPI 自动为您的 API 生成交互式文档：
/docs - 适合开发和调试/redoc - 更适合阅读和共享# 启动测试数据库
docker-compose -f docker-compose.test.yaml up -d
# 运行所有测试
pytest
# 运行特定测试文件
pytest tests/routers/test_items.py
# 运行测试并显示覆盖率
pytest --cov=app
# 格式化代码
ruff format
# 检查代码质量
ruff check
# 修复可自动修复的问题
ruff check --fix
# 实时查看应用日志
tail -f logs/app.log
该项目使用分层配置文件，可根据需要创建和修改：
.env.default - 默认配置，提交到版本控制.env - 环境特定配置，根据部署环境定制.env.local - 本地开发配置，不提交到版本控制配置项加载顺序：.env.default < .env < .env.local
LOG_LEVEL 环境变量配置（默认：INFO）LOG_DIR 环境变量配置每个请求都会分配唯一的 Request ID，便于问题排查：
2025-06-06 10:30:15 - app.main - [abc-123-def] - INFO - Root endpoint accessed!
请求 ID 会自动：
X-Request-IDA: 可以通过环境变量或直接在启动命令中指定：
# 在命令中指定
uvicorn app.main:app --host 0.0.0.0 --port 8020
# 或在 docker-compose.yml 中修改映射
ports:
- "8080:8000"
A: 考虑以下方案：
--workers 4A: 可以通过以下方式监控：
/healthA: 推荐的生产部署方案：
如果您有任何改进建议或问题，欢迎通过以下方式参与贡献：
本项目采用 MIT 许可证。您可以自由地使用、修改和分发此代码，无论是用于个人项目还是商业项目。