说明配置事实源、管理接口、本地域快照、紧急封禁和缓存一致性的责任边界。
8. 数据模型
建议控制面使用以下关系模型。所有主键使用 UUID，所有时间使用 UTC，并在展示层转换时区。
| 表 | 关键字段 | 关键约束 |
|---|---|---|
merchants | id、external_ref、name、status、created_at | external_ref 全局唯一 |
api_keys | id、merchant_id、public_key_id、environment、status、not_before、expires_at、created_at | public_key_id 全局唯一；商户外键不可空 |
api_key_secret_versions | id、api_key_id、secret_digest、pepper_version、version、status、valid_from、valid_until | 每个 Key 的 version 唯一；不保存明文 Secret；Pepper 版本外键不可空 |
api_key_signing_keys | id、api_key_id、algorithm、public_key、status、valid_from、valid_until | 只允许批准的非对称算法；不接收私钥 |
api_key_client_certificates | id、api_key_id、certificate_fingerprint、issuer_ref、status、valid_from、valid_until | 指纹与 Key 的绑定唯一；证书链必须来自批准的发行者 |
api_key_ip_bindings | id、api_key_id、ip_network、status、created_at | 同一 Key 下规范化后的 ip_network 唯一；禁止重叠；执行第 5.3 节前缀限制 |
scopes | id、scope_name、platform、resource、action、status | scope_name 全局唯一 |
api_key_scopes | api_key_id、scope_id、granted_at、granted_by | Key 与 Scope 联合唯一 |
routes | id、route_name、environment、platform、method、path_rule、required_scope_id、service_capability_id、request_class、policy_version、status | 数据库 CHECK 保证已发布路由具有 required scope、环境和服务能力声明 |
merchant_region_policies | merchant_id、environment、primary_region、allowed_regions、failover_mode、version | 每个商户和环境只有一条有效策略 |
service_capabilities | id、service_name、environment、read_consistency、max_replication_lag_ms、signal_max_age_seconds、supports_global_idempotency、automatic_read_failover、automatic_write_failover | 每个服务与环境只有一条有效能力声明；能力提升需要审批 |
service_endpoints | id、service_name、environment、region、endpoint_ref、health_policy、status | 服务、环境、地域和端点引用联合唯一 |
control_plane_epochs | epoch、writer_region、lease_id、activated_at、fenced_previous_writer_at | 只追加；接管前必须记录旧主围栏证据 |
config_outbox | id、aggregate_type、aggregate_id、config_epoch、config_sequence、event_type、payload、published_at | 事件 ID 唯一；与配置写入同一事务；版本按 epoch 与 sequence 比较 |
admin_audit_logs | id、actor_id、action、resource_type、resource_id、before_digest、after_digest、reason、created_at | 只追加，不允许更新和删除 |
IP 建议使用 PostgreSQL inet 类型。secret_digest、审计差异和 Outbox 载荷均需列级加密或磁盘加密；任何载荷都不得包含明文 Secret。
9. 管理接口
管理接口只允许从内部管理网络访问，并使用公司身份系统的短期访问令牌。建议提供以下固定资源接口：
| 方法与路径 | 用途 | 关键输入 |
|---|---|---|
POST /admin/v1/api-keys | 创建 Key | merchant_id、environment、scopes、ip_bindings、expires_at、reason |
GET /admin/v1/api-keys | 按商户、状态或环境查询 Key 元数据 | 查询条件，不返回 Secret 或摘要 |
POST /admin/v1/api-key-rotations | 创建新 Secret 版本 | api_key_id、overlap_hours、reason |
POST /admin/v1/api-key-signing-keys | 注册商户请求签名公钥 | api_key_id、algorithm、public_key、valid_until、reason |
POST /admin/v1/api-key-client-certificates | 绑定 mTLS 客户端证书 | api_key_id、certificate_fingerprint、issuer_ref、valid_until、reason |
POST /admin/v1/api-key-suspensions | 暂停 Key | api_key_id、reason |
POST /admin/v1/api-key-revocations | 永久吊销 Key | api_key_id、reason |
PUT /admin/v1/api-key-ip-bindings | 原子替换一个 Key 的 IP 绑定集合 | api_key_id、ip_bindings、expected_version、reason |
PUT /admin/v1/api-key-scopes | 原子替换一个 Key 的 Scope 集合 | api_key_id、scopes、expected_version、reason |
POST /admin/v1/routes/validations | 校验待发布路由配置 | 完整路由配置和目标版本 |
POST /admin/v1/route-publications | 发布已校验的路由版本 | route_id、expected_version、reason |
所有写接口必须支持幂等请求标识、乐观锁版本和操作原因。原子替换 IP 或 Scope 的响应必须返回替换前集合摘要和新版本号，供误操作审计与受控回滚使用。Secret 创建响应禁止被反向代理、APM 或审计中间件记录。
高风险操作包括生产 Key 创建、Scope 提权、扩大 IP 网段、允许跨地域写入和吊销恢复策略变更，建议要求双人审批。
10. 缓存与配置一致性
10.1 配置发布与运营中心
配置发布与运营中心有两条彼此独立的路径。普通变更走单写控制面、PostgreSQL 和 Outbox；紧急只拒绝路径使用不同网络、身份角色和硬件保护签名，在普通控制面不可用时仍可收缩访问。不可篡改审计写入属于本边界，可观测性中心只读取和关联这些记录。
%%{init: {"flowchart": {"curve": "linear", "nodeSpacing": 34, "rankSpacing": 38, "htmlLabels": true}}}%%
flowchart TB
subgraph STANDARD["普通配置发布 · 统一控制面单写"]
direction TB
ADMIN["内部管理后台 / 自动化系统"] --> ADMIN_API["Gateway Admin API<br/>内部身份 · 最小权限 · 双人审批"]
ADMIN_API --> VALIDATE["配置不变量校验<br/>乐观锁 · 单写租约 · 旧主围栏"]
VALIDATE --> TX["PostgreSQL 事实源<br/>同一事务写配置、审计与 Outbox<br/>(epoch, sequence)"]
TX --> AUDIT["不可篡改审计存储<br/>操作者 · 审批 · 原因 · 变更摘要"]
TX --> OUTBOX["事务 Outbox 与消息总线<br/>幂等发布 · 重放 · 版本对账"]
OUTBOX --> ROUTE_SNAPSHOT["路由策略快照<br/>供流量路由策略中心"]
OUTBOX --> ACCESS_SNAPSHOT["Key · IP · Scope 快照<br/>供访问控制中心"]
OUTBOX --> GOVERN_SNAPSHOT["路由治理快照<br/>供请求治理与执行层"]
end
subgraph EMERGENCY["紧急只拒绝 · 独立安全通道"]
direction LR
SECURITY["安全事件指挥<br/>独立身份角色"] --> SIGNED["硬件签名拒绝指令<br/>只追加 Key / 商户 / IP 拒绝项"]
SIGNED --> REGIONAL_DENY["各地域访问控制中心<br/>验签后与中央配置取并集"]
SIGNED --> LOCAL_AUDIT["本地只追加审计副本<br/>恢复后归档到正式记录"]
end
classDef external fill:#F7F9FC,stroke:#8A9AAF,color:#18212F,stroke-width:1.5px
classDef control fill:#F2F0FF,stroke:#6657C7,color:#292057,stroke-width:1.5px
classDef output fill:#FFFFFF,stroke:#4F79A7,color:#18212F,stroke-width:1.5px
classDef emergency fill:#FFF2EC,stroke:#C7582B,color:#6B2812,stroke-width:1.5px
class ADMIN,SECURITY external
class ADMIN_API,VALIDATE,TX,OUTBOX,AUDIT control
class ROUTE_SNAPSHOT,ACCESS_SNAPSHOT,GOVERN_SNAPSHOT output
class SIGNED,REGIONAL_DENY,LOCAL_AUDIT emergency
style STANDARD fill:#FAF9FF,stroke:#C9C0F1,stroke-width:2px
style EMERGENCY fill:#FFFAF7,stroke:#E8B69F,stroke-width:2px
普通发布流程如下：
- 控制面在同一 PostgreSQL 事务中更新配置和写入 Outbox 事件。
- 发布器把事件发送到消息总线，事件包含
(epoch, sequence)配置版本。 - 各地域消费者幂等应用事件，先比较
epoch再比较sequence，拒绝旧版本覆盖新版本。 - 各地域的 API Key 验证服务维护 Redis 快照和进程内短缓存。
- 每个地域周期性执行全量版本对账，发现缺口后从事实源重建快照。
10.2 吊销优先级
吊销、暂停和 IP 移除属于安全事件，必须走高优先级通道，并向所有地域推送失效通知。建议目标为 99.9% 的安全变更在 10 秒内生效。
如果消息总线异常，各地域使用短周期版本轮询补偿。对于无法确认状态的新 Key 或未缓存 Key，数据面必须拒绝；不得为了可用性绕过授权。
10.3 紧急只拒绝通道
控制面或 PostgreSQL 不可用时，安全人员仍必须能够立即阻止泄露的 Key。每个地域提供独立的 break-glass 紧急封禁入口，并遵守以下约束：
- 入口仅允许新增对公开 Key ID、商户 ID 或来源 IP 的拒绝项，不能新增允许项、扩大权限或删除中央吊销记录。
- 指令使用硬件保护的内部安全签名密钥签名，各地域的 API Key 验证服务先验签再把拒绝项与中央配置做并集。
- 正常情况下需要两名授权安全人员审批；已声明的最高级安全事件允许事件指挥官先执行，第二名审批人必须在 15 分钟内复核。
- 地域本地拒绝项的初始租期为 24 小时。控制面仍不可用时，安全人员可以通过相同签名与审批流程续期；API Key 验证服务在距离到期 2 小时和 1 小时告警，且在控制面不可用、拒绝项尚未正式归档时不得因租期到期自动恢复允许。控制面恢复后必须转为正式暂停或吊销记录，未完成归档前不得提前删除。
- 每个地域把操作人、审批人、原因、签名摘要、接收时间和生效时间写入本地只追加审计存储。
- break-glass 入口与普通 Gateway Admin API 使用不同网络路径、身份角色和签名密钥，季度演练一次。
10.4 降级策略
| 故障 | 行为 |
|---|---|
| PostgreSQL 控制面主库不可用 | 普通管理写入停止；数据面使用最后一次已验证快照继续服务；紧急封禁使用第 10.3 节通道 |
| 消息总线不可用 | 控制面提交配置但标记为待发布；区域通过版本轮询补偿；发布完成前不宣告变更生效 |
| 地域 Redis 不可用 | API Key 验证服务使用有界的进程内快照；未知 Key 和超过快照有效期的 Key 拒绝；分布式限流降级为实例本地令牌桶，实例只能使用故障前已租用且未过期的配额份额，新实例配额为零，因此全部实例份额之和不得超过该商户或 Key 的全局配额 |
| API Key 验证服务不可用 | 网关认证失败关闭，返回 503，不绕过权限校验 |
| 单个后端实例不可用 | 健康检查摘除并在同一服务池选择健康实例 |
| 整个后端地域不可用 | 按第 7.3 节的读取与写入前提决定故障转移或返回 503 |
最后一次已验证快照的最大离线使用时间建议为 15 分钟。超过该时间仍无法取得新版本时，应拒绝高风险写请求；读取请求是否继续需要由各平台按风险分级确认。