工作流自动化桌面应用AI 应用企业应用后端前端【免费下载链接】astron-rpaAgent-ready RPA suite with out-of-the-box automation tools. Built for individuals and enterprises.项目地址https://gitcode.com/bijinfeng/astron-rpa点击查看免费下载导读RPA OpenAPI Service 是 astron-rpa 项目中面向外部集成与自动化编排的开放 API 服务它基于 FastAPI 构建为 RPA 平台提供工作流创建、执行、监控和 API 密钥管理等完整能力并深度集成 WebSocket 实时通信与 MCPModel Context Protocol协议使 AI 模型和第三方编排工具如 n8n能够通过统一入口发现并异步执行 RPA 工作流。阅读本文后你将掌握该服务的分层架构、全部核心接口、MCP 稳定工具契约、外部集成安全模型以及从本地启动到 Docker 生产部署的完整实战路径。该服务是 astron-rpa 中backend/openapi-service子项目其设计文档与安全契约分别见 README.zh.md、外部集成安全契约 与 执行管理契约。一、服务定位与项目概览RPA OpenAPI Service 是 RPA 平台对外提供 API 能力的关键入口承担“工作流即服务”的职责。从 应用入口 的FastAPI(titleRPA OpenAPI, version1.2.0)可以看出服务以独立 FastAPI 应用形态存在通过 lifespan 生命周期统一管理 Redis 连接池、WebSocket 管理器单例、MCP StreamableHTTP 会话管理器以及执行恢复任务recover_executions。服务的主要特性包括工作流管理工作流的创建、更新、查询和删除支持“个人工作流”与“公开工作流”分类统计实时执行基于 WebSocket 的工作流实时执行与状态监控支持多客户端连接API 密钥管理完整的密钥生成、验证和管理包含密钥掩码展示与 bcrypt 哈希校验MCP 协议支持集成 Model Context Protocol提供稳定的工作流控制工具集供 AI 模型与外部集成调用请求链路追踪全局 Request ID 生成、传递与日志注入结构化日志统一日志格式、文件轮转与敏感数据脱敏依赖注入FastAPI 依赖注入体系便于测试与维护Redis 集成异步 Redis 连接池max_connections10测试框架pytest pytest-asyncio 异步测试容器化部署Docker Docker Compose。二、分层架构解析该服务采用清晰的分层架构设计所有模块集中在backend/openapi-service/app/下各层职责边界明确1. API 路由层app/routers/路由模块职责workflows.py工作流 CRUD、同步/异步执行、停止、星辰 Agent 工作流拉取executions.py执行记录分页查询、执行状态与结果查询api_keys.pyAPI 密钥与星辰 Agent 凭据的增删改查websocket.pyWebSocket 实时通信与状态推送streamable_mcp.pyMCP Streamable HTTP 协议端点与工具分发healthcheck.py / user.py / mcp_modern.py健康检查、用户注册默认禁用、双协议 MCP 适配在 入口文件 中所有路由以/admin、/workflows、/executions、/api-keys、/ws等前缀注册MCP 端点则通过app.mount(/mcp, handle_streamable_http)挂载为 ASGI 子应用。2. 服务层app/services/workflow.py工作流业务逻辑区分内部查询与“外部授权查询”get_external_workflows/get_external_workflowexecution.py执行逻辑通过execute_authorized_workflow统一处理 REST 与 MCP 的启动execution_management.py持久化分发与对账实现幂等启动与确认式取消websocket.pyWebSocket 管理器WsManagerService与消息服务api_key.py密钥生成、验证及星辰 Agent 凭据管理workflow_control.py外部集成共享的授权工作流控制服务REST 与 MCP 共用同一执行核心。3. 数据模型层app/schemas/与app/models/Pydantic 模式定义请求/响应结构包括workflow.py工作流与执行数据、api_key.py密钥数据、mcp.py稳定控制工具与输入/输出 JSON SchemaSQLAlchemy ORM 模型位于app/models/含Workflow、Execution、OpenAPIDB密钥表等。4. 公共组件层dependencies/init.py身份认证API 密钥 / 网关头部身份与各服务依赖的工厂函数middlewares/tracing.py请求追踪中间件与 Request ID 上下文internal/admin.py内部管理接口security/API 密钥解析校验api_key.py、MCP 鉴权mcp_auth.py、工作流授权workflow_authorization.py。5. 配置与连接管理层config.pyPydantic Settings 环境配置redis.py异步 Redis 连接池database.py异步 SQLAlchemy 引擎与会话含连接池调优与重试装饰器logger.py统一日志配置与敏感数据脱敏。三、技术栈与版本要求组件技术选型版本要求以 pyproject.toml 为准后端框架FastAPIfastapi[standard]0.135.1文档标注 0.115.12PythonPython3.11pyproject 中requires-python 3.13数据库MySQL SQLAlchemySQLAlchemy 2.0.41驱动 aiomysql 0.2.0缓存Redisredis[hiredis] 6.1.0配置管理Pydantic Settings2.9.1pydantic2.12.5MCPmcp1.26.0Streamable HTTP密码学bcrypt / cryptographybcrypt4.3.0cryptography45.0.2校验jsonschema4.26.0Draft 2020-12 输出校验WebSocket 协议rpawebsocket1.0.7本地 wheel 锁定测试框架pytest pytest-asyncio8.3.5代码质量Ruff0.11.11依赖管理uvuv.lock锁定值得注意pyproject.toml通过[tool.uv.sources]将rpawebsocket锁定为app/utils/rpawebsocket-1.0.7-py3-none-any.whl本地包确保客户端协议实现版本一致。四、核心功能详解4.1 工作流管理/workflows工作流接口在 workflows.py 中实现统一以StandardResponse包裹返回接口方法说明/workflows/upsertPOST创建或更新工作流若project_id已存在且属于他人则拒绝属于本人则更新/workflows/getGET分页获取工作流列表返回total、personal_total、public_total与records/workflows/get/{project_id}GET按项目 ID 查询工作流详情/workflows/executePOST同步执行等待结果超时 600 秒未完成返回 202/workflows/execute-asyncPOST异步执行立即返回executionId工作流超时 10 小时/workflows/stop-currentPOST停止当前用户正在运行的工作流仅作用于本人客户端/workflows/get-astronGET拉取绑定的星辰 Agent 的所有工作流从源码看工作流的创建/更新通过service.get_workflow判断存在性执行则统一走execution_service.execute_authorized_workflow同步/异步仅体现在wait参数与超时时间上这正是“REST 与 MCP 共用执行核心”的实现基础。注意/workflows/copy-workflow接口已明确返回 403禁止跨用户复制工作流。4.2 工作流执行/executionsexecutions.py 提供执行记录查询能力接口方法说明/executions/getGET按 API 密钥归属用户分页查询执行记录返回total、total_pages等/executions/{execution_id}GET查询指定执行的状态与结果未找到返回 404执行记录通过external_execution_dict序列化见 workflow_authorization.py仅暴露外部安全模型允许的字段。底层执行对账在 execution_management.py 中完成只有NEW状态的收据可以触发启动SENT状态只能查询/取消绑定的 Client绝不把“无响应”当作重试信号以此保证启动操作的幂等语义。4.3 API 密钥管理/api-keysapi_keys.py 提供密钥与星辰 Agent 凭据管理接口方法说明/api-keys/getGET获取当前用户密钥列表返回掩码/api-keys/createPOST创建新密钥仅创建响应返回原始密钥/api-keys/removePOST删除指定密钥/api-keys/create-astronPOST绑定星辰 Agentapi_key与api_secret均不能为空/api-keys/get-astron/get-astron-by-idGET查询星辰 Agent 列表与详情/api-keys/remove-astron/update-astronPOST删除 / 更新星辰 Agent密钥校验逻辑在 security/api_key.py 中存储采用 bcrypt 哈希validate_api_key通过prefix前 8 字符快速定位候选再完整校验同时防御 bcrypt 72 字节截断问题——超过 72 字节的密钥一律拒绝。每次请求都会重新校验密钥不存在“正向认证缓存”因此吊销立即生效。4.4 WebSocket 实时通信/wswebsocket.py 定义 WebSocket 端点客户端需在请求头携带user_id缺失时以1008状态码关闭连接。连接建立后WsManagerService并行执行三件事ws_mg.listen(user_id, Conn(...))监听该用户的执行消息ws_mg.start_ping()心跳保活ws_mg.clear_watch()清理过期订阅。WebSocket 通道承载工作流执行状态推送与日志流并作为 REST/MCP 启动请求通往 RPA 客户端的底层传输execution_request即通过ws_manager发出。每个收到的消息都会绑定到独立处理器包括缓冲的 busy/success 回复这是对rpawebsocket1.0.7 监听器的兼容性修复。4.5 MCP 协议支持/mcpMCP 端点在 streamable_mcp.py 中实现使用StreamableHTTPSessionManager构建无状态 Streamable HTTP 会话。外部集成连接https://服务域名/api/rpa-openapi/mcp/即可发现与调用工具。MCP 鉴权方式生产环境推荐 Bearer 方式Authorization: Bearer API_KEY也支持独立请求头X-API-Key: API_KEY默认不接受 URL 查询参数中的?key——查询字符串常出现在浏览器历史与代理访问日志中存在密钥泄露风险。仅在迁移旧客户端时临时设置MCP_ALLOW_QUERY_API_KEYtrue。同一请求只能使用一种凭据来源缺失、格式错误、无效或已吊销的密钥统一返回 HTTP 401对应配置项定义见 config.py。稳定工作流控制工具schemas/mcp.py 定义了六个保留工具名它们与 REST 共用执行核心不依赖工作流名称、n8n 或特定部署地址工具输入返回astron_integration_get无集成契约版本与 Client 就绪状态不启动执行astron_workflow_list可选offset、limit1100当前用户开放的工作流及nextOffsetastron_workflow_getprojectId发布版本、输入inputSchema、supportsCancel、profileastron_workflow_executeprojectId可选params、version、idempotencyKey、executionTimeout、profileRevision立即返回执行快照含executionIdastron_execution_getexecutionId执行状态、结果或安全错误摘要astron_execution_cancelexecutionId请求取消cancelRequested仅为意图需查询确认终态关键语义约束源自 workflow_control.py 与 MCP 工具定义项目 ID 为字符串启动仅允许当前用户开放的发布版本省略版本时由服务端选择查询时重新检查所有权与授权关闭外部调用或更换授权发布版本后旧版本记录不再通过此入口公开输入类型当前稳定入口支持 string、integer、number 输入并保留零值拒绝未知字段、文件、密码、复杂对象及无法识别的参数元数据输出成功结果同时返回structuredContent与等价的 JSON 文本并附带输入/输出 JSON Schema错误工具调用错误使用isErrortrue和error.code/message不回显输入参数或内部异常执行快照字段executionId、projectId、version、status、terminal、acceptedAt、finishedAt、result、error等acceptedAt为服务端记录创建时间状态机accepted、running、succeeded、failed、unknown持久化模型中还有cancelled、timeout当前 Client 通道通常只能观察到受理与终态查询成功不等于任务成功仅succeeded与failed为已知终态错误摘要码CLIENT_OFFLINE、CLIENT_BUSY、EXECUTION_FAILED、EXECUTION_RESULT_TIMEOUT等unknown表示未能确认实际结果不证明任务仍在运行或已停止幂等性启动操作尚不具备幂等性调用方必须关闭自动重试取得executionId后应经 MCP 轮询等待超时也应保留该 ID后台任务继续执行。上述约束在 execution_management.py 中与持久化状态PENDING/RUNNING/COMPLETED/FAILED/CANCELLED/TIMEOUT/UNKNOWN一一对应digest()通过 SHA-256 计算参数摘要以支持幂等对账。五、快速开始环境要求Python 3.11pyproject 实际要求 3.13MySQL 8.0Redis 7.0Docker Docker Compose可选1. 安装依赖# 使用 pip 安装 pip install -e . # 或使用 uv推荐uv.lock 已锁定依赖版本 uv sync2. 配置环境变量配置文件按优先级从低到高为.env.default.env.env.local其中.env.local仅用于本地调试切勿在生产环境使用。run.py启动脚本会在加载时按此顺序覆盖加载。创建.env文件# 数据库配置 DATABASE_URLmysqlaiomysql://username:passwordlocalhost:3306/my_service # Redis 配置 REDIS_URLredis://localhost:6379/0 # 应用名称 APP_NAMEMy New Service # 仅迁移旧 MCP 客户端时临时开启生产环境保持 false MCP_ALLOW_QUERY_API_KEYfalse除上述项外config.py 还支持DATABASE_USERNAME/DATABASE_PASSWORD用于替换DATABASE_URL中的占位符密码会经 URL 编码支持动态注入LOG_LEVEL日志级别默认INFOLOG_DIR日志目录默认/var/log/rpa-openapiMCP_ALLOWED_ORIGINS浏览器来源白名单逗号分隔为空则默认拒绝浏览器来源INTEGRATION_POLICY_FILE可信部署策略文件路径用于社区节点准入校验为空保留历史调用方。3. 启动服务# 使用 uvicorn 直接启动开发环境 uvicorn app.main:app --reload --host 0.0.0.0 --port 8020 # 或使用 run.py 启动支持环境名参数 uv run python run.py dev # 开发环境自动热重载 uv run python run.py prod # 生产环境 uv run python run.py test # 测试环境run.py支持通过ENVdev环境变量或首个命令行参数指定环境配置文件.env.dev、.env.prod、.env.test默认加载.env.default与.env。4. 验证服务访问 http://localhost:8020/docs 查看 Swagger UI 交互式 API 文档或 http://localhost:8020/redoc 查看 ReDoc 阅读版文档。六、Docker 部署生产环境部署创建.env文件并配置环境变量启动服务docker-compose up -d查看状态与日志docker-compose ps docker-compose logs -f app在根目录 docker-compose.yml 中openapi-service 容器rpa-opensource-openapi-service以镜像ghcr.io/iflytek/astron-rpa/openapi-service:latest运行内部端口 8020开发环境下将backend/openapi-service/app挂载到容器/app/app并通过OPENAPI_WORKFLOWS_UPSERT_URL等环境变量与其他服务联动。安全契约特别强调OpenAPI 容器端口必须保持私有不能直接暴露公网否则调用方伪造user_id等身份头会破坏信任边界。单元测试环境部署# 启动测试依赖服务 docker-compose -f docker-compose.test.yaml up -d # 运行测试 pytest七、开发指南运行测试# 启动测试数据库 docker-compose -f docker-compose.test.yaml up -d # 运行所有测试 pytest # 运行特定测试文件 pytest tests/routers/test_items.py # 运行测试并显示覆盖率 pytest --covapp仓库中的测试覆盖了 路由层工作流、执行、API 密钥、端到端、条目、服务层MCP、工作流、流式会话、执行管理、执行隔离、集成策略等以及 安全专项MCP 鉴权、工作流隔离、外部安全、敏感日志、WebSocket 突发压力等其中test_execution_management.py直接验证持久化幂等与对账逻辑。代码质量检查# 格式化代码 ruff format # 检查代码质量 ruff check # 修复可自动修复的问题 ruff check --fix查看日志# 实时查看应用日志默认目录 /var/log/rpa-openapi tail -f /var/log/rpa-openapi/app.log八、日志与请求追踪日志配置日志级别通过LOG_LEVEL环境变量配置默认INFO日志目录通过LOG_DIR配置默认/var/log/rpa-openapi日志格式时间戳 - 模块名 - [请求ID] - 日志级别 - 消息内容文件轮转单文件 10 MB保留 10 个备份见 logger.py敏感脱敏SensitiveDataFilter与SensitiveFormatter对控制台、文件以及 uvicorn access 日志统一脱敏防止旧 MCP?key查询参数被写入访问日志。请求追踪每个请求都会分配唯一 Request IDtracing.py2025-06-06 10:30:15 - app.main - [abc-123-def] - INFO - Root endpoint accessed!Request ID 的流转机制优先读取请求头X-Request-ID否则生成 UUID存入contextvars.ContextVar响应头X-Request-ID回传同一 ID便于客户端关联通过RequestIdFilter注入每条日志记录全链路可追踪。另外main.py 对RequestValidationError做了安全化处理只保留错误位置与类型替换掉 FastAPI 默认返回的“被拒绝的原始输入值”避免 API 密钥、密码与工作流参数出现在 422 错误响应中。九、外部集成安全契约外部集成的安全边界定义在 EXTERNAL_INTEGRATION_SECURITY.md 中核心要点如下身份与信任边界外部调用使用且仅使用一个凭据Authorization: Bearer API_KEY或X-API-Key: API_KEY两套传输MCP 与 REST共用同一套活跃密钥查询与 bcrypt 校验重复/冲突头、畸形凭据、无效/已吊销密钥统一返回 401每次请求都重新校验密钥无正向缓存认证存储故障返回 503 且不泄露数据库细节网关在认证前剥离调用方传入的user_id、X-User-Id、user-info仅转发既有机器人/认证服务的身份API 密钥请求不能访问管理路由也不能伪装成桌面 WebSocket 连接。密钥生命周期与轮换创建密钥通过已登录的桌面会话设置页完成仅创建响应返回原始密钥之后列表只返回掩码。原始密钥应保存在调用方的凭据存储中严禁写入工作流 JSON、URL、源码或导出的示例。推荐的无任务轮换流程为目标身份/环境创建新密钥用新凭据初始化 MCP发现并读取授权工作流空的工作流列表是认证成功的正常结果不是启动任务的理由将调用方切换到新凭据通过所有者会话吊销旧密钥后续 MCP/REST 请求包括已建立的 HTTP 连接上的请求必须拒绝之。吊销只阻止新请求不等于取消已受理的执行密钥无自动过期运维方应制定轮换计划并显式吊销未使用/已泄露的密钥。授权矩阵节选入口身份强制资源权限固定 MCP list/getAPI 密钥所有者 外部访问开启 有效发布版本固定 MCP / REST 启动API 密钥授权项目/当前版本 准入名单仅执行器角色MCP 执行查询/取消、REST 执行列表/查询API 密钥执行所有者 当前工作流所有者 外部访问开启密钥创建/吊销、工作流 upsert、星辰凭据管理桌面会话私有网关当前用户/workflows/stop-currentAPI 密钥仅作用于认证用户自身客户端普通重新发布保留对已受理执行记录的访问撤销外部访问、删除工作流或变更所有权会拒绝访问包括 REST 列表计数但不会停止已受理的任务。MCP 工具级别的拒绝使用isError/安全业务错误而非 HTTP 授权状态码。n8n 集成要点字段契约MCP Endpoint部署提供的完整 HTTPS URL含路径不要猜测或丢弃路径段API Key密钥凭据字段标准 Bearer 头绝不放入查询数据ProtocolMCP2025-11-25over Streamable HTTP无自动协议升级/回退n8n 的 AstronRPA 社区节点实现位于 integrations/n8n/n8n-nodes-astron-rpa全部业务操作走 MCP连接测试只允许初始化 MCP、发现工具和执行授权读取不得调用 execute/stop、不得走 REST 回退启动、不得自动重试启动。十、常见问题Q: 如何修改默认端口号A: 可以通过环境变量或启动命令指定# 在命令中指定 uvicorn app.main:app --host 0.0.0.0 --port 8020 # 或在 docker-compose.yml 中修改端口映射 ports: - 8080:8000Q: 如何处理大量并发请求A: 考虑以下方案增加 uvicorn workers 数量--workers 4注意每个 worker 持有独立的 WebSocket 管理器实例WebSocket 连接是进程级别的这是设计预期使用 Gunicorn 作为进程管理器对耗时操作使用异步处理利用数据库连接池与 Redis 缓存提升吞吐database.py 已配置pool_size20、max_overflow30、pool_recycle1800秒、pool_pre_pingTrue。Q: 如何监控服务健康状况A:使用健康检查端点/health含/health/remote-check、/health/local-check仅报告该用户客户端的在线状态不启动任何工作查看日志文件了解运行情况监控 Redis 与 MySQL 连接状态高级场景可接入 Prometheus 与 Grafana。Q: 如何部署到生产环境A:使用 Docker Compose 或 Kubernetes 管理容器配置反向代理如 Nginx处理 SSL 与请求分发——HTTPS 部署与 Casdoor 认证初始化/轮换步骤参见 docker/HTTPS_DEPLOYMENT.md使用环境变量注入敏感配置保持 OpenAPI 容器端口私有设置适当的日志级别与监控并配套制定 API 密钥轮换计划。十一、许可证本服务随项目采用 MIT 许可证可自由使用、修改和分发无论用于个人项目还是商业项目。如需贡献可通过提交 Issue 报告问题或建议新功能通过 Pull Request 贡献代码改进。赞分享工作流自动化桌面应用AI 应用企业应用后端前端【免费下载链接】astron-rpaAgent-ready RPA suite with out-of-the-box automation tools. Built for individuals and enterprises.项目地址https://gitcode.com/bijinfeng/astron-rpa点击查看免费下载相关推荐AstronRPA OpenAPI Service 深度指南基于 FastAPI 的 RPA 工作流管理与 MCP 集成实战AstronRPA OpenAPI Service 深度指南基于 FastAPI 的 RPA 工作流管理与 MCP 集成实战 导读 backend/opena工作流自动化桌面应用AI 应用企业应用后端前端Astron Agent 中 RPA 服务的 API 调用实战基于 Xingchen RPA Server 的多语言客户端与错误处理指南Astron Agent 中 RPA 服务的 API 调用实战基于 Xingchen RPA Server 的多语言客户端与错误处理指南 本指南以 astro人工智能AI AgentAgent 编排RPA后端前端企业应用Genie MCP Client API 服务实战基于 FastAPI 与 SSE 的 MCP 工具网关接入指南Genie MCP Client API 服务实战基于 FastAPI 与 SSE 的 MCP 工具网关接入指南 导读 本文围绕开源通用智能体项目 joya人工智能AI Agent多智能体Agent 框架RAG工具调用代码智能体后端前端数据分析上一篇Apache OpenWhisk Feed 实现指南三种架构模式与 Feed Action 协议全解析下一篇Onlook 仓库 Agent 开发指南在 AI 优先的 React 设计工具 monorepo 中安全高效地提交代码创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
