Spring Cloud Gateway中SaToken的Same-Token校验失效如何解决？

Question

在Spring Cloud Gateway中集成SaToken实现Same-Token校验（即强制同一设备/浏览器会话内Token不可复用）时，常出现校验失效问题。根本原因在于：Gateway作为无状态网关，默认不保存客户端连接上下文（如User-Agent、IP指纹等），且SaToken的`SameTokenCheckFilter`依赖`HttpServletRequest`获取请求头与客户端特征，而WebFlux环境下的`ServerWebExchange`无法直接提供同步阻塞式请求属性；同时，若未正确配置`SaTokenConfigure`启用`setSameToken(true)`及`setSameTokenTimeout(1800)`，或未在全局过滤器中调用`StpUtil.checkSameToken()`，均会导致Same-Token机制形同虚设。此外，跨域、代理转发（如Nginx）可能剥离或篡改`X-Forwarded-For`/`User-Agent`，进一步破坏设备指纹一致性。该问题易引发Token劫持与会话冒用风险，需针对性增强上下文透传与校验时机控制。

Answer 1

```html

一、现象层：Same-Token校验“看似启用，实则失效”的典型表现

• 前端连续发起两次携带相同 Token 的请求（同一浏览器 Tab），网关未拦截第二请求；
• Postman 复用 Token 发起并发请求，全部通过鉴权，无重复使用拒绝日志；
• 日志中可见 StpUtil.getTokenValue() 正常返回，但 StpUtil.checkSameToken() 未抛出 NotLoginException 或 DisableServiceException；
• Redis 中 satoken:token:same:xxx key 持续缺失或 TTL 异常为 -1；
• 跨域请求（如前端 localhost:3000 → gateway）下 Same-Token 校验完全不触发。

二、架构层：Spring Cloud Gateway 与 SaToken 的运行时语义鸿沟

Gateway 基于 WebFlux（Reactor Netty），其 ServerWebExchange 是非阻塞、不可变、无 Servlet 容器上下文的抽象；而 SaToken 原生 SameTokenCheckFilter 依赖 HttpServletRequest 同步获取 getHeader("User-Agent")、getRemoteAddr() 等字段——二者在 I/O 模型、线程模型、上下文生命周期上存在根本性不兼容。

维度	传统 Spring MVC	Spring Cloud Gateway (WebFlux)
请求对象	HttpServletRequest（同步、可多次读取）	ServerHttpRequest（异步、body 流式不可重放）
客户端 IP 获取	request.getRemoteAddr()	需解析 X-Forwarded-For + X-Real-IP，且需网关显式透传
设备指纹构建	直接组合 UA + IP + Token	UA/IP 需从 headers 异步提取，且可能被 Nginx 截断

三、配置层：SaToken 启用 Same-Token 的必要但非充分条件

仅添加 @EnableSaToken 不足以激活 Same-Token。必须显式配置：

@Configuration
public class SaTokenConfig {
    @Bean
    public SaTokenConfigure getSaTokenConfigure() {
        return new SaTokenConfigure()
            .setSameToken(true)                    // ✅ 关键：开启 Same-Token 模式
            .setSameTokenTimeout(1800)             // ✅ 单位秒（30分钟），非毫秒！
            .setTokenName("Authorization")          // ⚠️ 若前端用 Bearer Token，需匹配 header key
            .setIsReadBody(true);                  // ✅ 允许读取 body 构建指纹（如含 device_id 字段）
    }
}

四、实现层：WebFlux 环境下 Same-Token 的正确校验时机与方式

不能依赖 Servlet Filter，必须使用 GlobalFilter，并在 filter 链中早于路由转发执行：

@Component
@Order(-100) // 优先级高于 RouteToRequestUrlFilter
public class SameTokenGlobalFilter implements GlobalFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String token = getTokenFromHeader(exchange);
        if (StrUtil.isNotBlank(token)) {
            try {
                // ✅ 在 WebFlux 上下文中安全调用（SaToken 5.3.0+ 已适配 Reactor）
                StpUtil.checkSameToken();
            } catch (DisableServiceException e) {
                return Mono.error(new ResponseStatusException(HttpStatus.FORBIDDEN, "Token 已被其他设备使用"));
            }
        }
        return chain.filter(exchange);
    }
}

五、基础设施层：代理链路对设备指纹的破坏与修复方案

graph LR
  A[Client] -->|UA/IP stripped| B[Nginx]
  B -->|X-Forwarded-For missing| C[Gateway]
  C --> D[Auth Service]
  style B fill:#ff9999,stroke:#333
  style C fill:#99ccff,stroke:#333

修复措施：

• Nginx 配置强制透传：proxy_set_header X-Forwarded-For $remote_addr;（禁用 $proxy_add_x_forwarded_for，避免伪造）；
• Gateway 添加预处理过滤器，标准化 IP 提取逻辑（支持多级代理）；
• 前端主动上报加密设备指纹（如 WebCrypto API 生成的 device_fingerprint），写入请求头 X-Device-FP，规避 UA/IP 不稳定问题。

六、增强层：生产级 Same-Token 的高可用加固策略

单一 UA+IP 易受代理、CDN、移动端网络切换影响，建议组合策略：

1. 分级指纹：主指纹（X-Device-FP）+ 备用指纹（User-Agent + X-Forwarded-For 哈希）；
2. Redis 分片存储：按 token_prefix 分片，防止单实例瓶颈；
3. 异步刷新机制：每次合法请求后，异步更新 Redis 中该 Token 的最新指纹与时间戳；
4. 审计告警：监听 SameTokenDisableEvent，推送企业微信/钉钉告警并记录原始请求全量 headers。

七、验证层：端到端 Same-Token 效果验证清单

验证项	预期结果	失败定位点
同一 Chrome Tab 连续发 2 次相同 Token	第2次返回 403	GlobalFilter 是否生效？Redis key 是否写入？
Chrome + Firefox 同时用同一账号登录	后登录设备踢前设备	setSameTokenTimeout 是否生效？事件监听是否注册？
Nginx 后置时发起跨域请求	仍能准确识别设备差异	X-Forwarded-For 是否透传？UA 是否被 CORS strip？

```