ARCHITECTURE_OVERVIEW.md 6.6 KB
DataOps Platform 架构总览
状态基线：2026-07-18。本文只描述当前可验证事实和已确认的下一阶段目标，不把占位入口描述为已完成功能。
1. 系统边界
DataOps Platform 面向数据治理人员、数据编辑者和数据消费者，负责数据源登记、业务域/元数据/数据流治理、数据产品与订单管理，并通过 n8n 承载流程编排和执行。当前唯一后端源码是 app/，前端为 Vue 2；Vue 3 迁移安排在业务能力稳定后的独立阶段。
flowchart LR
U["管理员 / 编辑者 / 查看者"] --> FE["Vue 前端"]
FE --> API["Flask API / app/"]
API --> PG["PostgreSQL\n交易、审核、布局、映射"]
API --> DSP["外部数据源连接池\nPostgreSQL / MySQL"]
API --> NEO["Neo4j\n治理对象与血缘图"]
API --> OBJ["MinIO\n非结构化原件与附件"]
API --> N8N["n8n\nWorkflow 定义与执行"]
API --> DS["DeepSeek\n生成与问答"]
API --> QW["Qwen Embedding\n向量化"]
外部模型调用是唯一可选的非本地依赖。没有配置密钥时，本地基础设施、登录和非模型功能仍可验证，且代码不得回退到任何生产地址。
2. 容器与代码层级
flowchart TB
subgraph Browser["浏览器"]
UI["frontend/src"]
end
subgraph Runtime["应用运行时"]
NGINX["Nginx 静态资源与 /api 代理"]
ROUTES["app/api 蓝图路由"]
CORE["app/core 领域逻辑"]
SERVICES["app/services 基础服务"]
CONFIG["app/config 环境配置"]
end
subgraph Stores["本地隔离数据服务"]
POSTGRES["平台 PostgreSQL 16\n控制面与凭据密文"]
SOURCEPG["外部 PostgreSQL\n业务数据"]
SOURCEMY["外部 MySQL\n业务数据"]
NEO4J["Neo4j 5"]
MINIO["MinIO"]
N8NLOCAL["n8n 1.100.1"]
end
UI --> NGINX --> ROUTES
ROUTES --> CORE
CORE --> SERVICES
SERVICES --> CONFIG
SERVICES --> POSTGRES
CORE --> SOURCEPG
CORE --> SOURCEMY
SERVICES --> NEO4J
SERVICES --> MINIO
SERVICES --> N8NLOCAL
职责规则：
app/api/只负责协议转换、参数校验、鉴权和响应封装。app/core/承载领域用例；app/core/data_source/负责外部数据源凭据、 驱动白名单、连接池、熔断和生命周期编排。app/services/提供 PostgreSQL、Neo4j、MinIO、n8n 和模型客户端。database/是基础建库脚本源；migrations/是已启用的 Alembic 增量迁移链。deployment/app/与deployment/database/是发布镜像，不是编辑源。
3. 当前业务闭环
| 能力 | 前端入口 | 后端前缀 | 主要存储 | 当前状态 |
|---|---|---|---|---|
| 数据源 | 数据治理/数据源 | /api/datasource |
Neo4j 安全定义、PostgreSQL 凭据密文、Worker 本地连接池 | PostgreSQL/MySQL 可用 |
| 业务域 | 数据治理/业务域 | /api/bd |
Neo4j、PostgreSQL 审核表 | 可用 |
| 元数据 | 元数据详情与审核 | /api/meta |
Neo4j、PostgreSQL 审核/历史 | 可用 |
| 数据标准与标签 | 数据治理相关页面 | /api/interface |
Neo4j | 可用 |
| DataFlow 定义 | 数据流程 | /api/dataflow |
Neo4j | 可用；版本映射待实现 |
| n8n Workflow | n8n 适配页面 | /api/datafactory |
n8n | 代理可用；首次需本地 API Key |
| 数据产品/订单 | 数据服务 | /api/dataservice |
PostgreSQL、Neo4j | 可用 |
| 数据安全 | 保留入口 | 无完整接口 | 无 | 占位，不宣称实现 |
| 数据治理知识库 | 保留入口 | 待实现 | PostgreSQL/pgvector、Neo4j | 下一阶段 |
| 工作台 | 首页 | 待完善 | PostgreSQL | 验收样例；下一阶段持久化 |
当前 Flask 路由的机器可读清单和实际数量见 OPENAPI.yaml， 该文件由路由源码自动生成并由契约测试校验。
4. 外部数据源连接池边界
flowchart LR
ROUTE["数据源 API"] --> SERVICE["DataSourceService"]
SERVICE --> GRAPH["Neo4j\n无密钥连接定义"]
SERVICE --> CREDS["平台 PostgreSQL\nAES-256-GCM 凭据版本"]
USE["元数据 / 质量 / DataFlow"] --> MANAGER["Worker 本地 ConnectionManager"]
MANAGER --> REGISTRY["惰性 PoolRegistry\n2 + 3 / 数据源 / Worker"]
REGISTRY --> PGADAPTER["postgresql+psycopg2"]
REGISTRY --> MYADAPTER["mysql+pymysql"]
PGADAPTER --> EXTPG["外部 PostgreSQL"]
MYADAPTER --> EXTMYSQL["外部 MySQL"]
- 平台 PostgreSQL 是控制面数据库，沿用应用自身数据库会话，不进入该连接池注册表。
- 外部池按
数据源 UID + 凭据版本 + 配置指纹隔离；一个后端 Worker 对一个键最多创建一个 Engine。当前单实例使用 2 个 Gunicorn Worker，因此 总连接预算必须按“单池上限 × Worker 数 × 活跃数据源数”核算。 - 仅允许 PostgreSQL 和 MySQL 固定驱动；客户端不能传入驱动名、任意
connect_args或自由连接串。 - 查询用途明确区分只读与写入；只读事务回滚，写入事务只执行一次并提交， 连接失败不会自动重放写事务。
- 连续三次连接失败仅打开对应数据源的熔断器，30 秒后允许一个半开探测。 故障不会改变平台 PostgreSQL、其他数据源或其他 Worker 的状态。
- 连接定义保存在 Neo4j，但不含用户名、密码或连接串；不可变凭据版本及审计 事件保存在平台 PostgreSQL。日志、错误和管理诊断均经过脱敏。
- 配置或凭据版本变化会使旧池排空并惰性重建；空闲池 15 分钟回收，每个 Worker 默认最多保留 20 个空闲池。进程退出时统一关闭。
5. 下一阶段目标链路
flowchart LR
CHANGE["治理对象变更"] --> OUTBOX["PostgreSQL Outbox"]
OUTBOX --> INDEXER["知识库增量同步"]
INDEXER --> EMB["Qwen Embedding"]
EMB --> VECTOR["pgvector"]
VECTOR --> QA["DeepSeek 问答"]
AUDIT["每日全量一致性巡检"] --> INDEXER
DF["DataFlow 治理定义"] --> MAP["版本映射"]
MAP --> WF1["n8n Workflow v1"]
MAP --> WF2["n8n Workflow v2"]
MAP --> ACTIVE["环境级唯一生效版本"]
实施顺序、依赖和验收口径见 NEXT_ITERATION_ROADMAP.md。