2.0 KiB
2.0 KiB
Overseas Gateway 模块指引
职责边界
- 负责海外 API 统一入口、路由、RS256/JWKS 验签、Audience 和必要 Claims 校验。
- 不保存签名私钥，不依赖国内 Redis 会话，不在网关实现尾程业务逻辑。
- 修改海外 Token、Audience、JWKS、区域路由或服务身份时，先读
../../docs/跨区域认证与服务通信契约.md。
快速索引
| 功能 | 入口 |
|---|---|
| 安全链配置 | src/main/java/com/baiyue/gateway/config/GatewaySecurityConfig.java |
| Audience 校验 | config/AudienceJwtValidator.java |
| 必要 Claims 校验 | config/RequiredClaimsJwtValidator.java |
| 安全配置项 | config/GatewaySecurityProperties.java |
| 可信身份头传递 | filter/TrustedIdentityHeaderFilter.java |
| 环境配置 | src/main/resources/application.yml、../config/nacos/ |
| 浏览器业务路由 | src/main/resources/application-overseas.yml；Lastleg 显式覆盖 /api/merchant/v1/last-leg/**、/api/platform/v1/last-leg/**，Warehouse 显式覆盖商户仓库与平台 warehouse-admin 路径 |
| 海外 PDA 路由 | 设备端 ../../apps/pda-overseas-uniapp/，服务端入口 /api/pda/v1/last-leg/**；必须在 Gateway 路由中显式声明并保持海外 Token/权限校验，不得让设备直连 Lastleg |
| 测试 | src/test/java/com/baiyue/gateway/config/ |
安全规则
- 生产令牌
aud必须包含lastleg-api，并包含配置要求的身份声明。 - 网关必须清除外部请求伪造的可信身份头，仅传递验签后生成的身份信息。
- JWKS 地址、Issuer 和 Audience 必须外部配置；不得在源码写死生产密钥。
- merchant、platform 与 PDA 路径分别显式维护路由和授权边界；新增 PDA Controller 不会自动成为公网路由，Gateway 未声明前不得把设备链路标记为已联通。
修改与验证
- 定向验证：
mvn -pl gateway-overseas -am test。 - 安全变更覆盖合法令牌、错误 Audience、缺失 Claims、过期/错误签名和身份头伪造测试。