聊到Spring Cloud微服务落地绕不开的就是分布式权限校验。很多团队从单体转型到微服务之后第一反应是把原来的Session拷贝一份放到Redis里接着用结果各种状态不同步、网关无法统一鉴权、业务服务还要去查会话问题一个接一个。我自己在推进项目拆分时就被这套东西卡过不止一次后来把OAuth这套体系彻底理顺才真正明白分布式权限校验应该怎么设计。这篇文章就是把这些经验沉淀下来适合已经会Spring Cloud基础组件、但还没系统设计过权限模块的开发者参考。这里不会只贴一段官方文档式的配置而是把为什么用OAuth、Token怎么设计、网关怎么做统一鉴权、资源服务怎么配合以及线上常见的坑都串起来讲一遍。核心思路是认证服务负责发Token网关负责校验Token并透传身份业务服务只信任最终得到的用户信息配合Redis和JWT做到可控的分布式会话。这套方案在当前Spring Cloud生态里是比较主流、踩坑成本也相对可控的路线。1. 为什么微服务权限校验绕不开OAuth1.1 单体Session方案在分布式下的三个痛点先聊聊很多团队在转型初期容易踩的坑。单体应用里用户登录后把用户信息丢进Session每次请求带着Cookie过来后端直接查Session就能确认身份代码写起来非常舒服。但到了微服务阶段这套逻辑会遇到几个非常棘手的问题。第一个痛点是状态共享。用户的Session是存内存还是存Redis如果是存内存那用户的两个请求打到不同实例上就会莫名其妙掉线如果存Redis你会发现每个业务服务都依赖同一个会话存储服务拆分得越细Redis反而变成最大的耦合点。更麻烦的是会话数据里如果塞了用户对象涉及序列化版本升级时线上会面临热数据兼容问题这是我们团队真实遇到过的。第二个痛点是多端适配。现在项目基本都是Web、小程序、App同时存在Session Cookie这套机制只在浏览器Web端顺畅原生App端对Cookie的支持完全是另一套逻辑小程序又有自己的登录体系。如果沿用Session方案等于每个端都要单独做一套会话适配后端还要维护多套Session生命周期工作量翻倍不说还特别容易出漏洞。第三个痛点是鉴权逻辑和业务代码耦合。单体时代我们习惯在每个Service方法里拿一下当前用户但在微服务里你没法保证调用你服务的对象一定经过了Web层。服务间调用、消息队列消费、定时任务触发这些场景根本没有HttpSession概念如果权限逻辑全部建立在Session上那这些批量任务的鉴权就会变得很尴尬。所以这时候我们需要一套和具体会话无关的权限方案——核心就是把“认证”和“授权”分开用Token传递用户身份。1.2 OAuth2.0到底解决了什么问题OAuth2.0本质上不是一套新鲜东西它是一个授权框架。它定义了四个角色资源所有者用户、客户端Web、App、服务、授权服务器发Token的地方、资源服务器提供业务数据的服务。放到Spring Cloud场景里客户端的角色很灵活——用户的浏览器是客户端前端服务是客户端甚至后端的某个微服务在请求另一个服务时也是客户端。这些角色之间通过Token进行身份传递。登录成功后认证服务发放一个Token给客户端客户端每次请求都携带这个Token资源服务只需要验证Token是否有效不需要自己存任何会话状态。这就解决了我刚才说的三个痛点没有Session共享问题因为Token是自包含的多端只需要统一携带Token不用管Cookie的兼容性服务间调用时也能用Token传递身份和Web场景保持一致。更重要的是OAuth2.0把“登录授权”这个动作集中到了认证服务上。用户密码只在认证服务的登录页出现业务系统不接触用户密码。从安全审计角度讲漏洞面会小很多权限变更、踢人下线、密码重置也都收敛到一个点。1.3 整体架构认证服务、网关、业务服务怎么分工落到Spring Cloud微服务里我常用的架构是三层分工模式。第一层是认证服务Authorization Server它负责登录、发Token、刷新Token偶尔还负责登出和Token吊销。认证服务只做一件事就是对用户身份做出判定然后签发Token。第二层是Spring Cloud Gateway网关它是所有请求的入口负责拦截请求、校验Token是否有效、解析Token里的用户信息然后把用户信息放到请求头里转发给下游服务。网关在这一层的核心任务不是业务而是“集中鉴权”避免每个服务各自实现一套校验逻辑。第三层是业务服务也就是资源服务。业务服务接收网关转发的请求从请求头里拿到用户身份然后做权限判断比如当前用户是否拥有某个角色、某个操作权限或者直接把用户ID传给Service层使用。这三层各司其职以后整个权限链路是这样的客户端请求 - 网关校验Token - 网关提取用户信息 - 转发请求头 - 业务服务读取用户信息 - 执行方法级权限判断 - 返回业务结果每一层都不需要依赖别的服务的Session业务服务也不需要访问认证服务的数据库只要信任Token本身即可。这个架构的好处是业务服务可以被单独压测、单独缩容、单独发布认证逻辑完全隔离后面若要支持SPA、App、小程序等不同客户端也不需要改业务服务代码。2. 方案选型Token用JWT还是存Redis2.1 JWT令牌的优缺点确定用Token以后下一步就是选Token的形态。现在主流是JWTJSON Web Token它本质上是一段Base64编码的字符串包含三部分Header、Payload、Signature。Header里写签名算法Payload里放用户信息、过期时间、作用域等Signature则是用私钥对前两部分签名。JWT最大的优点是无状态、自包含、轻量。业务服务拿到JWT后不需要查数据库只需要验签就能信任里面的信息。但JWT的优点同时也是缺点。因为它是自包含的Token一经签发在过期之前服务端无法主动让它失效。比如用户改了密码理论上旧Token应该立即失效但按JWT的设计除非你额外引入黑名单机制否则这个Token还能继续用到过期。另一个缺点是Token体积会比随机字符串大不少如果Payload里塞了一堆角色权限请求头部会膨胀在网关转发时也会多出很多无用的字符串。所以我的观点是不要为了JWT而JWT也不要为了状态共享而把Token存成纯Redis随机串。更建议的做法是“JWT Redis 键控”的组合模式。2.2 我建议的组合JWT Redis键控所谓键控就是在JWT里放一个唯一标识比如jti然后Redis里存一个以jti为key的状态记录。这个记录里的value可以是userId、过期时间、吊销状态等关键信息。网关在验签之后还需要去Redis查一下这个jti是否存在、状态是否正常。如果Redis里查不到或者标记为吊销那么即使JWT签名合法也直接拒绝请求。这么设计其实是在“无状态”和“可控性”之间取了个平衡。正常请求走JWT验签不需要频繁查库性能损耗很低Token吊销、踢人下线、权限即时变更等场景则通过操作Redis记录来实现。严格来说它已经不是100%无状态了但Redis作为集中式状态点对分布式系统来说是必要的毕竟你总要有个地方记录“哪些Token是干净的”。实际项目中我会把Redis里的结构设计成这样oauth:token:{jti} - { userId: 1001, clientId: web, expiresIn: 7200 } oauth:user-token:{userId} - { currentJti: xxx, lastRefreshTime: 1710000000 }第一个key是为了快速校验Token有效性第二个key是为了实现“一个用户同时只能在一个端登录”之类业务策略用户再次登录后旧的currentJti会被覆盖网关查到jti不匹配就会拒绝请求。2.3 授权模式怎么选OAuth2.0有几种授权模式很多初学者容易混淆。我这里不展开所有模式只说Spring Cloud环境里最常用的两种。一种是授权码模式Authorization Code适合Web应用和前后端分离场景。用户访问前端时前端引导用户跳转到认证服务登录登录成功后认证服务返回授权码前端用授权码向后端换Token。它的优点是用户密码不经过前端安全性高而且支持刷新Token。另一种是客户端模式Client Credentials适合服务间调用。比如xxl-job定时任务要调业务接口此时没有用户参与后台服务直接用clientId和clientSecret去认证服务换一个服务级别的Token这个Token可以拥有特定的scope比如只允许调用某个Job接口。至于密码模式虽然很多老项目还在用但我建议新项目不要再用。原因很简单密码模式要求客户端拿着密码去换Token这等于把用户密码暴露给了应用层不符合现代安全规范。Spring官方在Spring Authorization Server里也明确不推荐密码模式默认都不实现它。3. 从零落地授权服务器、资源服务和网关配置3.1 一步步搭建授权服务器我选型时用的是Spring Authorization Server这是Spring官方提供的现代授权服务器实现替代了早期已经停止维护的Spring Security OAuth2。它基于Spring Security构建配置起来相对规范。Maven依赖这样引入dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-oauth2-authorization-server/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-redis/artifactId /dependencySpring Authorization Server的核心配置是注册一个SecurityFilterChain的Bean并且加上EnableAuthorizationServer注解在我的实际版本中是通过SecurityFilterChain的配置类来完成具体类名以官方文档为主。关键配置点有授权服务器相关端点路径、客户端信息、Token生成方式、Token存储策略。客户端信息配置示例Bean public RegisteredClientRepository registeredClientRepository() { RegisteredClient webClient RegisteredClient.withId(web-client) .clientId(web-client-id) .clientSecret({noop}web-client-secret) .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE) .authorizationGrantType(AuthorizationGrantType.REFRESH_TOKEN) .redirectUri(http://localhost:8080/login/oauth2/code/web) .scope(openid) .scope(profile) .build(); return new InMemoryRegisteredClientRepository(webClient); }Token的生成和存储我选择往Redis里写。可以用OAuth2TokenEndpointConfigurer自定义Token生成逻辑也可以更简单地实现一个OAuth2TokenCustomizer往JWT的Claims里写入业务需要的userName、角色列表等信息。这里有个我在项目中反复确认的细节token的过期时间一定要和Redis的TTL保持一致。比如accessToken的有效期是2小时那Redis里对应key的TTL也要设为2小时同时refreshToken有效期如果是30天那么刷新时新发放的accessToken对应的key也必须是2小时。不然会出现Redis已经删掉了token但业务服务验签还能通过的情况。3.2 搭建资源服务资源服务就是我们正常的业务微服务在Spring Security中通过JWT解析器配置来完成Token校验。依赖如下dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-oauth2-resource-server/artifactId /dependency配置类里需要指定JWT的验签公钥。如果授权服务器和资源服务共用同一个签名密钥我一般会在配置中心里管理一个JWK Set地址资源服务启动时自动拉取公钥spring: security: oauth2: resourceserver: jwt: jwk-set-uri: http://auth-server/oauth2/jwks这样配置后资源服务会自动校验JWT的签名、过期时间等。接着通过注解开启方法级权限校验Configuration EnableWebSecurity EnableGlobalMethodSecurity(prePostEnabled true) public class ResourceServerConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .oauth2ResourceServer(oauth2 - oauth2.jwt(Customizer.withDefaults())) .authorizeHttpRequests(auth - auth .anyRequest().authenticated() ); return http.build(); } }然后在Controller层或Service层直接使用权限注解PreAuthorize(hasAuthority(admin)) GetMapping(/admin/users) public ListUser listUsers() { return userService.listAll(); }这里有个容易踩坑的地方JWT中角色的key默认是scope不是authority。如果你把角色信息放在JWT的roles字段里需要自定义一个JwtAuthenticationConverter把roles映射为权限。否则你会发现明明JWT里有admin角色但PreAuthorize(hasRole(admin))就是失效。3.3 网关统一鉴权过滤器网关不在业务服务的资源服务体系内它更像一个前置安全代理。我在Spring Cloud Gateway里通过GlobalFilter GatewayFilterChain实现统一鉴权。核心思路是网关拿到请求后先从Authorization头发取Bearer Token然后调用JWT解析器验签验签通过后解析出userId、角色等信息放行并把用户信息放入请求头验签失败则直接返回401。一个简化版的网关过滤器大致长这样Component public class AuthGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request exchange.getRequest(); String path request.getURI().getPath(); // 白名单放行比如登录接口、静态资源 if (whiteList.contains(path)) { return chain.filter(exchange); } String token resolveToken(request); if (StringUtils.hasText(token)) { try { Jwt jwt jwtDecoder.decode(token); String userId jwt.getClaimAsString(userId); String roles StringUtils.collectionToCommaDelimitedString( jwt.getClaimAsStringList(roles)); ServerHttpRequest mutatedRequest request.mutate() .header(X-User-Id, userId) .header(X-User-Roles, roles) .build(); return chain.filter(exchange.mutate().request(mutatedRequest).build()); } catch (JwtException e) { return unauthorizedResponse(exchange); } } return unauthorizedResponse(exchange); } Override public int getOrder() { return -100; } }这个过滤器里我保留了白名单路径透传比如认证服务的登录端点、对外暴露的健康检查接口、回调通知接口等。这里不要图省事把所有接口都拦截否则后面排查权限问题时连认证服务本身的登录端也会被网关挡住形成死循环。4. 分布式场景下的关键细节与扩展4.1 Token在网关集群中的共享以及Gateway集群可行性热搜词里有个问题很典型Spring Cloud Gateway能做集群吗答案是当然可以。Gateway本身是无状态网关节点之间不需要同步任何会话只要所有节点共享同一个Redis和同一个配置中心即可。前置可以用Nginx或负载均衡器做流量分发后端的Gateway节点任意伸缩用户请求打到哪个节点都能正常工作。前提是你千万不要在Gateway过滤器里用本地缓存去存Token的吊销状态。如果A节点缓存了Token有效但用户在B节点触发了吊销A节点还可能继续放行。我在生产环境就遇到过这个问题最开始为了降低Redis压力在网关里加了一层本地缓存结果用户踢人下线后旧Token还能访问接近一分钟后来直接砍掉了本地缓存保证每次鉴权都走Redis键控行为才符合预期。另外还要注意网关集群部署时要保证JWT验签公钥一致。如果你用本地密钥文件就必须把同一个公钥同步到所有节点如果用JWK Set URI确保认证服务地址对网关节点来说都是可访问的并且网络隔离策略没有拦掉内网调用。4.2 并发刷新与分布式锁Token快过期时客户端会拿refreshToken换新的accessToken。这个动作在高并发下会有一个经典问题如果多个请求同时发现accessToken过期同时携带着同一个refreshToken去刷新可能产生多个新Token旧refreshToken也可能被重复消费。解决这个问题的常规手段是引入分布式锁锁的粒度控制在refreshToken级别。我用Redis的SETNX命令实现一个简单的分布式锁String lockKey oauth:refresh-lock: refreshToken; Boolean locked redisTemplate.opsForValue().setIfAbsent(lockKey, 1, Duration.ofSeconds(10)); if (Boolean.TRUE.equals(locked)) { try { // 执行刷新逻辑校验refreshToken是否存在、是否被吊销 // 生成新的accessToken和refreshToken // 刷新完成后删除旧refreshToken记录 } finally { redisTemplate.delete(lockKey); } } else { // 说明有并发刷新线程这里直接等待或返回旧token让客户端重试 throw new TokenRefreshConflictException(请稍后重试); }这其实和“Redis分布式锁”面试题是同一个道理。锁的key要精细不能一把锁锁住所有用户的刷新操作锁的过期时间要留足余量避免业务执行时间超过锁的自动释放时间。我用10秒是因为正常情况下刷新操作在几十毫秒内完成10秒足够。如果你接入了外部认证系统刷新可能比较慢就把超时时间调大一些同时做好刷新接口的幂等设计。4.3 Token吊销、踢人下线以及权限变更即时生效分布式权限校验容易被忽略的一点是用户密码重置、用户角色变更后已发放的Token还能不能用用纯JWT的方案时答案是很遗憾旧Token在过期前都还能用。所以我在方案里加入Redis键控就是为了解决这一类运营侧的硬需求。具体做法是用户主动退出删除oauth:token:{jti}这个键后面的请求到网关后查不到键直接401。管理员在后台踢人通过oauth:user-token:{userId}找到当前jti删除oauth:token:{jti}并更新oauth:user-token:{userId}里的当前jti为空。用户密码重置需要把所有客户端下该用户的所有Token都吊销那就按照userId做一次扫描删除。如果Token量很大还可以用Redis的SCAN命令异步处理避免阻塞主线程。接口权限变更的场景也类似。角色信息虽然是保存在JWT里的但网关在鉴权时通常会把角色列表透传给下游业务服务。业务服务可以不用全信JWT里的角色而是在关键操作上去数据库重新查一次权限这样权限变更就能在更细粒度上即时生效。我的经验是高频低风险的接口用JWT里的角色低频高风险的接口比如支付、删除、导出一定要走库查权限。4.4 与其他分布式组件的配合搜索词里还有一批分布式相关的组件比如分布式事务、xxl-job、分布式缓存。这些虽然不直接属于OAuth2但在实际项目里会和权限校验互相影响。拿xxl-job举例。定时任务调业务接口时没有用户点击但接口又有权限保护。这时候就需要在任务调度平台或任务执行器里配置一个服务账号的clientId和clientSecret用OAuth2的客户端模式获取一个服务级别的Token然后在调用业务接口时带上这个Token。这个Token的scope建议保持最小权限只开放任务需要的那几个接口不要给它全部权限。拿分布式事务举例。事务链路里跨服务调用时同样需要把用户Token透传下去。用户先调A服务A服务再调B服务B服务要判断当前用户是否有权执行后续操作就必须在A服务调用B服务时把原始Token放入Feign请求头。如果不透传B服务看到的是服务间调用自己的客户端身份权限语义就变了。分布式缓存这块Token状态的存储本身就属于缓存设计的一部分。除了常规的TTL还需要考虑缓存穿透场景比如有人恶意伪造大量不存在的jti网关每次都去Redis查Key可能会给Redis造成压力。可以适当在网关层加布隆过滤器或本地空值缓存但一定要以安全为底线不能为了性能放弃一致性。5. 常见问题与排查思路实录5.1 401/403令牌格式错误、算法不匹配、公钥不同步出现401时先别急着调代码第一件事是打开网关或资源服务的日志看具体异常类型。我遇到过最多的几种情况是JwtException: JWT signature does not match。这种通常是授权服务器更换了签名密钥但资源服务还在用旧公钥或者配置的JWK Set地址没有刷新。解决办法是检查资源服务的jwk-set-uri是否还能拉到最新公钥必要时重启资源服务强制刷新。Invalid token: Token has expired。这种不需要惊慌属于正常的过期流程。客户端应该走刷新逻辑获取新Token但如果网关把过期Token直接拒绝返回401而前端没有实现刷新逻辑就会出现用户频繁掉线。我建议网关在返回401时附带错误码TOKEN_EXPIRED前端根据错误码自动触达刷新Token接口而不是让用户重新登录。JwtDecoders: Unable to resolve Configuration。一般是网络问题资源服务拉取JWK Set超时。建议在配置中心里配置好重试策略并且把认证服务的地址配置为内网地址。5.2 网关转发后用户信息丢失操作现象网关已经解析出userId放到请求头了但下游业务服务拿不到。排查后发现几种可能的原因。一种是网关所在的Netty服务默认会过滤掉某些自定义请求头需要在Gateway配置里加上自定义header的白名单。另一种是Feign调用时请求头默认不传递需要实现RequestInterceptor把X-User-Id和X-User-Roles复制到Feign的RequestTemplate里。还有一种是自己写顺手了在mutate请求头时覆盖了原有的Authorization头导致下游服务也拿不到原始Token。这里我建议在整个链路里统一约定网关解析出的用户信息统一放在X-User-Id和X-User-Roles这两个请求头脑业务服务只依赖这组头部不要再去解析原始Token。5.3 Token过期时间与Redis缓存不一致现象客户端明明显示Token没过期但Redis里已经没有对应记录了导致请求被拒。根源通常是两个地方写时间时遗漏了同步。一是签发Token时expiresIn写在JWT的Claims里但Redis的TTL设置成了别的时间二是刷新Token时新Token签发成功旧的Redis记录没有及时删除或者删除的是错误key。我的排查建议是先打印Redis里key的剩余TTL再解一下JWT看expire时间对比两个值是否一致。实际线上可接受的偏差是几秒以内如果偏差很大基本就是代码写死时间和Redis设置时间不匹配。修正方法也很简单——统一用一个常量控制TTL签发时同时给JWT和Redis赋值释放时同时处理新旧token对应记录。5.4 刷新Token失效用户被频繁要求重新登录这个问题的常见原因是refreshToken被旋转了。OAuth2授权码模式下每次刷新都会重新生成一个refreshToken旧refreshToken立即失效。如果前端并发刷新后发起的刷新请求拿到的还是旧refreshToken就会导致刷新失败。解决思路还是我之前说的分布式锁同时在前端做刷新互斥用一个全局Promise来保证同一时刻只有一个刷新请求在飞行。还有一种情况是认证服务重启后内存中的refreshToken记录丢失。如果注册客户端和已发放的refreshToken都放在内存那服务重启后所有refreshToken都会失效。生产环境一定要把已发放的refreshToken信息持久化到Redis或数据库客户端记录建议也放在Redis或数据库别用内存存储。6. 我踩过的坑与最后的建议在做分布式权限校验这个模块时我踩过最大的坑就是一开始过度设计。看到OAuth2就觉得一定要引入授权中心、资源服务、网关三层结果团队业务体量根本不需要这么多端点和角色维护成本直线上升。后来我把方案收敛成“网关统一鉴权 JWT Redis键控”之后不仅代码量大幅减少排查问题也清晰了很多。第二个经验是权限校验要分层不要指望网关卡住所有问题。网关适合做一些粗粒度的校验比如是否登录、Token是否有效、是否有基础访问权限。真正细粒度的权限比如只能操作自己部门的数据、只能看到自己的订单一定要在业务服务里做否则你会在网关里写出越来越复杂的路由规则最后变成谁也看不懂的灾难。第三个建议是日志和监控一定要提前埋好。分布式环境下用户一次请求会经过网关和多个业务服务没有traceId串起来的话定位“用户有权限但请求失败”这种问题会非常痛苦。至少要在网关过滤器里打印Token解析结果的日志标记出userId、jti、路径、结果状态同时把TraceId放进请求头透传。最后再说一个小技巧。开发环境调试OAuth2流程时经常遇到认证服务器、网关、前端三个服务端口不一致导致的重定向URL错误这时候不要只盯着后端日志先看浏览器开发者工具里的重定向链路确认callback地址是否与认证服务里配置的redirectUri完全一致包括端口和路径。大多数OAuth2调不通的问题最后都能溯源到URI不匹配而不是密钥配错或者JWT解析失败。分布式权限校验本质上是在分布式系统中重新回答“你是谁、你能做什么”这两个问题。想清楚Token怎么发、怎么存、怎么校验、怎么吊销再配合网关的集中处理和业务服务的方法级校验整个体系就能在Spring Cloud生态里稳定运转。这套方案我在多个项目里验证过效果也希望能帮你在自己的架构里少走几个弯路。