企业官网建设流程全解析

1. 这不是“网关+认证”的简单拼凑，而是企业级身份治理的起点

Spring Cloud Gateway 结合 OAuth2 提供 UAA 服务——这句话乍看是技术栈堆砌，实则直指现代微服务架构中最常被轻视、却最易引发系统性风险的核心环节：统一认证与授权（UAA）的落地形态。我带团队做过 7 个中大型金融、制造类微服务项目，其中 4 个在上线半年内因认证逻辑分散、Token 管理混乱、权限校验绕过等问题触发过安全审计整改。问题根源从来不是 Spring Security 写得不对，而是把“认证”当成一个可插拔模块，而非贯穿网关、服务、客户端的治理契约。

核心关键词Spring Cloud Gateway、OAuth2、UAA、Spring Authorization Server、Spring Security在这里不是并列关系，而是分层协作关系：Gateway 是流量入口的守门人，OAuth2 是协议层的语言规范，UAA 是业务侧的治理实体，而 Spring Authorization Server（SAS）和 Spring Security 是支撑这套语言落地的执行引擎。尤其要注意，Spring Boot 3 + Spring Security 6 的组合已彻底废弃旧版spring-security-oauth2，所有 Token 签发、校验、 introspection 流程必须基于 RFC 7519（JWT）、RFC 7662（Token Introspection）和 RFC 8693（Token Exchange）重构，这不是配置升级，是协议栈重写。

这个方案解决的不是“怎么让用户登录”，而是“如何让 20+ 微服务共享同一套可信身份凭证、同一套细粒度权限策略、同一套审计溯源能力”。它适合三类人：正在从单体转向微服务的架构师（避免认证逻辑重复造轮子）、负责安全合规的运维/DevSecOps 工程师（需要集中管控 Token 生命周期）、以及接手遗留系统改造的后端开发（不用再为每个服务单独集成 Shiro 或旧版 Spring Security OAuth）。如果你还在用 Zuul 做网关、用自研 Token 校验、或把 client_id/client_secret 硬编码在服务配置里——这正是你需要停下来重读本文的信号。

2. 为什么必须用 Gateway 做 OAuth2 的第一道防线？而不是让每个服务自己验 Token

2.1 网关层校验不是“多此一举”，而是成本与安全的临界点选择

很多人第一反应是：“既然每个服务都要鉴权，那直接在服务里用@PreAuthorize不更灵活？”——这是典型的经验陷阱。我拿真实压测数据说话：某保险核心系统有 12 个业务服务，单节点 QPS 3200，若 Token 校验全部下沉到各服务：

• 每次请求需额外发起 1 次 Redis 查询（验证 Token 黑白名单）+ 1 次 JWT 解析（含 RSA 公钥验签）+ 1 次权限元数据加载（从 DB 查角色-资源映射），平均耗时 8.3ms；
• 单节点每秒产生 3200 × 3 = 9600 次跨进程调用，Redis 连接池打满，DB 出现慢查询；
• 更致命的是，当某服务因 GC 暂停 200ms，其 Token 校验队列堆积，导致合法请求被误拒，监控显示“认证失败率突增 47%”，但实际是服务抖动而非安全事件。

而将校验前置到 Spring Cloud Gateway：

• 所有流量在进入业务服务前完成统一解析、签名验证、有效期检查、黑名单拦截；
• 仅对通过校验的请求，才注入X-User-ID、X-Permissions等标准化 Header，业务服务只需做轻量级上下文提取；
• 同样 QPS 下，网关单节点校验耗时稳定在 1.2ms（基于 Netty 异步非阻塞 + JWT 解析缓存），Redis 查询合并为批量操作，DB 查询完全消除；
• 关键收益：认证失败被精准收敛到网关层，业务服务日志不再混杂认证噪音，安全审计只需盯紧网关 access log。

提示：Gateway 的 Filter 链执行顺序至关重要。AuthenticationWebFilter必须在RouteToRequestUrlFilter之后、NettyWriteResponseFilter之前，否则可能对未路由请求误判，或对转发响应篡改 Header。

2.2 OAuth2 的四种模式，为什么只选 Authorization Code Flow + PKCE？

网络热词里频繁出现的 “smtp oauth2 权限” 实际指向 OAuth2 的Client Credentials Flow（机器对机器），但 UAA 场景下绝不能主推此模式。原因很现实：它无法代表“用户身份”，只能代表“应用身份”。当你需要区分“张三能删订单”和“李四只能查订单”时，Client Credentials Flow 给出的 Token 里只有client_id，没有sub（subject），没有scope的用户级语义。

我们坚持采用Authorization Code Flow + PKCE（RFC 7636），理由如下：

• 防授权码劫持：传统 Code Flow 中，攻击者若截获重定向 URL 中的code，可直接用client_secret换取 Token。PKCE 引入code_verifier和code_challenge，即使code泄露，没有原始verifier也无法完成兑换；
• 天然适配前端分离架构：现代 SPA 应用（Vue/React）无法安全存储client_secret，PKCE 允许前端生成verifier并只传递challenge，规避密钥暴露风险；
• UAA 的扩展性基础：后续接入第三方登录（微信、钉钉）、设备码登录（device_codeFlow）、甚至 FIDO2 无密码认证，都建立在 Code Flow 的扩展框架上，无需推翻重来。

注意：Spring Authorization Server 默认启用 PKCE，但必须显式配置RegisteredClient的clientAuthenticationMethod为ClientAuthenticationMethod.NONE（公共客户端），否则会强制要求client_secret，违背 PKCE 设计初衷。

2.3 UAA 不是“又一个登录页”，而是身份生命周期的中央控制器

很多团队把 UAA 理解为“统一登录中心”，于是只实现/login和/oauth2/authorize，结果埋下三个隐患：

• Token 刷新失控：前端拿到 Access Token 后，若过期时间设为 30 分钟，用户操作到一半 Token 失效，体验断层。UAA 必须提供/oauth2/token的 Refresh Token 换取接口，并强制绑定refresh_token的使用次数、绑定设备指纹、设置滑动过期窗口；
• 会话状态游离：用户在 A 服务登出，B 服务仍持有有效 Token。UAA 需实现/v1/revoke接口，接收token_hint（Access 或 Refresh Token）并主动吊销，同时广播TokenRevokedEvent到 Redis Pub/Sub，各服务监听后清空本地缓存；
• 权限动态变更失效：管理员在后台修改用户角色，但已签发的 Token 仍含旧权限。UAA 必须支持 Token Introspection（RFC 7662），网关在每次请求时调用/oauth2/introspect实时校验 Token 状态，而非依赖 JWT 的静态 payload。

这些能力不是“锦上添花”，而是 UAA 作为中央控制器的存在依据。没有它们，所谓的“统一”只是表面路由聚合，本质仍是 N 个独立认证孤岛。

3. Spring Authorization Server 替代旧版 Spring Security OAuth2 的关键重构点

3.1 从@EnableAuthorizationServer到@RegisterExtension：配置范式的根本转变

Spring Security OAuth2 2.x 的@EnableAuthorizationServer注解，本质是把 Authorization Server 当作一个黑盒组件自动装配。而 Spring Authorization Server（SAS）3.x 要求你显式声明每个协议端点的行为，这是安全加固的必然选择。

以/oauth2/authorize端点为例，旧版只需：

@Configuration @EnableAuthorizationServer public class AuthServerConfig extends AuthorizationServerConfigurerAdapter { @Override public void configure(AuthorizationServerEndpointsConfigurer endpoints) { endpoints.tokenStore(new JwtTokenStore(accessTokenConverter())); } }

SAS 中必须手动注册：

@Bean public RegisteredClientRepository registeredClientRepository() { // 定义客户端：前端 SPA 应用 RegisteredClient webClient = RegisteredClient.withId(UUID.randomUUID().toString()) .clientId("web-app") .clientName("Web Application") .clientAuthenticationMethod(ClientAuthenticationMethod.NONE) // PKCE 不需要 client_secret .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE) .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN) .redirectUri("https://your-app.com/login/callback") // 必须精确匹配 .scope("read") .scope("write") .clientSettings(ClientSettings.builder() .requireProofKeyForCodeExchange(true) // 强制 PKCE .build()) .build(); return new InMemoryRegisteredClientRepository(webClient); } @Bean public JWKSource<SecurityContext> jwkSource() { // 使用 RSA 密钥对，公钥用于 JWT 验签，私钥用于签发 KeyPair keyPair = generateRsaKeyPair(); // 生产环境应从 KMS 加载 RSAKey rsaKey = RSAKey.Builder((RSAPublicKey) keyPair.getPublic()) .privateKey((RSAPrivateKey) keyPair.getPrivate()) .keyID(UUID.randomUUID().toString()) .build(); return new ImmutableJWKSet<>(new JWKSet(rsaKey)); }

关键变化在于：

• 客户端注册显式化：每个RegisteredClient必须明确clientAuthenticationMethod、authorizationGrantType、redirectUri（支持正则匹配）、scope，杜绝配置遗漏；
• 密钥管理解耦：JWKSource独立于 Token 生成逻辑，便于对接 HashiCorp Vault 或 AWS KMS；
• Token 自定义可控：通过OAuth2TokenCustomizer<JwtEncodingContext>可向 JWT 添加tenant_id、department等业务字段，且不影响标准 claims。

实操心得：redirectUri必须与前端实际回调地址完全一致（包括末尾斜杠），SAS 默认启用严格匹配。曾有项目因前端配置https://app.com/callback/而 UAA 配置https://app.com/callback，导致授权码始终 400，排查耗时 3 小时。建议在RegisteredClient初始化时加入 URI 标准化校验。

3.2 JWT 签发不再是“开箱即用”，而是必须理解的密码学实践

旧版JwtAccessTokenConverter仅需配置signingKey，SAS 要求你深入理解 JWT 结构：

• Header：指定alg: RS256（非对称签名，推荐）或HS256（对称签名，仅限测试）；
• Payload：标准 claims（iss,sub,aud,exp,iat）由 SAS 自动填充，但业务 claims（如user_name,roles）需通过OAuth2TokenCustomizer注入；
• Signature：使用私钥对base64url(header).base64url(payload)签名，公钥用于验签。

常见错误配置：

// ❌ 错误：使用对称密钥 HS256，私钥泄露即全系统沦陷 @Bean public JwtEncoder jwtEncoder() { return new NimbusJwtEncoder(JwtEncoderProviderUtils::getSecretKey); // 返回 String 密钥 }

正确做法（生产环境）：

@Bean public JwtEncoder jwtEncoder(JWKSource<SecurityContext> jwkSource) { return new NimbusJwtEncoder(jwkSource); } // Token 自定义：注入用户部门和租户信息 @Bean public OAuth2TokenCustomizer<JwtEncodingContext> jwtCustomizer() { return context -> { if (OAuth2TokenType.ACCESS_TOKEN.equals(context.getTokenType())) { context.getClaims().claim("tenant_id", "acme-inc") .claim("department", "finance"); } }; }

注意：RSA 密钥对生成必须使用KeyPairGenerator.getInstance("RSA")，且密钥长度 ≥ 2048 bit。低于 1024 bit 的密钥已被 NIST 认定为不安全，部分云厂商 WAF 会直接拦截。

3.3 Resource Server（资源服务器）的校验逻辑迁移：从ResourceServerConfigurerAdapter到SecurityFilterChain

旧版资源服务配置：

@Configuration @EnableResourceServer public class ResourceServerConfig extends ResourceServerConfigurerAdapter { @Override public void configure(HttpSecurity http) throws Exception { http.authorizeRequests() .antMatchers("/api/public/**").permitAll() .antMatchers("/api/private/**").authenticated(); } }

SAS + Spring Security 6 的等效配置：

@Bean public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authz -> authz .requestMatchers("/api/public/**").permitAll() .requestMatchers("/api/private/**").authenticated() ) .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt); // 启用 JWT 校验 return http.build(); } @Bean public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) { // 使用公钥解码 JWT，无需私钥 return OAuth2JwtDecoderJwtBuilder .fromIssuerAndJwkSetUri("https://uaa.example.com", "https://uaa.example.com/oauth2/jwks") .build(); }

核心差异：

• 校验时机前移：JWT 解析、签名验证、exp检查在FilterChain早期完成，失败直接返回 401，不进入 Controller；
• Scope 映射自动化：@PreAuthorize("hasAuthority('SCOPE_read')")中的SCOPE_前缀由 Spring Security 自动添加，无需手动拼接；
• Introspection 可选：若需实时校验 Token 状态（如吊销），可配置oauth2ResourceServer().opaqueToken()并指定 introspection endpoint。

4. Spring Cloud Gateway 作为 OAuth2 Resource Server 的完整实现

4.1 为什么 Gateway 必须成为 Resource Server？而非仅做反向代理

单纯把 Gateway 当作反向代理，将/auth/**路由到 UAA，其余路径直通业务服务，会丢失三大能力：

• Token 提取与透传失效：业务服务无法获取标准化的X-User-ID，只能自行解析 JWT，重复造轮子；
• 权限预过滤缺失：网关无法根据 Token 中的scope或roles拦截非法请求（如/admin/delete被普通用户访问）；
• 审计日志颗粒度粗：日志只记录GET /order/123，不记录user_id=U1001, scope=read_order，无法关联用户行为。

因此，Gateway 必须以Resource Server身份运行，承担 Token 校验、上下文注入、权限路由职责。

4.2 核心配置：GlobalFilter+ReactiveJwtDecoder的协同工作流

Gateway 的 OAuth2 集成不依赖spring-boot-starter-oauth2-resource-server（该 Starter 为 Servlet 环境设计），而是基于 WebFlux 的ReactiveJwtDecoder：

# application.yml spring: cloud: gateway: routes: - id: auth-service uri: http://uaa-service:8080 predicates: - Path=/oauth2/** - id: order-service uri: http://order-service:8080 predicates: - Path=/api/order/** filters: - StripPrefix=1 - name: AuthenticationFilter # 自定义 Filter args: auth-url: https://uaa.example.com/oauth2/introspect required-scopes: read_order,write_order

自定义AuthenticationFilter实现：

@Component public class AuthenticationFilter implements GlobalFilter, Ordered { private final ReactiveJwtDecoder jwtDecoder; private final WebClient introspectClient; // 用于 Token Introspection public AuthenticationFilter(ReactiveJwtDecoder jwtDecoder, WebClient.Builder webClientBuilder) { this.jwtDecoder = jwtDecoder; this.introspectClient = webClientBuilder .defaultHeaders(httpHeaders -> httpHeaders.setBasicAuth("gateway-client", "secret")) .build(); } @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { String authHeader = exchange.getRequest().getHeaders().getFirst("Authorization"); if (authHeader == null || !authHeader.startsWith("Bearer ")) { return Mono.error(new RuntimeException("Missing or invalid Authorization header")); } String token = authHeader.substring(7); return jwtDecoder.decode(token) .onErrorResume(error -> { // JWT 解析失败，尝试 Introspection fallback return introspectToken(token); }) .flatMap(jwt -> { // 校验 scope 是否满足路由要求 List<String> scopes = jwt.getClaimAsStringList("scope"); if (!scopes.contains("read_order")) { return Mono.error(new RuntimeException("Insufficient scope")); } // 注入 Header ServerHttpRequest request = exchange.getRequest() .mutate() .header("X-User-ID", jwt.getSubject()) .header("X-Permissions", String.join(",", scopes)) .build(); ServerWebExchange mutatedExchange = exchange.mutate().request(request).build(); return chain.filter(mutatedExchange); }); } private Mono<Jwt> introspectToken(String token) { return introspectClient.post() .uri("https://uaa.example.com/oauth2/introspect") .bodyValue(Map.of("token", token)) .retrieve() .bodyToMono(IntrospectionResponse.class) .filter(IntrospectionResponse::isActive) .map(resp -> Jwt.withTokenValue(token) .header("kid", resp.getJti()) .claim("sub", resp.getUsername()) .claim("scope", resp.getScope()) .build()); } }

关键设计点：

• 双校验机制：先尝试 JWT 本地解析（快），失败后降级调用 UAA 的 Introspection 接口（准），兼顾性能与可靠性；
• Scope 动态校验：required-scopes从路由配置注入，不同服务可设置不同权限门槛；
• Header 标准化注入：业务服务无需解析 JWT，直接读取X-User-ID，降低耦合。

4.3 路由级权限控制：用 Predicate 实现细粒度访问策略

Gateway 的Predicate不仅能匹配路径，还能结合认证上下文做决策。例如，限制/api/admin/**仅对ADMIN角色开放：

@Bean public RouteLocator customRouteLocator(RouteLocatorBuilder builder) { return builder.routes() .route("admin-route", r -> r.path("/api/admin/**") .and() .header("X-User-ID", ".*") // 确保已认证 .and() .header("X-Permissions", ".*ADMIN.*") // 权限包含 ADMIN .uri("http://admin-service:8080")) .build(); }

更优雅的方式是自定义GatewayPredicateFactory：

public class RoleBasedPredicateFactory extends AbstractRoutePredicateFactory<RoleBasedPredicateFactory.Config> { public static class Config { private String role; public Config() {} public String getRole() { return role; } public void setRole(String role) { this.role = role; } } public RoleBasedPredicateFactory() { super(Config.class); } @Override public Predicate<ServerWebExchange> apply(Config config) { return exchange -> { String permissions = exchange.getRequest().getHeaders().getFirst("X-Permissions"); return permissions != null && permissions.contains(config.role); }; } }

在 YAML 中使用：

spring: cloud: gateway: routes: - id: admin-route uri: http://admin-service:8080 predicates: - Path=/api/admin/** - RoleBased=admin

实操心得：Header 匹配对大小写敏感，X-Permissions中的ADMIN必须与 Token 中roles字段值完全一致。建议在 UAA 签发 Token 时，统一转为大写并用逗号分隔，避免Admin、admin、ADMIN多种写法。

5. 生产环境避坑指南：从开发到上线的 12 个关键细节

5.1 密钥管理：别把 RSA 私钥写进代码或配置文件

• 开发环境：使用openssl genrsa -out private.key 2048生成密钥对，private.key放入src/main/resources，通过@Value("classpath:private.key")加载；
• 生产环境：必须从外部密钥管理服务加载。以 AWS Secrets Manager 为例：

  @Bean public KeyPair keyPair() throws Exception { String privateKeyPem = secretsManager.getSecretValue("uaa-rsa-private-key").getSecretString(); Reader reader = new StringReader(privateKeyPem); PEMParser pemParser = new PEMParser(reader); PrivateKeyInfo privateKeyInfo = (PrivateKeyInfo) pemParser.readObject(); JcaPEMKeyConverter converter = new JcaPEMKeyConverter(); return converter.getKeyPair(privateKeyInfo); }

• 绝对禁止：将私钥硬编码在 Java 类中、或以明文形式存入 Git 仓库。曾有团队因private.key被上传 GitHub，导致所有已签发 Token 可被伪造，紧急发布密钥轮换补丁。

5.2 Token 存储：Redis 不是万能的，要分场景设计 TTL

Redis 操作示例（Refresh Token 吊销）：

// 吊销时：ZADD revocation_set <exp_timestamp> <token_hash> redisTemplate.opsForZSet().add("revocation_set", tokenHash, System.currentTimeMillis() + 7 * 24 * 3600_000); // 校验时：ZRANGEBYSCORE revocation_set 0 <current_timestamp> COUNT 1 Boolean isRevoked = redisTemplate.opsForZSet().rangeByScore("revocation_set", 0, System.currentTimeMillis(), 0, 1).size() > 0;

注意：Redis 的ZREMRANGEBYSCORE应定时清理过期项，避免 Sorted Set 无限膨胀。建议在 Spring Scheduler 中每小时执行一次ZREMRANGEBYSCORE revocation_set 0 <now-7days>。

5.3 CORS 配置：UAA 的/oauth2/authorize端点必须放行前端域名

UAA 的@CrossOrigin注解必须精确到前端部署域名：

@RestController @RequestMapping("/oauth2") public class AuthorizationController { @GetMapping("/authorize") @CrossOrigin(origins = {"https://app.example.com", "https://staging.app.example.com"}) public String authorize(...) { ... } }

常见错误：

• 使用origins = "*"：浏览器会拒绝携带 Cookie 的请求，导致 PKCE 的code_verifier无法传递；
• 只配置https://app.example.com，但前端实际运行在https://app.example.com:8080（开发环境），导致跨域失败。

5.4 日志审计：必须记录client_id、user_id、scope、ip四要素

UAA 的审计日志格式应为：

[2023-10-05T08:23:41.123Z] [AUTH-SUCCESS] client_id=web-app user_id=U1001 scope=read_order,write_order ip=203.0.113.45 user_agent="Mozilla/5.0 ..." [2023-10-05T08:24:02.456Z] [AUTH-FAILURE] client_id=mobile-app error="invalid_scope" ip=198.51.100.22

关键点：

• AUTH-SUCCESS和AUTH-FAILURE标签便于 ELK 过滤；
• error字段必须记录 OAuth2 标准错误码（invalid_request,invalid_client,invalid_scope），而非 Java 异常类名；
• user_agent用于识别设备类型，辅助风控。

5.5 健康检查：UAA 的/actuator/health必须包含 JWK 和 DB 连接状态

@Component public class UaaHealthIndicator implements HealthIndicator { private final JWKSource<SecurityContext> jwkSource; private final DataSource dataSource; @Override public Health health() { Health.Builder builder = Health.up(); try { // 测试 JWK 加载 jwkSource.get(JWKSelector.EMPTY, SecurityContext.EMPTY).get(0); } catch (Exception e) { builder.down().withDetail("jwk_status", "unavailable"); } try { // 测试 DB 连接 dataSource.getConnection().close(); } catch (Exception e) { builder.down().withDetail("db_status", "unavailable"); } return builder.build(); } }

Kubernetes Liveness Probe 应调用/actuator/health，而非/actuator/health/liveness（默认不检查依赖），避免网关因 UAA JWK 加载失败而持续重试。

5.6 版本兼容性雷区：Spring Boot 3.2 + Spring Authorization Server 1.2 的依赖锁

当前（2024年）最稳定的组合：

<properties> <spring-boot.version>3.2.5</spring-boot.version> <spring-authorization-server.version>1.2.4</spring-authorization-server.version> <spring-cloud.version>2023.0.1</spring-cloud.version> </properties>

绝对避免的组合：

• Spring Boot 3.0 + SAS 1.0：OAuth2TokenCustomizer接口不兼容；
• Spring Cloud Gateway 4.0 + Spring Security 6.0：ReactiveJwtDecoder的setJwtValidator方法签名变更；
• 使用spring-boot-starter-webflux但未排除spring-boot-starter-web：导致 Servlet 和 WebFlux 混用，启动失败。

5.7 性能压测：网关层 Token 校验的瓶颈不在 CPU，而在 GC

我们对 Gateway 进行 10k QPS 压测时发现：

• JVM 参数-XX:+UseG1GC -XX:MaxGCPauseMillis=200下，Young GC 频繁（每 2 秒一次），Prometheus显示jvm_gc_pause_seconds_count{action="end of minor gc"}暴涨；
• 根本原因是JwtDecoder每次解析都创建大量临时对象（Base64解码缓冲区、JSONObject实例）；
• 解决方案：启用 JWT 解析缓存（SAS 默认关闭）：

  @Bean public JwtDecoder jwtDecoder(JWKSource<SecurityContext> jwkSource) { NimbusJwtDecoder jwtDecoder = (NimbusJwtDecoder) JwtDecoders.fromIssuerLocation("https://uaa.example.com"); jwtDecoder.setJwtValidator(Validators.createDefault()); // 启用内置缓存 return jwtDecoder; }

5.8 安全加固：必须禁用的 5 个危险配置

5.9 故障排查：401 Unauthorized 的 7 种根因速查表

5.10 监控告警：必须设置的 4 个 Prometheus 指标

# alert-rules.yml - alert: UaaJwkUnreachable expr: rate(http_client_requests_seconds_count{uri="/oauth2/jwks", status_code=~"5.."}[5m]) > 0.1 for: 2m labels: severity: critical annotations: summary: "UAA JWK endpoint unreachable" - alert: GatewayAuthLatencyHigh expr: histogram_quantile(0.95, sum(rate(http_server_requests_seconds_bucket{handler="AuthenticationFilter"}[5m])) by (le)) > 0.5 for: 2m labels: severity: warning annotations: summary: "Gateway authentication latency > 500ms" - alert: TokenIntrospectionFailureRateHigh expr: rate(http_client_requests_seconds_count{uri="/oauth2/introspect", status_code=~"5.."}[5m]) / rate(http_client_requests_seconds_count{uri="/oauth2/introspect"}[5m]) > 0.05 for: 2m labels: severity: warning annotations: summary: "Token introspection failure rate > 5%" - alert: RevocationListSizeTooLarge expr: redis_sorted_set_length{key="revocation_set"} > 100000 for: 10m labels: severity: warning annotations: summary: "Revocation list size > 100k, consider cleanup job"

5.11 灰度发布：如何零停机升级 UAA 的 JWK 密钥对

步骤：

1. 在 UAA 配置新密钥对，但不切换为默认签发密钥；
2. 将新 JWK 的kid添加到JWKSet，保持旧kid仍在集合中；
3. 更新 Gateway 的jwk-set-uri缓存刷新策略（默认 5 分钟），或手动触发JwkSetCache.clear()；
4. 观察日志，确认新旧kid的 Token 均能成功解析；
5. 将 UAA 的默认签发密钥切换为新密钥对；
6. 等待旧密钥签发的所有 Token 自然过期（exp时间），再从JWKSet移除旧kid。

关键点：kid是 JWT Header 中的唯一标识，Gateway 会根据kid选择对应公钥验签。只要JWKSet同时包含新旧kid，就能平滑过渡。

5.12 最后一个忠告：不要试图在 Gateway 里实现完整的 OAuth2 Client

网上很多教程教你在 Gateway 里写OAuth2AuthorizedClientService、OAuth2AuthorizationRequestResolver，这是严重误区。Gateway 的职责是Resource Server（验证 Token），不是Client（发起授权请求）。授权流程必须由前端或 Backend-for-Frontend（BFF）完成，Gateway 只接收已签发的 Bearer Token 并校验。否则，你会陷入 Cookie 管理、CSRF 防护、Session 同步等与网关定位无关的复杂性泥潭。

我在某电商项目就见过团队在 Gateway 里实现完整的 Authorization Code Flow，结果因 Netty 的线