62 lines
2.7 KiB
Markdown
62 lines
2.7 KiB
Markdown
# 架构决策记录
|
||
|
||
## ADR-001：控制面与数据面分离
|
||
|
||
**状态：** 接受。
|
||
|
||
Gateway 只依赖本地不可变 Snapshot；Provider、数据库、配置重载和健康聚合
|
||
位于 Controller/Checker。该选择隔离外部 I/O 抖动，并允许数据面按 QPS、
|
||
控制面按 Provider/库存规模独立扩容。
|
||
|
||
## ADR-002：Distribution 使用独占提取
|
||
|
||
**状态：** 接受并覆盖早期 Lease 方案。
|
||
|
||
成功响应前，通过 Redis 原子操作完成候选选择、`AVAILABLE -> EXTRACTED` 和
|
||
短期幂等结果写入；不提供 release、renew 或使用跟踪。这样契合“拿走真实
|
||
代理后平台不再管理”的最终产品语义，并消除并发重复发放。
|
||
|
||
## ADR-003：单 Worker 所有权
|
||
|
||
**状态：** 接受。
|
||
|
||
一个 Proxy 同一时刻至多归属一个 Worker，Gateway 在本地维护 Active/Reserved。
|
||
Distribution 只提取无所有权 Proxy；回收时执行 drain/ACK/归零/解除所有权。
|
||
该选择避免每请求访问 Redis 做全局并发计数。
|
||
|
||
## ADR-004：PostgreSQL 保存控制面事实，Redis 承载短效活动池
|
||
|
||
**状态：** 接受。
|
||
|
||
Proxy 明细不进入 PostgreSQL。短效 Proxy 及其状态、所有权和过期时间只存在于
|
||
带 TTL 的 Redis 活动池及节点内存；Redis 同时承担独占提取、短期幂等结果、
|
||
Provider Leader、分布式速率和 Worker 心跳。Redis 丢失时活动池作废，由
|
||
Provider 重新获取并重建，不从 PostgreSQL 恢复原 Proxy。
|
||
|
||
PostgreSQL 只持久化配置版本、Upstream/Routing 管理状态、Admin 审计与 Outbox，
|
||
以及可选的无 Proxy 明细聚合指标。两类存储不双写 Proxy，也不建立跨存储事务。
|
||
|
||
## ADR-005：Redis 活动池采用单实例原子深模块
|
||
|
||
**状态：** 接受并已实现。
|
||
|
||
首版 Redis 活动池部署在单实例或 Sentinel 主节点，通过一个深 Adapter 统一实现
|
||
Provider 入池、健康状态、Distribution 独占提取、Worker 所有权、库存读取和
|
||
有界过期清理。所有键使用固定 hash tag，为未来 Redis Cluster 单槽迁移保留
|
||
兼容性，但首版不引入跨分片事务。
|
||
|
||
完整决策、键空间、原子操作和测试门禁见
|
||
[ADR-005](005-redis-activity-pool.md)。
|
||
|
||
## ADR-006：PostgreSQL 管理面采用事务深模块
|
||
|
||
**状态：** 接受。
|
||
|
||
Upstream/Routing/配置修订、Admin 审计和 Outbox 由一个深 Adapter 在同一事务
|
||
提交。调用方只依赖 mutation、snapshot 和有界 outbox 接口，不接触数据库事务
|
||
或细粒度 Repository。PostgreSQL Schema 明确排除 Proxy、Worker ownership、
|
||
逐次提取记录和短期幂等结果。
|
||
|
||
完整接口、事务不变量、Schema 与公用契约见
|
||
[ADR-006](006-postgresql-admin-state.md)。
|