|
|
@@ -0,0 +1,385 @@
|
|
|
+# 数据源连接池与凭据安全设计
|
|
|
+
|
|
|
+日期：2026-07-18
|
|
|
+状态：已完成讨论，等待书面规格审阅
|
|
|
+
|
|
|
+## 1. 目标
|
|
|
+
|
|
|
+为 DataOps 平台接入的外部业务数据源建立统一、安全、可观测的连接池框架。
|
|
|
+第一阶段走通 PostgreSQL 和 MySQL，部署边界为单台服务器、单个后端实例，
|
|
|
+并为后续多副本部署保留配置与接口扩展能力。
|
|
|
+
|
|
|
+本设计明确区分两类数据库连接：
|
|
|
+
|
|
|
+- 平台控制库：DataOps 自身使用的 PostgreSQL，保存用户、订单、流程版本、
|
|
|
+ 工作台、知识库等平台数据。继续由 Flask-SQLAlchemy 管理，不建设额外的
|
|
|
+ 数据源连接池管理层。
|
|
|
+- 业务数据源：通过 `DataSource` 定义接入的外部数据库。元数据采集、数据预览、
|
|
|
+ 质量检查和 DataFlow 执行通过本设计的连接池管理器访问。
|
|
|
+
|
|
|
+## 2. 范围
|
|
|
+
|
|
|
+### 2.1 第一阶段范围
|
|
|
+
|
|
|
+- PostgreSQL 数据源，驱动为 `postgresql+psycopg2`。
|
|
|
+- MySQL 数据源，驱动为 `mysql+pymysql`。
|
|
|
+- 按数据源延迟创建和复用连接池。
|
|
|
+- 空闲池回收、配置变更失效、删除时排空。
|
|
|
+- 数据源凭据加密保存和历史明文凭据迁移。
|
|
|
+- 故障隔离、熔断、指标和管理员诊断。
|
|
|
+- 全本地隔离 Docker 验收环境。
|
|
|
+
|
|
|
+### 2.2 暂不进入第一阶段
|
|
|
+
|
|
|
+- 多后端副本间的全局连接预算和共享状态。
|
|
|
+- PgBouncer 或其他外部连接代理。
|
|
|
+- Oracle、SQL Server、DB2、Sybase 等驱动的正式验收。
|
|
|
+- 跨实例分布式连接池、分布式锁或集中式连接代理。
|
|
|
+- 任意 SQLAlchemy driver name 和任意 `connect_args` 透传。
|
|
|
+
|
|
|
+## 3. 总体架构
|
|
|
+
|
|
|
+```text
|
|
|
+平台控制面
|
|
|
+Flask-SQLAlchemy ──> 平台 PostgreSQL
|
|
|
+仅使用框架连接管理，不进入 DataSource Pool Registry
|
|
|
+
|
|
|
+业务数据面
|
|
|
+DataSource API / 元数据采集 / 数据预览 / DataFlow
|
|
|
+ │
|
|
|
+ ▼
|
|
|
+ DataSourceConnectionManager
|
|
|
+ ├── DataSourceDefinitionRepository
|
|
|
+ ├── CredentialProvider
|
|
|
+ ├── PostgreSQLAdapter
|
|
|
+ ├── MySQLAdapter
|
|
|
+ ├── PoolRegistry
|
|
|
+ ├── CircuitBreaker
|
|
|
+ └── PoolMetrics
|
|
|
+ │
|
|
|
+ ┌─────────┴─────────┐
|
|
|
+ ▼ ▼
|
|
|
+ PostgreSQL 数据源池 MySQL 数据源池
|
|
|
+```
|
|
|
+
|
|
|
+业务模块只能通过 `DataSourceConnectionManager` 获取外部数据库连接，不得直接
|
|
|
+读取数据源密码并调用 `create_engine()`。连接测试是唯一允许创建临时 Engine 的
|
|
|
+入口，且必须使用 `NullPool` 并在完成后执行 `dispose()`。
|
|
|
+
|
|
|
+## 4. 数据源身份与连接池注册
|
|
|
+
|
|
|
+每个数据源必须具有稳定 UUID，并以 `data_source_uid` 作为业务身份。池注册键由
|
|
|
+以下内容组成：
|
|
|
+
|
|
|
+```text
|
|
|
+data_source_uid
|
|
|
+credential_version
|
|
|
+connection_config_fingerprint
|
|
|
+```
|
|
|
+
|
|
|
+连接配置指纹由数据库类型、主机、端口、数据库名、Schema 和白名单安全选项生成，
|
|
|
+不包含用户名、密码、连接 URL 或密文。
|
|
|
+
|
|
|
+连接池按需创建：
|
|
|
+
|
|
|
+- 第一次采集、预览或 DataFlow 使用时创建。
|
|
|
+- 同一 Gunicorn Worker 内，同一注册键复用一个 SQLAlchemy Engine。
|
|
|
+- 数据源定义、凭据版本或安全配置变化后，旧注册键失效。
|
|
|
+- 数据源删除后，禁止新连接借出并排空旧池。
|
|
|
+- 空闲 15 分钟的池执行回收。
|
|
|
+- 每个 Worker 默认最多缓存 20 个空闲池。
|
|
|
+- 正在执行任务的池进入 `draining`，连接归还后再释放。
|
|
|
+
|
|
|
+Gunicorn Worker 是独立进程。即使只有一个后端实例，各 Worker 仍拥有独立的
|
|
|
+Pool Registry，第一阶段不尝试跨进程共享数据库连接。
|
|
|
+
|
|
|
+## 5. 默认容量
|
|
|
+
|
|
|
+单个数据源、单个 Worker 的默认参数：
|
|
|
+
|
|
|
+```text
|
|
|
+pool_size=2
|
|
|
+max_overflow=3
|
|
|
+pool_timeout=10
|
|
|
+pool_recycle=1800
|
|
|
+pool_pre_ping=true
|
|
|
+pool_use_lifo=true
|
|
|
+```
|
|
|
+
|
|
|
+采用 4 个 Worker 时，一个持续繁忙的数据源理论最大连接数为 20，常驻连接数
|
|
|
+最大为 8。数据源可以配置受控的池大小覆盖值，但服务端必须限制上下限，不能直接
|
|
|
+接受用户提交的任意连接数量。
|
|
|
+
|
|
|
+后续多副本阶段使用以下公式重新计算单数据源连接预算：
|
|
|
+
|
|
|
+```text
|
|
|
+副本数 × Worker 数 × (pool_size + max_overflow)
|
|
|
+```
|
|
|
+
|
|
|
+## 6. 驱动适配
|
|
|
+
|
|
|
+Adapter 负责：
|
|
|
+
|
|
|
+- 校验数据源类型和连接字段。
|
|
|
+- 构建 SQLAlchemy URL。
|
|
|
+- 生成驱动专属白名单参数。
|
|
|
+- 创建 Engine。
|
|
|
+- 执行 `SELECT 1` 探测。
|
|
|
+- 将驱动异常转换为稳定的平台错误。
|
|
|
+- 提供数据库标识符引用和只读事务能力。
|
|
|
+
|
|
|
+PostgreSQL 默认启用 TCP keepalive：
|
|
|
+
|
|
|
+```text
|
|
|
+connect_timeout=5
|
|
|
+keepalives=1
|
|
|
+keepalives_idle=30
|
|
|
+keepalives_interval=10
|
|
|
+keepalives_count=3
|
|
|
+```
|
|
|
+
|
|
|
+MySQL 默认设置：
|
|
|
+
|
|
|
+```text
|
|
|
+connect_timeout=5
|
|
|
+read_timeout=30
|
|
|
+write_timeout=30
|
|
|
+charset=utf8mb4
|
|
|
+```
|
|
|
+
|
|
|
+SSL 和证书参数只能从明确白名单读取，不允许任意驱动参数透传。前端传入的
|
|
|
+`type` 必须映射到平台内部 Adapter，不能直接成为 SQLAlchemy driver name。
|
|
|
+
|
|
|
+## 7. 凭据模型
|
|
|
+
|
|
|
+平台 PostgreSQL 新增 `datasource_credentials`：
|
|
|
+
|
|
|
+```text
|
|
|
+id
|
|
|
+data_source_uid
|
|
|
+credential_version
|
|
|
+encrypted_payload
|
|
|
+nonce
|
|
|
+key_version
|
|
|
+status
|
|
|
+created_at
|
|
|
+retired_at
|
|
|
+```
|
|
|
+
|
|
|
+`encrypted_payload` 包含用户名、密码和必要的认证选项。Neo4j `DataSource` 节点
|
|
|
+只保存：
|
|
|
+
|
|
|
+```text
|
|
|
+uid
|
|
|
+type
|
|
|
+host
|
|
|
+port
|
|
|
+database
|
|
|
+schema
|
|
|
+credential_ref
|
|
|
+credential_version
|
|
|
+业务描述和治理属性
|
|
|
+```
|
|
|
+
|
|
|
+凭据使用 AES-256-GCM 加密：
|
|
|
+
|
|
|
+- 主密钥由 `DATASOURCE_CREDENTIAL_MASTER_KEY` 环境变量注入。
|
|
|
+- 每条凭据使用独立随机 nonce。
|
|
|
+- `data_source_uid + credential_version` 作为附加认证数据。
|
|
|
+- `key_version` 为后续主密钥轮换保留。
|
|
|
+- 主密钥不写入代码、数据库、镜像或日志。
|
|
|
+- 缺少主密钥或解密失败时，数据源功能失败关闭，但平台控制面仍可启动。
|
|
|
+
|
|
|
+API、日志、异常、Neo4j 查询结果和诊断接口均不得返回用户名、密码、密文、
|
|
|
+带凭据的 URL 或完整连接串。数据源列表只返回 `credential_configured` 等布尔状态。
|
|
|
+
|
|
|
+## 8. 数据源变更流程
|
|
|
+
|
|
|
+### 8.1 创建
|
|
|
+
|
|
|
+1. 校验类型，只允许 PostgreSQL 或 MySQL。
|
|
|
+2. 校验主机、端口、数据库名和安全选项。
|
|
|
+3. 使用 `NullPool` 临时 Engine 测试连接，随后关闭。
|
|
|
+4. 将凭据加密写入平台 PostgreSQL。
|
|
|
+5. 在 Neo4j 保存不含密码的数据源定义及凭据引用。
|
|
|
+6. 成功后允许 Pool Registry 按 UID 延迟创建连接池。
|
|
|
+
|
|
|
+### 8.2 修改
|
|
|
+
|
|
|
+1. 创建不可变的新凭据版本。
|
|
|
+2. 更新 Neo4j 数据源定义和 `credential_version`。
|
|
|
+3. 将旧连接池标记为 `draining`。
|
|
|
+4. 后续请求使用新注册键创建连接池。
|
|
|
+5. 旧凭据标记为 `retired`。
|
|
|
+
|
|
|
+修改失败时，数据源继续引用原有有效版本。PostgreSQL 与 Neo4j 之间使用现有
|
|
|
+Outbox 和补偿巡检实现最终一致性。
|
|
|
+
|
|
|
+### 8.3 删除
|
|
|
+
|
|
|
+1. 禁止新连接借出。
|
|
|
+2. 等待已借出连接在限定时间内归还。
|
|
|
+3. 到期后强制释放 Engine。
|
|
|
+4. 删除或归档 Neo4j 数据源定义。
|
|
|
+5. 将凭据标记为 `revoked`。
|
|
|
+6. 记录不含敏感数据的审计事件。
|
|
|
+
|
|
|
+## 9. 连接获取接口
|
|
|
+
|
|
|
+业务模块使用统一的上下文接口：
|
|
|
+
|
|
|
+```python
|
|
|
+with data_source_manager.connect(
|
|
|
+ data_source_uid,
|
|
|
+ purpose="metadata_preview",
|
|
|
+) as connection:
|
|
|
+ ...
|
|
|
+```
|
|
|
+
|
|
|
+管理器依次完成定义读取、凭据获取、Adapter 选择、池注册、连接借出和归还。
|
|
|
+业务模块不持有 Engine，不负责连接池配置，也不能访问凭据明文。
|
|
|
+
|
|
|
+`purpose` 使用平台枚举，第一阶段至少包括：
|
|
|
+
|
|
|
+- `connection_test`
|
|
|
+- `metadata_collection`
|
|
|
+- `metadata_preview`
|
|
|
+- `quality_check`
|
|
|
+- `dataflow_read`
|
|
|
+- `dataflow_write`
|
|
|
+
|
|
|
+除 `dataflow_write` 外默认使用只读事务。写入任务必须显式提交，异常时回滚。
|
|
|
+
|
|
|
+## 10. 故障隔离与熔断
|
|
|
+
|
|
|
+每个数据源独立维护状态：
|
|
|
+
|
|
|
+```text
|
|
|
+healthy
|
|
|
+degraded
|
|
|
+open
|
|
|
+draining
|
|
|
+closed
|
|
|
+```
|
|
|
+
|
|
|
+- 单个数据源连接耗尽或宕机，不影响平台控制库和其他数据源。
|
|
|
+- 连续 3 次建连失败后熔断 30 秒。
|
|
|
+- 熔断结束后只允许一个半开放探测请求。
|
|
|
+- 探测成功恢复 `healthy`，失败继续熔断。
|
|
|
+- 借出等待超过 10 秒返回 `DATASOURCE_POOL_TIMEOUT`。
|
|
|
+- 事务中断必须回滚，不自动重放数据源写操作。
|
|
|
+- 失效连接不再返回池中。
|
|
|
+
|
|
|
+主要稳定错误码：
|
|
|
+
|
|
|
+- `DATASOURCE_NOT_FOUND`
|
|
|
+- `DATASOURCE_TYPE_UNSUPPORTED`
|
|
|
+- `DATASOURCE_CREDENTIAL_UNAVAILABLE`
|
|
|
+- `DATASOURCE_CONNECTION_FAILED`
|
|
|
+- `DATASOURCE_POOL_TIMEOUT`
|
|
|
+- `DATASOURCE_CIRCUIT_OPEN`
|
|
|
+- `DATASOURCE_QUERY_TIMEOUT`
|
|
|
+- `DATASOURCE_READ_ONLY_VIOLATION`
|
|
|
+
|
|
|
+错误响应不包含驱动原始连接 URL 或凭据。
|
|
|
+
|
|
|
+## 11. 监控与管理
|
|
|
+
|
|
|
+管理员可以查看单个数据源的池摘要：
|
|
|
+
|
|
|
+```text
|
|
|
+data_source_uid
|
|
|
+database_type
|
|
|
+pool_state
|
|
|
+pool_size
|
|
|
+checked_out
|
|
|
+checked_in
|
|
|
+overflow
|
|
|
+checkout_wait_ms
|
|
|
+last_used_at
|
|
|
+consecutive_failures
|
|
|
+circuit_open_until
|
|
|
+credential_version
|
|
|
+```
|
|
|
+
|
|
|
+平台健康检查仅返回聚合数据：
|
|
|
+
|
|
|
+```text
|
|
|
+active_pool_count
|
|
|
+degraded_pool_count
|
|
|
+open_circuit_count
|
|
|
+checked_out_total
|
|
|
+pool_timeout_total
|
|
|
+```
|
|
|
+
|
|
|
+指标至少覆盖：
|
|
|
+
|
|
|
+- 连接创建成功和失败次数。
|
|
|
+- Checkout 等待时间。
|
|
|
+- 当前占用、空闲和溢出连接数。
|
|
|
+- 池超时、连接失效和重建次数。
|
|
|
+- 查询耗时。
|
|
|
+- 空闲池回收次数。
|
|
|
+- 凭据版本导致的池重建次数。
|
|
|
+
|
|
|
+所有日志使用数据源 UID 和错误分类；异常文本在写日志前统一脱敏。
|
|
|
+
|
|
|
+## 12. 历史凭据迁移
|
|
|
+
|
|
|
+迁移必须分两步：
|
|
|
+
|
|
|
+1. 只读报告：统计含明文凭据、缺少 UID 或配置不完整的数据源，只输出 UID 和问题
|
|
|
+ 分类。
|
|
|
+2. 显式迁移：补齐 UID、加密凭据、写入凭据引用、验证可解密后删除 Neo4j 明文字段。
|
|
|
+
|
|
|
+生产执行前必须单独备份 Neo4j 和平台 PostgreSQL。迁移过程不得在日志、报告或
|
|
|
+异常中输出明文密码。迁移失败的数据源保持原状态并进入人工核查清单。
|
|
|
+
|
|
|
+现有数据源保存、验证和连接测试接口必须先完成请求日志脱敏。数据源列表接口必须
|
|
|
+在凭据迁移前就停止返回密码。
|
|
|
+
|
|
|
+## 13. 本地隔离验收
|
|
|
+
|
|
|
+Docker 测试栈新增两个业务数据源服务：
|
|
|
+
|
|
|
+```text
|
|
|
+platform-postgres 平台控制库
|
|
|
+source-postgres PostgreSQL 验收数据源
|
|
|
+source-mysql MySQL 验收数据源
|
|
|
+```
|
|
|
+
|
|
|
+验收标准：
|
|
|
+
|
|
|
+1. PostgreSQL、MySQL 均可保存、测试、建池和执行查询。
|
|
|
+2. 同一数据源并发请求复用连接且不超过池上限。
|
|
|
+3. 50–100 个并发请求下无连接泄漏。
|
|
|
+4. 配置或密码修改后旧池失效，新池使用新版本。
|
|
|
+5. 空闲池到期释放，再次访问可重建。
|
|
|
+6. MySQL 停机不影响 PostgreSQL 数据源和平台功能。
|
|
|
+7. 数据源恢复后可通过半开放探测恢复。
|
|
|
+8. 删除数据源后连接池和凭据不可继续使用。
|
|
|
+9. API、日志、Neo4j 和异常中不存在明文密码。
|
|
|
+10. 后端重启后连接池按需重建。
|
|
|
+
|
|
|
+测试包括：
|
|
|
+
|
|
|
+- AES-GCM 加密、篡改检测和密钥版本测试。
|
|
|
+- PostgreSQL、MySQL Adapter 合约测试。
|
|
|
+- Pool Registry 并发、回收和失效测试。
|
|
|
+- 熔断状态机测试。
|
|
|
+- 历史明文凭据迁移测试。
|
|
|
+- Docker 数据源宕机和恢复测试。
|
|
|
+- 前后端数据源管理接口验收。
|
|
|
+
|
|
|
+## 14. 后续扩展
|
|
|
+
|
|
|
+进入多副本阶段后再评估：
|
|
|
+
|
|
|
+- 按副本数重新计算连接预算。
|
|
|
+- PgBouncer。
|
|
|
+- 跨实例池状态聚合。
|
|
|
+- 数据源任务按 UID 路由。
|
|
|
+- Oracle、SQL Server 等额外 Adapter。
|
|
|
+
|
|
|
+第一阶段的 Adapter、CredentialProvider、Pool Registry 和指标接口保持稳定，
|
|
|
+多副本阶段不改变业务模块的连接获取接口。
|
马小龙