# 优化技术架构设计（最小可运营栈 + 触发式扩容）

- 版本：v2.1
- 日期：2026-03-27
- 目标：降低 S0/S1 运维复杂度，同时保证 S2 替换目标可达。

---

## 1. 架构优化原则

1. 先跑通核心链路，再引入复杂中间件。
2. 每增加一个基础设施组件，必须有可量化触发条件。
3. 控制面集中、数据面可灰度、回滚可自动化。
4. 与主栈强一致：Go + PostgreSQL + Redis。

---

## 2. 分阶段目标架构

### 2.0 极简模式（S0/S1优先，推荐默认）

| 层 | 组件 | 说明 |
|---|---|---|
| 北向入口 | 云负载均衡（L4/L7） | 仅做 TLS 终止与基础转发 |
| 业务层 | Gateway Core（Go 单体） | 内含 Auth/RateLimit/Router/Billing/subapi connector |
| 数据层 | PostgreSQL 15 | 交易、计费、审计主存储 |
| 缓存层 | Redis 7 | 分布式限流、并发门控、短期状态 |
| 观测层 | Prometheus + 云日志（stdout） | 指标+日志最小闭环，不默认引入 Loki |
| 外部集成 | subapi（内网） | mTLS 双向认证，作为外部模块接入 |

默认不引入（极简模式）：
1. API 网关产品层（Kong/Traefik）作为必选组件。
2. Loki/ELK 独立日志平台。
3. Kafka、Istio、多集群服务治理。

极简模式退出条件（任一触发）：
1. 需要在入口层做复杂插件治理（统一 WAF/插件策略/多协议细粒度控制）。
2. 网关核心服务发布耦合导致两次以上周更失败。
3. 观测检索 SLA 无法满足（日志检索 < 1 分钟）且云日志能力不足。

### 2.1 S0/S1 最小可运营栈（必须）

| 层 | 组件 | 说明 |
|---|---|---|
| 北向入口 | 单一入口层（极简默认：云LB + Go；增强模式：Kong） | 统一鉴权、限流、协议归一 |
| 业务层 | Go 服务（模块化单体优先） | Router/Auth/Billing/Adapter 在同一部署单元 |
| 数据层 | PostgreSQL 15 | 交易、计费、审计主存储 |
| 缓存层 | Redis 7 | 限流、并发门控、短期状态 |
| 观测层 | Prometheus + Grafana（日志默认走云日志） | 指标/日志最小闭环 |
| 外部集成 | subapi（内网） | 通过 connector 接入，mTLS 双向认证 |

不引入项（S0/S1 禁止默认引入）：
1. 服务网格（Istio）。
2. Kafka 作为默认依赖。
3. ELK 全套日志平台。
4. Loki（仅在日志检索SLA不满足时引入）。

### 2.2 S2 目标架构（有条件增强）

1. Router Core 成为主路径执行引擎。
2. subapi 保留长尾协议与回退通道。
3. 按需引入异步事件总线，先从 PG outbox 开始，再评估 Kafka。

---

## 3. 触发式扩容条件（唯一准入）

| 组件 | 引入前替代方案 | 触发条件（任一满足） | 引入后验收 |
|---|---|---|---|
| Kafka | PostgreSQL Outbox + Worker | 异步事件持续 > 5k msg/s 且 backlog > 15min；或跨域消费者>=3类 | 消费延迟 P95 < 5s，消息丢失=0 |
| Istio | 网关 + 应用内 mTLS/熔断 | 服务数量 > 8 且跨服务调用路径 > 20；或多集群流量治理需求明确 | 变更可观测、故障域隔离验证通过 |
| ELK | Loki + 对象存储归档 | 日志检索需求超出 Loki 能力，且安全审计检索 SLA < 1min | 检索 SLA 达标，成本可控 |
| 服务拆分 | 模块化单体 | 单服务 CPU>70% 持续7天；发布耦合导致周更失败>=2次 | 拆分后发布失败率下降 >=50% |

---

## 4. 部署拓扑（简化且可靠）

```text
Internet
  -> Cloud LB (or Kong in enhanced mode)
    -> Gateway Core (Go)
      -> Router Core / subapi connector
        -> Providers
    -> PostgreSQL
    -> Redis
    -> Observability (Prometheus/Grafana + Cloud Logs)
```

可靠性要求：
1. 回滚：10分钟触发、30分钟恢复。
2. 灰度：5% -> 20% -> 50% -> 100%。
3. 故障域：按租户分批升波，避免全量冲击。

---

## 5. 运维简化设计

1. 单一控制面：路由、开关、灰度比例统一发布入口。
2. 单一门禁：发布必须通过唯一验收门禁表。
3. 标准 Runbook：告警 -> 判断 -> 操作 -> 验证。
4. 证据包制度：每次升波必须产出日志+指标+结论。

---

## 6. 与现有文档关系

1. 本文档替代 `technical_architecture_design_v1_2026-03-18.md` 中“默认重组件组合”的实现建议。
2. 本文档与以下文档共同构成实施基线：
   - `llm_gateway_subapi_evolution_plan_v4_2_2026-03-24.md`
   - `acceptance_gate_single_source_v1_2026-03-18.md`
   - `test_plan_go_aligned_v1_2026-03-18.md`
   - `dependency_compatibility_audit_baseline_v1_2026-03-27.md`
   - `database_domain_model_and_governance_v1_2026-03-27.md`

---

## 7. 首周落地动作

1. 冻结 S0/S1 最小栈，不引入 Istio/Kafka/ELK。
2. 默认采用极简模式（Cloud LB + Go Core），Kong/Loki按退出条件评审后引入。
3. 发布扩容触发条件评审模板（无触发条件不得引入组件）。
4. 将运维看板与门禁阈值绑定到唯一验收门禁表。
5. 完成一次“升级 + 灰度 + 自动回滚”全链路演练。

---

## 8. 依赖兼容性审计（新增强制门禁）

1. 发布前必须产出四类证据：SBOM、锁文件差异、兼容矩阵、风险清单。
2. 对 `subapi/provider SDK` 执行精确版本锁定（`X.Y.Z`），禁止“仅锁主次版本”。
3. 任一依赖发生 major 变更，必须附兼容影响评估与回滚演练记录。
4. 依赖审计结果接入门禁指标 `M-017`，要求 `dependency_compat_audit_pass_pct=100%`。
5. 运行时、数据层、构建镜像三类版本必须可追溯到同一发布包，禁止“文档版本”和“运行版本”漂移。

---

## 9. 分阶段质量检查（防偏离主线）

### 9.1 阶段门禁定义

| 阶段 | Gate | 必达条件 | 阻断动作 |
|---|---|---|---|
| G0 需求冻结 | Requirement Gate | P0/P1 需求、按钮、接口状态全部冻结 | 禁止进入开发 |
| G1 设计冻结 | Design Gate | 数据模型、OpenAPI、状态机与审计字段齐套 | 禁止进入联调 |
| G2 开发自检 | Dev Gate | 单元/契约测试通过，覆盖率达标 | 禁止合并 |
| G3 集成验证 | Integration Gate | DB/缓存/外部依赖集成测试通过 | 禁止预发布 |
| G4 发布演练 | Release Gate | 回滚演练、性能门禁、安全门禁通过 | 禁止生产发布 |
| G5 发布观察 | Post Gate | 24h 指标稳定，无 P0/P1 回归 | 冻结后续升波 |

### 9.2 防偏航机制

1. 需求追踪覆盖率（`M-019`）必须 100%，每条 P0 需求都能映射到 API/测试/指标/Gate。
2. 阶段通过率（`M-018`）必须 100%，任一阶段失败禁止“跳阶段推进”。
3. 每日执行“需求-设计-测试-门禁”一致性巡检，发现漂移 24h 内关闭。
4. 所有变更按 `request_id + trace_id` 留痕，确保故障可逆向定位到需求与提交。

---

## 10. 本版补充结论

1. 架构基线从“最小可运营栈”扩展为“最小可运营栈 + 依赖可审计 + 分阶段质量闭环”。
2. 未完成依赖兼容审计或阶段门禁的变更，不得进入 `GO` 决策。