本文引用的文件
本文聚焦 Spring Cloud Gateway 中登录相关的全局过滤器链,解释 LoginRequestFilter、StickyRouteFilter 与 LoginResponseFilter 如何协作,完成“用户 → ai-server 节点”的粘性绑定。重点包括:
该机制位于网关模块 ai-gateway 的路由层,核心类集中在 com.zsjz.gateway.route 包下,配合 sql/gateway.sql 中的持久化模型完成用户与节点的绑定关系管理。
graph TB
Client["客户端"] --> GW["Spring Cloud Gateway"]
subgraph "网关路由层"
LRF["LoginRequestFilter<br/>order=9999"]
SRV["StickyRouteFilter<br/>order=10001"]
LRSF["LoginResponseFilter<br/>order=NettyWriteResponseFilter-1"]
TR["TokenResolver"]
URS["UserRouteService"]
UR["UserRouteRepository"]
end
subgraph "后端服务"
AIS["ai-server"]
end
DB[("PostgreSQL")]
Client --> LRF
LRF --> SRV
SRV --> AIS
AIS --> DB
SRV --> TR
SRV --> URS
LRSF --> URS
URS --> UR
UR --> DB
图示来源
章节来源
LoginRequestFilter:拦截配置路径上的登录 POST 请求,缓存并解析请求体中的 username,写入 GatewayAttributes.LOGIN_REQUEST 与 LOGIN_USERNAME,并将 Accept-Encoding 改为 identity,避免后续响应被 gzip 压缩导致解析失败。StickyRouteFilter:根据是否登录请求走不同分支。登录请求进入 decideForLogin,优先查已绑定节点;未绑定时轮询健康节点得到“候选节点”,仅写入 LOGIN_CHOSEN_NODE_ID,不写数据库。LoginResponseFilter:在登录响应写出后解析成功结果,根据 LOGIN_CHOSEN_NODE_ID 调用 UserRouteService.bindIfAbsent 完成持久化,并把 token → userId 写入 Redis 缓存。TokenResolver:提供 x-token → userId 解析,优先读本地 Redis 缓存,回退到 sa-token;登录成功后回填缓存,TTL 为 24 小时。UserRouteService / UserRouteRepository:封装用户路由的 Redis + PostgreSQL 两级读写,保证并发首次登录通过数据库唯一索引裁决。章节来源
登录粘性路由的设计目标是:同一用户在同一个 service 下始终访问同一个 ai-server 节点,因为业务数据可能落在节点本地磁盘或内存中,不能随意漂移。
flowchart TD
A["收到请求"] --> B{"是否为登录路径?"}
B -->|否| C["按普通请求处理<br/>x-token → userId → 粘性节点"]
B -->|是| D["LoginRequestFilter 解析 username<br/>写入 LOGIN_REQUEST 与 LOGIN_USERNAME"]
D --> E["StickyRouteFilter.decideForLogin"]
E --> F{"已绑定节点?"}
F -->|是| G["使用已绑定节点"]
F -->|否| H["轮询健康节点作为候选节点<br/>写入 LOGIN_CHOSEN_NODE_ID"]
G --> I["转发到 ai-server"]
H --> I
I --> J{"响应是否登录成功?"}
J -->|是| K["LoginResponseFilter 落库 bindIfAbsent<br/>并缓存 token"]
J -->|否| L["跳过绑定,原样透传响应"]
C --> M["后续请求按 token 粘性路由"]
图示来源
该过滤器仅在匹配服务注册中的完整登录路径且方法为 POST 时生效。它读取整个请求体(最多 64KB),尝试从 JSON 中取 username。无论解析成功与否都不阻断请求:解析失败时按匿名请求继续,让后端自行校验登录。
关键行为:
GatewayAttributes.LOGIN_REQUEST = true;GatewayAttributes.LOGIN_USERNAME,可能为空;Accept-Encoding: identity;ServerHttpRequestDecorator 重建请求体,确保下游能再次消费;将请求交给后续过滤器链。
flowchart TD
Start(["进入 LoginRequestFilter"]) --> CheckPath["检查是否为服务的 loginFullPath 且为 POST"]
CheckPath -->|否| PassThrough["直接放行,不修改请求"]
CheckPath -->|是| ReadBody["缓存请求体(≤64KB)"]
ReadBody --> ParseUsername["解析 username"]
ParseUsername --> SetAttrs["写入 LOGIN_REQUEST=true<br/>写入 LOGIN_USERNAME"]
SetAttrs --> RewriteHeader["改写 Accept-Encoding 为 identity"]
RewriteHeader --> RebuildBody["装饰请求体以便下游再次读取"]
RebuildBody --> Next["调用 chain.filter(exchange)"]
图示来源
章节来源
该过滤器在所有路由 URL 计算之后执行,负责把请求重写到具体 ai-server 节点。它读取 GatewayAttributes.LOGIN_REQUEST 决定走登录分支还是普通分支。
登录分支逻辑:
LOGIN_USERNAME 获取用户名;UserRouteService.findNodeIdByUsername 查询是否已有绑定;nodeSelector.select(service) 选择一个健康节点作为“候选节点”,写入 LOGIN_CHOSEN_NODE_ID,但不写库;route() 校验节点存在、启用且健康,再重写 GATEWAY_REQUEST_URL_ATTR 为目标节点 URL。普通分支逻辑:
x-token 或 token 解析失败:按匿名请求轮询健康节点;有 x-token:解析出 userId 后查找绑定节点;若无绑定则尝试绑定到服务配置的默认节点;仍无绑定则返回 503。
classDiagram
class StickyRouteFilter {
+int getOrder()
+filter(exchange, chain) Mono<Void>
-decideForLogin(exchange, service) Mono<String>
-decideForNormal(exchange, service) Mono<String>
-bindToDefaultNode(service, userId) Mono<String>
-anonymousNode(service) Mono<String>
-route(exchange, chain, service, nodeId) Mono<Void>
}
class TokenResolver {
+resolveUserId(serviceId, token) Mono<Long>
+cacheToken(serviceId, token, userId) Mono<Boolean>
}
class UserRouteService {
+findNodeIdByUserId(serviceId, userId) Mono<String>
+findNodeIdByUsername(serviceId, username) Mono<String>
+bindIfAbsent(serviceId, userId, username, nodeId) Mono<String>
}
StickyRouteFilter --> TokenResolver : "解析 x-token"
StickyRouteFilter --> UserRouteService : "查询/绑定用户路由"
图示来源
章节来源
该过滤器在 Netty 写出响应之前拦截响应体,收集最多 256KB 的数据,判断是否为登录成功响应。成功条件包括:响应体为 JSON、code=200、data.userId 非空、data.username 非空。
如果命中成功结构:
GatewayAttributes 取出 SERVICE_ID 与 LOGIN_CHOSEN_NODE_ID;UserRouteService.bindIfAbsent(serviceId, userId, username, chosenNodeId);TokenResolver.cacheToken(serviceId, token, userId);所有异常仅记录警告,不影响本次登录响应透传。
sequenceDiagram
participant GW as "网关"
participant LRSF as "LoginResponseFilter"
participant URS as "UserRouteService"
participant TR as "TokenResolver"
participant DB as "PostgreSQL"
GW->>LRSF: 登录响应写出前拦截
LRSF->>LRSF: 收集响应体 ≤256KB
LRSF->>LRSF: 解析 code=200 且 data.userId、data.username 有效
LRSF->>URS: bindIfAbsent(serviceId, userId, username, chosenNodeId)
URS->>DB: 唯一索引裁决 INSERT ... ON CONFLICT DO NOTHING
DB-->>URS: 返回生效节点
URS-->>LRSF: 返回 effective nodeId
LRSF->>TR: cacheToken(serviceId, token, userId)
TR-->>LRSF: 写入 Redis 缓存
LRSF-->>GW: 继续写出原始响应
图示来源
章节来源
原因有三点:
业务状态尚未确认
LoginRequestFilter 只拿到 username,但此时 ai-server 还未验证密码或账号状态。若在请求阶段就写库,可能出现“用户名合法但登录失败”的脏绑定。
需要知道最终 token 和 userId
只有登录成功响应中才包含 token、userId、username。LoginResponseFilter.parseLogin 要求 code=200 且 data.userId、data.username 有效,才能进行绑定与 token 缓存。
解耦请求转发与持久化
LoginResponseFilter 以 fire-and-forget 方式触发绑定,即使数据库或 Redis 写入失败也不影响客户端收到的登录响应。这符合“绑定失败可下次补”的容错设计。
章节来源
网关侧主要依赖以下外部能力:
GatewayRegistry:根据请求路径找到服务信息,包括 loginFullPath、defaultNodeId、节点列表;NodeHealthRegistry / NodeSelector:选择健康节点;ReactiveStringRedisTemplate:缓存 token、用户路由;JdbcTemplate:直连 PostgreSQL 读写用户路由;Sa-Token:兜底解析已存在的 token。
graph LR
LRF["LoginRequestFilter"] --> REG["GatewayRegistry"]
SRV["StickyRouteFilter"] --> REG
SRV --> NH["NodeHealthRegistry"]
SRV --> NS["NodeSelector"]
SRV --> TR["TokenResolver"]
SRV --> URS["UserRouteService"]
LRSF["LoginResponseFilter"] --> URS
LRSF --> TR
URS --> REDIS["Redis"]
URS --> UR["UserRouteRepository"]
UR --> PG["PostgreSQL"]
图示来源
章节来源
boundedElastic 调度器,避免阻塞网关主事件循环。ON CONFLICT DO NOTHING 与唯一索引保证并发安全,返回实际生效节点。章节来源
下图展示客户端、网关、ai-server、PostgreSQL 之间的典型交互。
sequenceDiagram
participant Client as "客户端"
participant GW as "Gateway"
participant LRF as "LoginRequestFilter"
participant SRV as "StickyRouteFilter"
participant AIS as "ai-server"
participant LRSF as "LoginResponseFilter"
participant URS as "UserRouteService"
participant TR as "TokenResolver"
participant PG as "PostgreSQL"
Client->>GW: POST /path_prefix/login
GW->>LRF: 全局过滤器 order=9999
LRF->>LRF: 解析 username,写入 LOGIN_REQUEST、LOGIN_USERNAME
LRF->>SRV: 继续过滤器链
SRV->>SRV: decideForLogin
SRV->>URS: findNodeIdByUsername(username)
alt 用户未绑定
SRV->>SRV: 轮询健康节点,写入 LOGIN_CHOSEN_NODE_ID
else 用户已绑定
SRV-->>SRV: 使用已绑定节点
end
SRV->>AIS: 转发到目标节点
AIS->>PG: 校验账号/密码等业务
AIS-->>GW: 返回 Result{code=200, data.token, data.userId, data.username}
GW->>LRSF: 响应写出前拦截
LRSF->>LRSF: 解析成功结构
LRSF->>URS: bindIfAbsent(serviceId, userId, username, chosenNodeId)
URS->>PG: 插入 gateway_user_route(唯一索引裁决)
PG-->>URS: 返回生效节点
LRSF->>TR: cacheToken(serviceId, token, userId)
TR-->>Client: 透传原始登录响应
Note over Client,GW: 后续请求携带 x-token,按粘性路由访问同一节点
图示来源
用户名冲突由数据库唯一索引处理。gateway_user_route 上对 (service_id, lower(username)) 建立唯一索引,多个网关实例同时插入时会由 PostgreSQL 裁决赢家。UserRouteRepository.bindIfAbsent 在冲突后重新读取赢家节点,返回实际生效节点。
flowchart TD
A["两个网关同时登录同一用户名"] --> B["各自选出候选节点"]
B --> C["并发 INSERT ... ON CONFLICT DO NOTHING"]
C --> D["PostgreSQL 唯一索引裁决赢家"]
D --> E["read back winner node"]
E --> F["返回 effective nodeId"]
图示来源
章节来源
如果用户已经绑定到某个节点,StickyRouteFilter.decideForLogin 会直接复用已绑定节点,不再轮询新节点。bindIfAbsent 也会发现已有路由并返回既有节点,因此重复登录不会漂移节点。
章节来源
当用户被强制踢下线或单端登录顶掉旧会话时,Sa-Token 中的 token 失效。TokenResolver.resolveFromSaToken 会返回空值,StickyRouteFilter.decideForNormal 将其视为解析失败,按匿名请求处理,最终由 ai-server 返回 401,引导客户端重新登录。
flowchart TD
A["旧 token 被顶掉或过期"] --> B["TokenResolver 解析失败"]
B --> C["StickyRouteFilter 按匿名请求处理"]
C --> D["转发到 ai-server"]
D --> E["ai-server 返回 code=401"]
E --> F["客户端重新登录"]
图示来源
章节来源
LoginResponseFilter.parseLogin 只对 code=200 且满足字段条件的响应进行绑定。密码错误、账号禁用、字段缺失等情况不会触发 bindIfAbsent,也不会写库。
章节来源
LoginRequestFilter.parseUsername 对空体、超限体、非 JSON、缺少 username 字段的情况返回 null,此时 LOGIN_USERNAME 为空,StickyRouteFilter 按匿名轮询处理,由 ai-server 自行校验登录。
章节来源
登录后仍然随机跳转节点
检查 GatewayAttributes.LOGIN_CHOSEN_NODE_ID 是否在 StickyRouteFilter 中写入,以及 LoginResponseFilter 是否成功解析登录成功响应。关注日志中“登录响应超过 KB”“登录响应未命中成功结构”等提示。
token 无法解析
检查 Redis 中 gateway:token:{serviceId}:{token} 是否存在;若不存在,检查 sa-token 共享 Redis 是否可用。注意 TokenResolver 在缓存写入失败时仍允许正确请求通过。
用户被绑定到预期之外节点
检查是否存在并发首次登录,查看 LoginResponseFilter 日志中“并发首次登录:用户...实际绑定到已有节点”。这是唯一索引裁决的正常现象。
节点不可用返回 503
StickyRouteFilter.route() 会拒绝 DOWN 或停用的节点,并返回 503。这不是自动切换,因为业务数据可能在节点本地磁盘。
章节来源
登录粘性路由通过三层过滤器协作实现:LoginRequestFilter 在请求阶段提取用户名并标记登录请求;StickyRouteFilter 在路由阶段决定是否使用已绑定节点或生成候选节点;LoginResponseFilter 在响应阶段完成持久化与 token 缓存。该设计避免了在未确认登录成功前写库,同时通过 Redis 缓存与数据库唯一索引兼顾性能与一致性。对于用户名冲突、重复登录、token 失效等边界场景,系统采用延迟落库、匿名降级、唯一索引裁决等方式保证整体可用性。