# Gateway Token 一致性与登录绑定
**本文引用的文件**
- [LoginRequestFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java)
- [StickyRouteFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java)
- [LoginResponseFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java)
- [TokenResolver.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java)
- [UserRouteService.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java)
- [UserRouteRepository.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java)
- [NodeSelector.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java)
- [GatewayAttributes.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/GatewayAttributes.java)
- [StickyUnavailableException.java](file://ai-gateway/src/main/java/com/zsjz/gateway/support/StickyUnavailableException.java)
- [GatewayErrorHandler.java](file://ai-gateway/src/main/java/com/zsjz/gateway/support/GatewayErrorHandler.java)
- [gateway.sql](file://sql/gateway.sql)
## 目录
1. [引言](#引言)
2. [项目结构与入口](#项目结构与入口)
3. [核心组件与职责](#核心组件与职责)
4. [系统架构总览](#系统架构总览)
5. [关键流程详解](#关键流程详解)
6. [依赖关系分析](#依赖关系分析)
7. [性能与一致性特征](#性能与一致性特征)
8. [常见失败场景与排查](#常见失败场景与排查)
9. [结论](#结论)
## 引言
本文聚焦 ai-gateway 中三个网关过滤器与相关支撑组件,解释以下问题:
- 客户端、Gateway、ai-server 之间 token 为什么必须保持一致;
- LoginRequestFilter 如何从登录请求中提取 username;
- StickyRouteFilter 如何根据 userId 或用户名选择 ai-server 节点并重写目标 URL;
- LoginResponseFilter 如何在登录成功后把用户与服务节点绑定写入数据库;
- 当用户绑定的节点 DOWN 时,为什么返回 503 而不是自动切换到其他节点;
- 登录流程时序图、常见失败场景及排查步骤。
本说明面向既需要理解代码实现,又希望把握整体设计意图的读者。
## 项目结构与入口
Gateway 层围绕 Spring Cloud Gateway 的全局过滤器机制构建。本次文档涉及的核心 Java 类位于 `com.zsjz.gateway.route` 包和 `com.zsjz.gateway.support` 包,数据模型定义在 SQL 脚本中。
```mermaid
graph TB
Client["客户端"] --> GW["Spring Cloud Gateway"]
GW --> LRF["LoginRequestFilter
提取 username"]
GW --> SRF["StickyRouteFilter
按 userId/username 选节点"]
GW --> LRSF["LoginResponseFilter
登录后写绑定与 token 缓存"]
SRF --> TR["TokenResolver
x-token → userId"]
SRF --> URS["UserRouteService
Redis + PostgreSQL 路由缓存"]
URS --> UR["UserRouteRepository
gateway_user_route"]
SRF --> NS["NodeSelector
健康节点轮询"]
GW --> ERR["GatewayErrorHandler
统一错误码"]
GW --> AI["ai-server 节点"]
TR --> Redis["Redis"]
URS --> Redis
```
**图表来源**
- [LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
- [TokenResolver.java:1-100](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L1-L100)
- [UserRouteService.java:1-117](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L1-L117)
- [UserRouteRepository.java:1-227](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L1-L227)
- [NodeSelector.java:1-45](file://ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java#L1-L45)
- [GatewayErrorHandler.java:1-98](file://ai-gateway/src/main/java/com/zsjz/gateway/support/GatewayErrorHandler.java#L1-L98)
**章节来源**
- [LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
## 核心组件与职责
| 组件 | 主要职责 | 关键行为 |
|---|---|---|
| LoginRequestFilter | 识别并预处理登录请求 | 解析请求体中的 username;改写 Accept-Encoding;转发原请求体 |
| StickyRouteFilter | 粘性路由决策与目标 URL 重写 | 登录请求用 username 查绑定或轮询候选;普通请求用 x-token 查 userId;校验节点可用性并设置 GATEWAY_REQUEST_URL_ATTR |
| LoginResponseFilter | 登录响应后处理 | 解析成功登录响应;调用 UserRouteService 绑定用户到节点;回填 token 到 Redis |
| TokenResolver | x-token 到 userId 的解析与缓存 | 优先读 gateway:token 键;未命中则调用 sa-token;登录成功后由响应过滤器回填 |
| UserRouteService | 用户路由两级缓存 | Redis 热路径缓存;PostgreSQL gateway_user_route 为事实来源;提供 bindIfAbsent |
| UserRouteRepository | 用户路由数据库访问 | 查询绑定;幂等插入;并发冲突由部分唯一索引裁决 |
| NodeSelector | 匿名或新用户健康节点轮询 | 仅对 enabled 且 isUp 的节点轮询;已绑定用户不改变其节点 |
| StickyUnavailableException | 粘性不可用异常 | 封装 HTTP 503 语义 |
| GatewayErrorHandler | 统一错误处理器 | 将 StickyUnavailableException 转为 503 JSON,连接失败转 502,其余转 500 |
**章节来源**
- [GatewayAttributes.java:1-31](file://ai-gateway/src/main/java/com/zsjz/gateway/route/GatewayAttributes.java#L1-L31)
- [StickyUnavailableException.java:1-25](file://ai-gateway/src/main/java/com/zsjz/gateway/support/StickyUnavailableException.java#L1-L25)
- [GatewayErrorHandler.java:1-98](file://ai-gateway/src/main/java/com/zsjz/gateway/support/GatewayErrorHandler.java#L1-L98)
## 系统架构总览
Gateway 不是业务逻辑中心,而是认证上下文、路由粘性与后端可达性的协调者。真实登录校验、token 签发由 ai-server 完成;Gateway 只负责“把请求送到正确的节点”,并在登录成功后维护“用户→节点”的映射。
```mermaid
sequenceDiagram
participant C as "客户端"
participant G as "Gateway"
participant A as "ai-server 节点"
participant DB as "PostgreSQL"
participant R as "Redis"
Note over C,A: 首次登录
C->>G: POST /服务前缀/登录路径
请求体含 username
G->>G: LoginRequestFilter 解析 username
G->>G: StickyRouteFilter 决定节点
alt 已有绑定
G->>DB: 查询 user_id/username 对应 node_id
else 新用户
G->>G: NodeSelector 轮询健康节点
end
G->>A: 转发登录请求
A-->>G: 登录成功 Result{code=200,data:{token,userId,username}}
G->>G: LoginResponseFilter 解析响应
G->>DB: bindIfAbsent(serviceId,userId,username,nodeId)
G->>R: cacheToken(serviceId,token,userId)
G-->>C: 原样透传登录响应
```
**图表来源**
- [LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
- [TokenResolver.java:1-100](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L1-L100)
- [UserRouteService.java:1-117](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L1-L117)
- [UserRouteRepository.java:1-227](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L1-L227)
- [NodeSelector.java:1-45](file://ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java#L1-L45)
## 关键流程详解
### LoginRequestFilter:从登录请求中提取 username
LoginRequestFilter 是一个优先级较高的全局过滤器。它只对“已注册服务的完整登录路径”生效,并且只处理 HTTP POST 请求。
处理要点:
1. 通过 GatewayRegistry 查找当前请求是否命中某个服务;
2. 如果是该服务的 loginFullPath,则读取整个请求体;
3. 使用 Jackson 解析 JSON,取出 username 字段;
4. 将 LOGIN_REQUEST 和 LOGIN_USERNAME 写入 ServerWebExchange 属性;
5. 把 Accept-Encoding 改为 identity,避免后端 gzip 压缩导致响应难以解析;
6. 重建请求并继续转发,不修改业务内容。
如果请求体为空、超过 64KB、非 JSON 或没有 username,它会记录日志并按匿名请求继续处理,由后端自行判断登录结果。
**章节来源**
- [LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
- [GatewayAttributes.java:1-31](file://ai-gateway/src/main/java/com/zsjz/gateway/route/GatewayAttributes.java#L1-L31)
### StickyRouteFilter:按 userId 选择 ai-server 节点并重写目标 URL
StickyRouteFilter 是粘性路由的核心,优先级为 10001,在 Spring Cloud Gateway 内部 RouteToRequestUrlFilter(10000)之后执行。它会根据“是否是登录请求”走两条分支。
#### 登录请求分支
- 先从 Exchange 属性中取 LOGIN_USERNAME;
- 通过 UserRouteService 查询 serviceId + username 对应的 nodeId;
- 若已绑定,直接使用该节点;
- 若未绑定,则由 NodeSelector 从健康节点中轮询一个候选节点;
- 注意:此时不会立即写库,绑定推迟到 LoginResponseFilter。
#### 普通请求分支
- 从请求头读取 x-token;
- 若为空,按匿名请求轮询健康节点;
- 若存在,通过 TokenResolver 解析出 userId;
- 再用 UserRouteService 查询 userId 对应的 nodeId;
- 若没找到绑定,且服务配置了 defaultNodeId,则尝试 bindIfAbsent 兜底绑定;
- 若仍无绑定,抛出 StickyUnavailableException,最终返回 503。
#### 节点校验与 URL 重写
无论登录还是普通请求,StickyRouteFilter 都会:
1. 检查选出的 nodeId 是否存在于 ServiceInfo 且启用;
2. 检查 healthRegistry.isUp(nodeId);
3. 把 SERVICE_ID、TARGET_NODE_ID 写入 Exchange 属性;
4. 计算 target URI = baseUrl + 原始 rawPath + 原始 rawQuery;
5. 设置 GATEWAY_REQUEST_URL_ATTR,使后续 NettyRoutingFilter 流式转发;
6. 在响应头添加 X-Gateway-Node 便于排障。
```mermaid
flowchart TD
Start(["进入 StickyRouteFilter"]) --> HasRoute{"是否命中路由"}
HasRoute -->|否| Next["跳过粘性逻辑"]
HasRoute -->|是| IsLogin{"是否登录请求"}
IsLogin -->|是| GetUser["取 LOGIN_USERNAME"]
GetUser --> BoundCheck{"是否有绑定节点"}
BoundCheck -->|有| UseBound["使用绑定节点"]
BoundCheck -->|无| PickCandidate["NodeSelector 轮询健康节点"]
IsLogin -->|否| GetToken["读取 x-token"]
GetToken --> TokenValid{"token 可解析?"}
TokenValid -->|否| Anonymous["匿名轮询"]
TokenValid -->|是| ResolveUserId["TokenResolver 解析 userId"]
ResolveUserId --> LookupBind{"是否绑定节点"}
LookupBind -->|是| UseBound
LookupBind -->|否| DefaultNode{"是否配置默认节点"}
DefaultNode -->|是| BindDefault["bindIfAbsent 到默认节点"]
DefaultNode -->|否| Error503["抛出粘性不可用异常"]
UseBound --> ValidateNode["校验节点启用与健康状态"]
PickCandidate --> ValidateNode
Anonymous --> ValidateNode
BindDefault --> ValidateNode
ValidateNode --> Rewrite["重写 GATEWAY_REQUEST_URL_ATTR"]
Rewrite --> End(["交给下游过滤器转发"])
Error503 --> End
```
**图表来源**
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [NodeSelector.java:1-45](file://ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java#L1-L45)
- [TokenResolver.java:1-100](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L1-L100)
- [UserRouteService.java:1-117](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L1-L117)
**章节来源**
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
### LoginResponseFilter:登录成功后绑定用户与服务节点
LoginResponseFilter 的优先级为 NettyWriteResponseFilter - 1,保证在响应写出之前捕获响应体。
处理流程:
1. 再次判断当前请求是否命中某个服务的 loginFullPath;
2. 装饰响应,收集最多 256KB 的响应体;
3. 等待链式过滤完成后,解析登录成功结构:code=200,data 中存在 token、userId、username;
4. 若满足条件,调用 UserRouteService.bindIfAbsent(serviceId, userId, username, chosenNodeId);
5. 同时调用 TokenResolver.cacheToken(serviceId, token, userId),写入 Redis;
6. 无论绑定成功与否,都不修改原始登录响应。
这里的关键是 chosenNodeId 来自 StickyRouteFilter 在请求阶段设置的 LOGIN_CHOSEN_NODE_ID。因此,新用户第一次登录会绑定到当时轮询到的健康节点;并发首次登录时,数据库部分唯一索引保证只有一个绑定生效。
**章节来源**
- [LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
- [GatewayAttributes.java:1-31](file://ai-gateway/src/main/java/com/zsjz/gateway/route/GatewayAttributes.java#L1-L31)
### 用户路由与 token 解析的数据模型
数据库表结构定义了 Gateway 的用户粘性路由基础:
- gateway_service:服务定义,包含 path_prefix、login_path、health_path、default_node_id;
- gateway_node:ai-server 节点,base_url 不含路径;
- gateway_user_route:用户到节点的绑定,支持按 user_id 或 username 唯一。
Redis 提供两级缓存:
- gateway:route:user:{serviceId}:{userId} → nodeId;
- gateway:route:name:{serviceId}:{lower(username)} → nodeId;
- gateway:token:{serviceId}:{token} → userId,TTL 24 小时。
```mermaid
erDiagram
GATEWAY_SERVICE {
varchar id PK
varchar name
varchar path_prefix UK
varchar login_path
varchar health_path
varchar default_node_id
smallint enabled
timestamp create_time
timestamp update_time
}
GATEWAY_NODE {
varchar id PK
varchar service_id FK
varchar name
varchar base_url
smallint enabled
varchar remark
timestamp create_time
timestamp update_time
}
GATEWAY_USER_ROUTE {
bigint id PK
varchar service_id FK
bigint user_id
varchar username
varchar node_id FK
timestamp create_time
timestamp update_time
}
GATEWAY_SERVICE ||--o{ GATEWAY_NODE : "包含"
GATEWAY_SERVICE ||--o{ GATEWAY_USER_ROUTE : "拥有绑定"
GATEWAY_NODE ||--o{ GATEWAY_USER_ROUTE : "被绑定"
```
**图表来源**
- [gateway.sql:1-107](file://sql/gateway.sql#L1-L107)
- [UserRouteService.java:1-117](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L1-L117)
- [TokenResolver.java:1-100](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L1-L100)
**章节来源**
- [UserRouteRepository.java:1-227](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L1-L227)
- [UserRouteService.java:1-117](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L1-L117)
- [gateway.sql:1-107](file://sql/gateway.sql#L1-L107)
## 依赖关系分析
```mermaid
classDiagram
class LoginRequestFilter {
+filter(exchange, chain) Mono
+parseUsername(body) String
-resolveService(exchange) ServiceInfo
}
class StickyRouteFilter {
+filter(exchange, chain) Mono
-decideForLogin(exchange, service) Mono
-decideForNormal(exchange, service) Mono
-route(exchange, chain, service, nodeId) Mono
+buildTargetUri(baseUrl, requestUri) URI
}
class LoginResponseFilter {
+filter(exchange, chain) Mono
-parseAndBind(serviceId, chosenNodeId, body) Mono
+parseLogin(body) LoginSuccess
}
class TokenResolver {
+resolveUserId(serviceId, token) Mono
+cacheToken(serviceId, token, userId) Mono
-resolveFromSaToken(token) Mono
}
class UserRouteService {
+findNodeIdByUserId(serviceId, userId) Mono
+findNodeIdByUsername(serviceId, username) Mono
+bindIfAbsent(serviceId, userId, username, nodeId) Mono
+evictUserCache(serviceId, userId, username) Mono
}
class UserRouteRepository {
+findNodeIdByUserId(...)
+findNodeIdByUsername(...)
+bindIfAbsent(...)
+deleteRoutesForUser(...)
}
class NodeSelector {
+select(service) NodeInfo
}
class StickyUnavailableException {
+httpStatus int
+serviceUnavailable(message) StickyUnavailableException
}
class GatewayErrorHandler {
+handle(exchange, error) Mono
}
LoginRequestFilter --> StickyRouteFilter : "传递 LOGIN_USERNAME"
StickyRouteFilter --> TokenResolver : "x-token → userId"
StickyRouteFilter --> UserRouteService : "查询/绑定节点"
StickyRouteFilter --> NodeSelector : "健康节点轮询"
LoginResponseFilter --> UserRouteService : "bindIfAbsent"
LoginResponseFilter --> TokenResolver : "cacheToken"
UserRouteService --> UserRouteRepository : "JDBC 访问"
StickyRouteFilter --> StickyUnavailableException : "不可用时抛出"
StickyUnavailableException --> GatewayErrorHandler : "统一转 503"
```
**图表来源**
- [LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
- [TokenResolver.java:1-100](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L1-L100)
- [UserRouteService.java:1-117](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L1-L117)
- [UserRouteRepository.java:1-227](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L1-L227)
- [NodeSelector.java:1-45](file://ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java#L1-L45)
- [StickyUnavailableException.java:1-25](file://ai-gateway/src/main/java/com/zsjz/gateway/support/StickyUnavailableException.java#L1-L25)
- [GatewayErrorHandler.java:1-98](file://ai-gateway/src/main/java/com/zsjz/gateway/support/GatewayErrorHandler.java#L1-L98)
**章节来源**
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [UserRouteService.java:1-117](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L1-L117)
## 性能与一致性特征
### 性能特性
- LoginRequestFilter 最多缓存 64KB 登录请求体,避免重复读取;
- LoginResponseFilter 最多缓存 256KB 登录响应体,超时或大响应会降级跳过绑定解析;
- UserRouteService 使用 Redis 作为热路径缓存,Redis 失败回源 PostgreSQL;
- TokenResolver 使用 Redis 缓存 token 到 userId 的映射,TTL 24 小时;
- 数据库读写放在 boundedElastic 调度器上,避免阻塞响应线程;
- 绑定操作使用 ON CONFLICT DO NOTHING 配合部分唯一索引,并发安全但只保证“首次写入者胜出”。
### 一致性约束
- token 一致性要求:客户端保存的 token、Gateway 缓存的 token、ai-server 中 sa-token 存储的 token 必须指向同一登录会话;
- 如果 Gateway 拿到的 token 无法解析出 userId,会被当作匿名请求,由 ai-server 返回 401 引导重新登录;
- 用户路由以 PostgreSQL gateway_user_route 为事实来源,Redis 只是加速层;
- 节点绑定一旦写入,不会因为另一个节点可用就自动切换。
**章节来源**
- [LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
- [LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
- [TokenResolver.java:1-100](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L1-L100)
- [UserRouteService.java:1-117](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L1-L117)
- [UserRouteRepository.java:1-227](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L1-L227)
## 常见失败场景与排查
### 未绑定节点
现象:
- 普通请求携带有效 token,但数据库中不存在该 userId 的绑定;
- 如果服务未配置 defaultNodeId,Gateway 返回 503;
- 如果配置了 defaultNodeId,Gateway 会尝试 bindIfAbsent 并绑定到默认节点。
原因:
- 存量用户从未登录过新 Gateway;
- 管理端解绑后未重新登录;
- 历史绑定被清理。
排查步骤:
1. 查看响应头 X-Gateway-Node 是否为空或异常;
2. 查询 gateway_user_route 是否缺少该 service_id 与 user_id 的记录;
3. 检查 gateway_service.default_node_id 是否配置;
4. 若需迁移存量用户,可使用导入逻辑将 sys_user 中未绑定用户批量绑定到指定节点。
**章节来源**
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [UserRouteRepository.java:1-227](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L1-L227)
- [gateway.sql:1-107](file://sql/gateway.sql#L1-L107)
### token 过期、被顶下线或伪造
现象:
- 普通请求返回类似 401 的错误;
- 客户端应引导重新登录;
- Gateway 本身不会自动刷新 token。
原因:
- TokenResolver 无法从 Redis 或 sa-token 解析出 userId;
- Gateway 把这种情况视为匿名请求,透传给 ai-server;
- ai-server 根据自身认证逻辑返回 401,提示重新登录。
排查步骤:
1. 检查 Redis 中是否存在 gateway:token:{serviceId}:{token};
2. 检查 ai-server 中 sa-token 是否仍认为该 token 有效;
3. 确认客户端是否使用了旧 token;
4. 登录后确认 LoginResponseFilter 是否成功写入 token 缓存。
**章节来源**
- [TokenResolver.java:1-100](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L1-L100)
- [LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
### 节点不可用或 DOWN
现象:
- 用户绑定的节点变为不可用;
- Gateway 返回 503;
- 不会自动切换到其他健康节点。
原因:
- StickyRouteFilter 明确校验 healthRegistry.isUp(nodeId);
- StickyUnavailableException.serviceUnavailable 固定返回 503;
- 设计目标是保护本地磁盘上的案件数据、附件和 Agent 记忆;
- 自动切换可能导致请求落到没有该用户数据的节点。
排查步骤:
1. 查看 Gateway 日志中是否出现“用户绑定的后端节点不可用”;
2. 检查 NodeHealthRegistry 中该节点状态;
3. 检查 gateway_node 中该节点是否启用;
4. 恢复节点后再重试;如需强制迁移用户,使用管理接口重绑。
**章节来源**
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [StickyUnavailableException.java:1-25](file://ai-gateway/src/main/java/com/zsjz/gateway/support/StickyUnavailableException.java#L1-L25)
- [GatewayErrorHandler.java:1-98](file://ai-gateway/src/main/java/com/zsjz/gateway/support/GatewayErrorHandler.java#L1-L98)
### 登录请求体无法解析
现象:
- 登录仍可继续,但不会按 username 做粘性绑定;
- 下次可解析的登录再补绑定。
原因:
- 请求体为空、超过 64KB、非 JSON 或缺少 username;
- LoginRequestFilter 故意不阻断请求,退化为匿名轮询。
排查步骤:
1. 检查前端发送的登录请求体是否为 JSON;
2. 检查是否包含 username 字段;
3. 检查请求体大小是否超过 64KB;
4. 查看 Gateway 日志中“登录请求 username 解析失败”的提示。
**章节来源**
- [LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
### 登录响应过大或绑定失败
现象:
- 登录仍然成功;
- 但用户可能没有被绑定到预期节点;
- 下次登录时会补绑定。
原因:
- LoginResponseFilter 最大只解析 256KB 响应体;
- 非成功登录结构不会触发绑定;
- 绑定或 token 缓存失败只记日志,不影响登录。
排查步骤:
1. 检查登录响应是否大于 256KB;
2. 检查响应结构是否包含 code=200、data.token、data.userId、data.username;
3. 查看 Gateway 日志中“登录响应超过 256KB,跳过绑定解析”;
4. 确认 Redis 中是否写入 token 缓存。
**章节来源**
- [LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
## 结论
Gateway 的粘性路由设计围绕三个关键点展开:
1. **token 一致性**:客户端、Gateway、ai-server 必须使用同一个 token;否则 Gateway 无法将其映射到 userId,只能按匿名请求处理。
2. **用户粘性绑定**:首次登录成功后,Gateway 把 userId 或 username 与选定节点绑定到 PostgreSQL,并通过 Redis 加速后续请求的路由。
3. **节点不可用不自动切换**:因为案件数据、附件和 Agent 记忆可能存储在节点本地磁盘,自动切换会造成数据不一致;因此 Gateway 显式返回 503,要求运维修复节点或手动迁移绑定。
这套机制在性能、一致性和可排障性之间做了平衡:Redis 减少数据库压力,PostgreSQL 提供最终一致性,StickyRouteFilter 保证请求始终落到有用户数据的节点,GatewayErrorHandler 提供清晰的错误语义。