2026-08-20 09:10:34 +08:00
|
|
|
# 跨区域认证与服务通信契约
|
|
|
|
|
|
|
|
|
|
## 适用范围
|
|
|
|
|
|
|
|
|
|
- 本契约适用于 Admin、Client、国内头程服务、海外网关、尾程服务、海外仓资源服务及跨区域事件桥接。
|
|
|
|
|
- 业务范围仍按对应阶段和模块文档确定；本文件只冻结跨区域账号、请求路由、服务鉴权和事件通信边界。
|
2026-08-20 19:55:24 +08:00
|
|
|
- 开发/测试同机共置及生产国内/海外双控制面的实际部署拓扑、Nacos、数据库和 Event Bridge 规划见[双区域部署与 Nacos 规划](双区域部署与Nacos规划.md)。
|
2026-08-20 09:10:34 +08:00
|
|
|
|
|
|
|
|
## 统一账号与 Token
|
|
|
|
|
|
|
|
|
|
- Admin、Client 只维护一套前端和一套用户账号体系；用户登录和 Token 签发统一归国内头程 Auth，不得为海外仓再创建独立登录、账号或权限体系。
|
|
|
|
|
- 统一使用 RS256/JWKS 信任链，但区分 Token 用途：国内登录/刷新时由同一 Auth 同时签发国内 Token 和短时海外 Token；海外 Token 限定海外 Audience，并携带海外 API 所需身份、客户范围和权限快照。
|
|
|
|
|
- 用户只登录一次，由前端统一认证模块按目标 API 自动选择 Token，不在页面或业务模块中分叉登录逻辑。
|
|
|
|
|
- JWKS 只暴露公钥验证能力，不暴露私钥；国内服务验证登录 Token 并结合 Redis 会话实现即时退出和权限变更，海外服务不访问国内 Redis，只验证海外访问 Token 的签名、Issuer、Audience、有效期、应用域、客户范围和权限 Claims。
|
|
|
|
|
|
|
|
|
|
## 区域 API 路由
|
|
|
|
|
|
|
|
|
|
- 一套前端使用国内、海外两个区域 API Base：国内业务直连 `gateway/`，海外仓业务直连 `gateway-overseas/`，再由海外网关路由到 `lastleg-service/`、`warehouse-overseas-service/` 和海外部署的公共服务。
|
|
|
|
|
- 日常海外请求不得经国内 Gateway 中转。区域地址、Token 选择和刷新由环境配置与统一 API/认证层处理，业务页面不得感知部署区域差异。
|
|
|
|
|
- 海外浏览器请求的具体 Audience、Claim 和路由以前端项目、`auth/`、`gateway-overseas/` 最近的 `AGENTS.md` 与实际配置为准；修改其中任一项时必须联查全部生产者和消费者。
|
|
|
|
|
|
|
|
|
|
## 跨区域事件与服务身份
|
|
|
|
|
|
|
|
|
|
- 头程与海外仓的数据流转使用 MQ 的 Outbox → Inbox、事件幂等、重试和死信机制。
|
|
|
|
|
- 事件使用版本化信封、事件 ID、业务键、来源/目标区域和 Payload 哈希，不携带用户 Access Token。
|
|
|
|
|
- 费用由海外仓发布事件，头程 Finance 消费并按来源快照入账；财务状态机和结算口径仍由财务契约冻结，海外服务不得自行定义。
|
|
|
|
|
- MQ 使用独立的服务身份、TLS 和 ACL；服务间事件鉴权与用户 JWT 鉴权分开。只有明确的同步 HTTP 内部接口才使用内部服务令牌。
|
|
|
|
|
- 修改事件时联查 `common-event-contract/`、`event-bridge-service/`、生产服务、消费服务、幂等记录、重试/死信和契约测试。
|
|
|
|
|
|
|
|
|
|
## 修改与验收
|
|
|
|
|
|
|
|
|
|
- Token、Audience、Claim、JWKS、API Base 或刷新策略变化时，至少联查 Auth、IAM、Admin/Client 统一认证层、国内/海外 Gateway、`common-security/` 和目标海外服务。
|
|
|
|
|
- 跨区域事件变化时同步检查事件版本、Payload 哈希、Outbox、Inbox、重复投递、失败重试、死信和全部实际消费者。
|
|
|
|
|
- 本文件是跨区域通信的公共事实来源；项目和模块 `AGENTS.md` 只保留执行所需摘要及本文件入口，不复制完整协议。
|
