Skip to content

architecture.md

Latest commit

 

History

History
146 lines (127 loc) · 8.58 KB

architecture.md

File metadata and controls

146 lines (127 loc) · 8.58 KB
Raw

FlowTest 架构基线

1. 架构目标

FlowTest 采用模块化单体起步，在代码边界上区分控制平面与执行平面，待吞吐量和隔离需求明确后再拆分 Worker。

React Web
    │ REST / WebSocket
FastAPI Control Plane
    ├── Project / API / Environment / Workflow / Plan / Report
    ├── PostgreSQL
    ├── Redis / Celery Task Queue
    └── PostgreSQL Runner Task / Lease / Fence / Event
              │ HTTPS Runner Control Plane
        Execution Plane
        HTTPX + asyncio + DAG
        General / Data / Performance / Environment Runner
        Remote Docker / Kubernetes Runner Agent
              │
          Target APIs

2. 仓库结构

backend/app/
├── api/          # HTTP 适配层，不放业务规则
├── core/         # 配置、安全、数据库、日志
├── observability/# 低基数指标与运行状态
├── domain/       # 领域实体、值对象和规则
├── services/     # 应用用例与事务编排
├── repositories/ # 持久化接口及实现
├── models/       # SQLAlchemy 模型
├── schemas/      # API 输入输出契约
├── engine/       # Context、变量、映射、DAG 与节点执行器
├── http/         # 请求构造、异步客户端、响应解析
├── importers/    # OpenAPI / Swagger / Postman
├── assertions/   # 断言库
└── extractors/   # JSONPath / JMESPath / Header 等提取器

frontend/src/
├── pages/        # 路由页面
├── features/     # 领域功能
├── components/   # 跨功能组件
└── flow/         # 节点、边、画布和运行态

3. 首批领域边界

  • Identity：用户、角色、项目成员。
  • Project：项目与任意层级目录。
  • API Definition：请求、响应示例、断言配置及版本。
  • Environment：环境、变量、Secret 和 Header 继承。
  • Workflow：DAG、节点、边、字段映射和版本。
  • Execution：Snapshot、Context、节点结果、事件日志。
  • Test Plan：流程集合、触发器与调度。
  • Report：执行汇总、步骤详情、失败分类和趋势。
  • Data Source：加密 Credential、只读 SQL/Redis 适配器及出站网络策略。
  • Mock：无脚本的请求规则、模板响应与脱敏请求日志。
  • Protocol：GraphQL/gRPC Schema、Kafka/WebSocket 事件源与不可变协议 Snapshot。
  • Performance：声明式负载、固定 k6 编译结果、运行基线、阈值证据和质量门禁。
  • Environment Lab：管理员签名的不可变模板版本、受控 Provision、健康检查、Seed、TTL 与幂等清理。
  • Contract Hub：服务目录、不可变 Pact、Provider 验证、OpenAPI 绑定与发布兼容证据。
  • Change Impact：有界多源 Diff、显式资产映射、确定性 Test Selection、影响图与覆盖快照。
  • Runner Fabric：管理员 Worker Pool、一次性注册、身份心跳、PostgreSQL Lease/Fencing、 Drain、失联接管和可审计事件。

4. 必须前置冻结的契约

  1. 变量作用域与覆盖顺序：Global → Project → Environment → Workflow → Dataset → Runtime。
  2. Header 覆盖顺序：System → Project → Environment → Workflow → API → Runtime。
  3. Workflow JSON Schema：节点、边、条件、结构化字段映射。
  4. Execution Snapshot：工作流版本、API 版本、环境和数据集版本。
  5. 节点状态机：pending、running、passed、failed、skipped、cancelled。
  6. 错误传播、超时、重试、并发和取消语义。

5. V6 外部 Agent 与 Skill 边界

External Agent
  ├── read-only Code MCP
  ├── schema/profile-only Database MCP
  └── flowtest-generate-integration-flow Skill
            │ FlowTest MCP (stdio / Streamable HTTP)
            ▼
FlowTest Application API
  Quick: Project/Environment/API → Simple Proposal → Visual Review
  Deep:  Context Revision → Typed Evidence → Plan → Compile → Draft → Visual Review
                                                                          └→ optional Sandbox Preview
  • FlowTest Server 不作为第三方 MCP Client，不发现、不认证、不保存 Code/Database MCP 地址或凭据。
  • Skill 只编排既有 MCP Application API，不创建第二套 Planner、Compiler、Review 或 Execution 状态机。
  • 外部 MCP 输出是非可信数据，只能转换为有界、强类型、带版本与 Provenance 的 Evidence。
  • Proposal 只进入既有 AIChangeSet/WorkflowDesigner 审核事实源；Skill 不 Accept、Apply、Publish 或执行。
  • Preview 必须是 test/sandbox、一次性 Approval、固定 Revision/Budget/Cleanup；production 硬拒绝。

6. 安全基线

  • Secret 加密存储；日志和报告遵循安装级/项目级生效脱敏策略，安装级默认 OFF。OFF 不扫描、遮盖、替换或 因敏感分类阻断已有授权内容，也不扩大采集范围；显式 ON 时保留输出副本脱敏。
  • 目标 URL 执行 SSRF 校验并限制内网/元数据地址策略。
  • 请求、响应、上传、下载、超时与并发均设置上限。
  • 第一版只提供安全函数 DSL，不运行任意用户脚本。
  • 生产环境运行需要明显标识、权限控制和审计记录。
  • 生产配置拒绝示例密钥、示例管理员密码和不安全 Cookie。
  • 运行时响应只在内存中供字段映射使用；进入数据库、日志和报告时按生效策略处理，策略 OFF 不自动改写原文。
  • 环境实验室不接受用户 Compose、命令、脚本、Secret 或卷；镜像必须是管理员白名单中的精确 Digest。
  • Pact 仅接受有界 HTTP Exact Contract；拒绝 Secret、Matching Rule、Generator 和 Plugin，Provider/Broker 请求使用固定 Origin、禁止重定向并执行项目出站策略。
  • Change Impact 只接收有界 Unified Diff 或已登记 Schema 文本，不拉取外部 Git、不接收仓库凭据和 任意脚本；推荐结果只能来自项目内显式 Mapping，无证据项必须保留为 Coverage Gap。
  • Runner 注册与身份 Token 只保存哈希，生产控制面强制 HTTPS；远程 Agent 不接收用户 Compose、Shell、插件代码、宿主凭据或 Kubernetes ServiceAccount Token。
  • Runner 只恢复加密的平台 Workflow Snapshot，校验计划 SHA-256 与结果 Schema，并重新执行 项目 Host/CIDR 出站策略。过期 Fence 不能写入节点或终态。

7. 质量策略

  • 领域规则和执行引擎以单元测试为主。
  • 数据库、Redis、导入器和 HTTP 调用使用集成测试。
  • 一条稳定的示例业务流程作为端到端回归基线。
  • 工作流 Schema 与 API OpenAPI 契约进入版本控制。
  • 普通变更执行路径选择的核心门禁；最新复审清除 P0/P1 后，再显式执行 Compact、容量、镜像和恢复等 RC 重门禁。重门禁不被删除，只从每次小修中后移到发布候选检查点。

8. 运行与恢复边界

  • API、Worker 与 Beat 共享 PostgreSQL、Redis 和 MinIO，但执行引擎不依赖 Celery。
  • Performance Worker 使用独立 performance 队列和非 root、只读 k6 镜像；用户定义不能包含脚本。
  • Environment Worker 使用独立 environment 队列和非 root、只读镜像；它不挂载宿主 Docker Socket，只通过内部网络访问不对宿主暴露的独立 daemon。
  • Environment Instance 以 PostgreSQL 中的 Snapshot、签名、Fencing Token、TTL 和 Cleanup 状态为事实源； Beat Reconciler 使失败、超时、取消、到期、重投和 Runner 重启共享同一幂等清理路径。
  • Impact Run、Test Selection 与 Coverage Snapshot 以 PostgreSQL 为事实源，保存规范变更、解释边、 选择原因、Gap 和 Fingerprint；S28 不自动执行推荐测试，也不改变现有发布门禁。
  • Runner Task、Lease、递增 Fence 和 Event 以 PostgreSQL 为事实源；Pool、Runner 和 Project 容量通过分命名空间的事务 advisory lock 决策，Task 通过 SKIP LOCKED 唯一认领。
  • 远程 Runner Agent 可部署在 Docker 或 Kubernetes，每个 Token 只对应一个身份。Compose Agent 使用非 root、只读根文件系统和 Drop ALL；Kubernetes 同时禁用 ServiceAccount Token。
  • Beat Reconciler 定期处理过期 Lease 和失联 Runner；Agent 对短暂传输、429 和 5xx 保持存活， 任务由有界尝试次数和 Fence 阻止重复终态。
  • Beat 每日执行项目保留期清理；运行中执行与审计记录不会被项目清理任务删除。
  • /api/v1/metrics 暴露 HTTP 延迟/计数与持久化执行状态，不把 UUID 作为标签。
  • PostgreSQL 与 MinIO 作为一个恢复点备份；数据加密密钥必须由部署方在备份系统外安全托管。