背景、目标与设计边界

说明为什么要建设统一入口、它要解决哪些业务问题，以及哪些职责不由网关承担。

1. 依据与结论

1.1 输入材料

本设计以正式会议摘要 正式会议摘要文件 作为已确认记录，以逐字稿 会议逐字稿文件 作为上下文佐证。逐字稿包含低置信度片段、重复语句和说话人识别误差，不能单独用于确认高风险架构事实。

1. 会议逐字稿文件
2. 正式会议摘要文件

当前仓库 当前仓库 尚无业务代码或既有架构文档，因此本文中的技术选型、性能目标和运维指标均属于建议设计，不代表现网事实。

1.2 已确认业务决策

1. API Gateway 是多个支付平台的统一入口，不是 Zero Confirmation 的专用入口。
2. 首批纳入的平台包括 WebPay Inbox、BPS 和 Zero Confirmation，未来还需接入其他支付平台。
3. API Key 必须表达它可访问的平台、服务和操作权限。
4. 一个商户可以拥有多个 API Key，也可以使用多个来源 IP。
5. API Key 与来源 IP 必须建立显式绑定；未绑定的 Key 与 IP 组合必须拒绝。
6. 系统必须支持多个地域、多个网关实例和后端多数据库场景，并提供冗余与路由能力。
7. Zero Confirmation 的多地域设计经验未来需要复用于 BPS。

1.3 设计结论

建议采用“全局统一控制面、区域自治数据面”的架构：

• 控制面统一管理商户、API Key、密钥版本、IP 绑定、权限范围、路由和审计。
• 每个地域部署无状态网关数据面与本地域配置快照及限流缓存，请求不依赖跨地域同步数据库查询。
• API Key 授权采用默认拒绝模型，并同时满足商户归属、环境、Key 状态、Key 与 IP 绑定、路由所需权限五项条件。
• 网关只负责认证、授权、流量治理和确定性路由，不负责在 BPS 或 Zero Confirmation 的业务数据库之间做双写。
• 支付写请求的跨地域故障转移必须以端到端幂等和后端数据一致性为前提，不能仅靠网关重试解决。

2. 目标与非目标

2.1 目标

1. 为所有商户 API 提供统一的公网或专线入口。
2. 用一套平台无关的授权模型管理多平台、多服务和多操作权限。
3. 精确校验 API Key 与来源 IP 的组合，防止同一商户的多个 Key 和多个 IP 被错误混用。
4. 支持 Key 创建、轮换、吊销、过期、权限变更和 IP 变更的完整生命周期。
5. 支持区域内横向扩展和多地域部署，单个网关实例或单个地域故障时具备明确的降级与恢复行为。
6. 为安全审计、故障排查、容量规划和 SLO 提供完整可观测性。
7. 允许未来支付平台通过配置和标准接入流程接入，而不修改核心认证逻辑。

2.2 非目标

1. 不在网关内实现 WebPay Inbox、BPS 或 Zero Confirmation 的业务逻辑。
2. 不由网关负责平台业务数据库复制、跨库事务或账务一致性。
3. 不允许网关自动把一个地域的支付写请求盲目重放到另一个地域。
4. 不把 API Key 当作商户后台用户登录凭据；后台人员应使用独立的身份系统和强认证。
5. 本阶段不设计商户计费系统，但会产出可供计费使用的用量事件。

3. 核心原则

1. 默认拒绝：任何缺失、未知、过期、吊销或未明确授权的请求都拒绝。
2. 显式绑定：权限和 IP 都直接绑定到具体 API Key，不从商户级配置隐式继承。
3. 控制面与数据面分离：管理变更可以短时不可用，但存量数据面应继续处理已知且有效的请求。
4. 区域自治：请求热路径只访问本地域组件，不依赖跨地域数据库。
5. 后端拥有数据一致性：网关只根据已发布的路由策略选定一个后端，不参与业务双写。
6. 机密最小暴露：API Secret 只在创建时展示一次，服务端只保存不可逆摘要。
7. 全链路可审计：所有控制面变更和数据面授权决策都可追溯，但日志不得记录原始 Secret、支付敏感字段或完整请求体。