add aodb detailed planning artifacts and adrs

2026-04-13 16:12:54 +08:00
parent 973c745762
commit 66d081faaf
15 changed files with 1069 additions and 0 deletions
@@ -0,0 +1,176 @@
+# AODB 最小部署拓扑草案
+
+## 1. 文档定位
+
+本文档给出 AODB MVP 的最小部署拓扑、关键高可用策略和恢复思路，用于支撑高层设计中的 SLO 和上线门禁。
+
+## 2. 目标
+
+- 以单机场私有化部署为前提
+- 优先满足当前态统一、事件不丢、审计可回放
+- 用最少组件完成可恢复、可观测、可演练的运行形态
+
+## 3. 逻辑拓扑
+
+```text
+             +-------------------------+
+             |    External Systems     |
+             | SSIM / AIDX / AFTN      |
+             +------------+------------+
+                          |
+                          v
+                +-------------------+
+                |   Kong Gateway    |
+                +-------------------+
+                          |
+          +---------------+----------------+
+          |               |                |
+          v               v                v
+ +----------------+ +----------------+ +------------------+
+ | Flight Service  | | Milestone Svc | | External API Svc |
+ +----------------+ +----------------+ +------------------+
+          |               |                |
+          +-------+-------+----------------+
+                  |
+                  v
+          +----------------------+
+          | PostgreSQL/Timescale |
+          | Current + Audit +    |
+          | Outbox               |
+          +----------+-----------+
+                     |
+                     v
+             +---------------+
+             | CDC/Publisher |
+             +-------+-------+
+                     |
+                     v
+                 +-------+
+                 | Kafka |
+                 +---+---+
+                     |
+          +----------+-----------+
+          |                      |
+          v                      v
+ +----------------+      +----------------+
+ | Resource Svc   |      | Alert Service  |
+ +----------------+      +----------------+
+
+ +----------------+
+ | Redis Cache    |
+ +----------------+
+
+ +-------------------------------+
+ | Prometheus / Grafana / Loki   |
+ +-------------------------------+
+```
+
+## 4. 部署分区建议
+
+### 4.1 状态层
+
+- PostgreSQL / TimescaleDB
+- Kafka
+- Redis
+
+要求：
+
+- 与无状态服务分离部署
+- 具备独立备份和恢复策略
+
+### 4.2 无状态业务层
+
+- Flight Operation Service
+- Milestone Service
+- Resource Service
+- Alert Service
+- External API Service
+- CDC / Publisher
+
+要求：
+
+- 多副本
+- 滚动升级
+- 配置和密钥外置
+
+### 4.3 平台观测层
+
+- Kong
+- Keycloak
+- Prometheus
+- Grafana
+- Loki
+
+## 5. 高可用建议
+
+### 5.1 PostgreSQL / TimescaleDB
+
+- 主备部署
+- 定期全量备份 + WAL / PITR 能力
+- 演练主备切换
+
+### 5.2 Kafka
+
+- 多 broker
+- `replication factor >= 3`
+- `min ISR >= 2`
+- 消费位点外部可追踪
+
+### 5.3 Redis
+
+- 主从或哨兵
+- 缓存失效不应影响核心写链路
+
+### 5.4 无状态服务
+
+- 至少 2 副本
+- 健康检查 + 自动重启
+- 发布器必须支持重复执行幂等
+
+## 6. 最小恢复策略
+
+### 6.1 数据库故障
+
+- 切换到备实例
+- 根据最近备份和 WAL 进行恢复
+- 恢复后执行 Published Fact 与 Outbox 对账
+
+### 6.2 Kafka 堆积或单 broker 故障
+
+- Broker 恢复后消费者追赶
+- 重点检查订阅延迟、DLQ 率、CDC 积压
+
+### 6.3 CDC / Publisher 中断
+
+- 根据 Outbox 位点断点续传
+- 保证重复发布不产生重复副作用
+
+### 6.4 查询层异常
+
+- 核心写链路不中断
+- 对外查询可降级，但订阅恢复后必须可补偿
+
+## 7. 关键观测指标
+
+| 指标 | 含义 |
+| --- | --- |
+| ingest_to_publish_latency_p95 | 接入到发布的 P95 延迟 |
+| outbox_backlog | Outbox 堆积量 |
+| cdc_publish_retry_count | 发布重试次数 |
+| kafka_consumer_lag | 消费滞后量 |
+| dlq_rate | 解析失败和旁路率 |
+| conflict_mttr | 冲突平均处置时间 |
+| review_task_open_count | 未关闭复核任务数 |
+
+## 8. 上线前必须演练
+
+1. PostgreSQL 主备切换
+2. Kafka 单 broker 故障恢复
+3. CDC 中断和断点恢复
+4. 订阅端断线重连与游标补偿
+5. 关键字段回放抽检
+
+## 9. 与高层设计的关系
+
+- 本文档细化 `开源机场运营数据库（AODB）高层设计文档.md` 中的部署与 SLO 章节。
+- 它不是最终部署手册，但必须足以支撑架构评审和上线门禁定义。