本文引用的文件
本仓库的 ai-gateway 模块是一个基于 Spring Cloud Gateway、WebFlux 和 Netty 的用户粘性转发网关。它的核心职责不是复制后端业务逻辑,而是保证“同一用户的请求始终落到同一台 ai-server 节点”。这是因为案件数据源、附件、Agent 记忆等数据落在各节点的本地磁盘或 JVM 内存中,普通无状态负载均衡会把请求打散到没有数据的机器上。
网关的基础设施层由应用入口、跨域配置、响应式 WebClient 配置、请求 ID 注入、全局异常处理和统一错误语义组成;业务转发则由登录预处理、登录响应后处理、令牌解析、用户路由缓存以及粘性路由过滤器共同支撑。
网关模块采用按职责分层的组织方式:
config:Spring 配置类,负责 CORS、WebClient、属性扫描。support:横切基础设施,包括请求 ID、全局异常处理器、统一错误语义。route:粘性路由主流程,包括登录请求预处理、登录响应后处理、令牌解析、用户路由服务、粘性路由过滤器。registry:服务与节点注册表、健康检查、配置仓库(用于粘性决策)。admin:管理接口及鉴权。sql/gateway.sql:启动时自动执行的幂等建表脚本。
graph TB
subgraph "网关基础设施"
App["GatewayApplication"]
Cors["CorsConfig"]
Wc["WebClientConfig"]
Rid["RequestIdFilter"]
Err["GatewayErrorHandler"]
Sue["StickyUnavailableException"]
end
subgraph "粘性路由"
Lrf["LoginRequestFilter"]
Lrpf["LoginResponseFilter"]
Tr["TokenResolver"]
Urs["UserRouteService"]
Srf["StickyRouteFilter"]
end
App --> Cors
App --> Wc
App --> Rid
App --> Err
App --> Srf
Srf --> Lrf
Srf --> Lrpf
Srf --> Tr
Srf --> Urs
Err --> Sue
图示来源
章节来源
本节聚焦文档目标中的六个基础设施组件,并说明它们如何共同支撑粘性路由、管理接口和业务转发。
| 组件 | 主要职责 | 对粘性路由的影响 |
|---|---|---|
GatewayApplication |
应用启动入口,启用调度与配置属性扫描 | 提供网关运行上下文,使注册表、过滤器、错误处理器等 Bean 生效 |
CorsConfig |
可选网关层跨域处理 | 默认关闭,避免与后端跨域头重复;开启时可暴露 X-Gateway-Node 等头部 |
WebClientConfig |
为探活专用 WebClient 设置连接超时与响应超时 | 不承载业务转发,只影响节点健康检查 |
RequestIdFilter |
透传或生成 X-Request-Id |
让一次完整请求在网关、后端、日志中可串联追踪 |
GatewayErrorHandler |
统一捕获并转换异常为 JSON 错误体 | 把粘性不可用、上游失败、内部错误映射到明确 HTTP 状态码 |
StickyUnavailableException |
表示粘性路由无法继续处理 | 携带自定义 HTTP 状态码,通常对应 503,但不切换节点 |
章节来源
网关的请求路径大致分为三类:
LoginRequestFilter 解析用户名并标记为登录请求,再由 StickyRouteFilter 决定是命中已有绑定还是轮询候选节点;成功后由 LoginResponseFilter 写入用户路由和 token 缓存。x-token 解析 userId,再查用户路由缓存或数据库,最终粘到已绑定的节点;若未绑定且存在默认节点,则尝试兜底绑定。管理请求:走 /gateway/admin/**,由管理员鉴权和 IP 白名单控制,变更服务、节点、用户路由后会刷新注册表。
sequenceDiagram
participant Client as "客户端"
participant Gw as "网关"
participant LoginReq as "LoginRequestFilter"
participant Sticky as "StickyRouteFilter"
participant Backend as "ai-server 节点"
participant LoginResp as "LoginResponseFilter"
Client->>Gw: POST /js/a/auth/login
Gw->>LoginReq: 解析 username,标记登录请求
LoginReq-->>Gw: 原样转发请求
Gw->>Sticky: 选择绑定节点或候选节点
Sticky-->>Backend: 流式转发
Backend-->>Sticky: 登录响应
Sticky-->>Gw: 透传响应
Gw->>LoginResp: 捕获成功登录结构
LoginResp->>Gw: 写用户绑定与 token 缓存
LoginResp-->>Client: 返回原始登录响应
图示来源
GatewayApplication 使用 @SpringBootApplication 装配 Spring Boot,并通过 @EnableScheduling 启用定时任务,例如健康检查轮询和实例间对账。@ConfigurationPropertiesScan 会扫描配置属性,供 GatewayProperties 等配置类读取。
它本身不包含业务逻辑,但决定了整个网关容器的启动范围:过滤器、错误处理器、注册表、管理控制器、调度器都会在这个上下文中生效。
章节来源
CorsConfig 默认关闭,只有当 gateway.cors.enabled=true 时才注册 CorsWebFilter。默认关闭的原因是后端已经实现了全局跨域处理;如果网关也输出 Access-Control-Allow-Origin,浏览器会收到重复响应头并拒绝响应。
当需要网关收口跨域时,该配置允许所有方法和所有请求头,允许凭证模式为关闭,并显式暴露以下响应头:
X-Gateway-Node:当前转发的后端节点标识Content-Disposition:用于附件下载等场景X-Request-Id:便于前端和链路日志关联
flowchart TD
Start["是否启用 gateway.cors.enabled"] -->|否| Passthrough["透传后端跨域响应头"]
Start -->|是| Build["构建网关层 CorsWebFilter"]
Build --> AllowOrigins["允许来源模式"]
Build --> AllowHeaders["允许全部请求头"]
Build --> AllowMethods["允许全部方法"]
Build --> Credentials["不允许凭据跨域"]
Build --> Expose["暴露 X-Gateway-Node / Content-Disposition / X-Request-Id"]
AllowOrigins --> End["注册 /** 规则"]
AllowHeaders --> End
AllowMethods --> End
Credentials --> End
Expose --> End
图示来源
章节来源
WebClientConfig 创建的是 healthWebClient,专用于节点健康检查。它从 GatewayProperties 读取探活超时时间,并设置为 Reactor Netty 的 TCP 连接超时和 WebClient 响应超时。
需要注意:这个 WebClient 并不承载业务转发。业务请求走 Spring Cloud Gateway 内部的 HttpClient;这里只是避免健康检查复用业务通道,从而让探活行为可控、可观测。
章节来源
RequestIdFilter 是一个 WebFilter,在所有其他过滤器之前执行。它优先使用客户端传来的 X-Request-Id;如果没有,就生成一个 UUID。请求 ID 同时写入:
ServerWebExchange 的属性键 gateway.requestIdX-Request-Id这样,粘性路由过滤器、全局异常处理器、后端日志都可以用同一个请求 ID 串联排查。
flowchart TD
Enter["进入 RequestIdFilter"] --> Read["读取请求头 X-Request-Id"]
Read --> Has{"是否存在非空白值?"}
Has -->|是| UseExisting["使用客户端提供的请求 ID"]
Has -->|否| Generate["生成 UUID 作为请求 ID"]
UseExisting --> SetAttr["写入 exchange 属性 gateway.requestId"]
Generate --> SetAttr
SetAttr --> SetHeader["设置响应头 X-Request-Id"]
SetHeader --> Next["继续过滤器链"]
图示来源
章节来源
GatewayErrorHandler 实现 ErrorWebExceptionHandler,优先级高于多数 Spring 默认错误处理器。它根据异常类型决定 HTTP 状态码和消息:
| 异常类型 | 状态码 | 含义 |
|---|---|---|
StickyUnavailableException |
来自异常的 HTTP 状态码,默认 503 | 粘性路由不可用,不切换节点 |
ResponseStatusException |
使用其状态码,5xx 记录警告日志 | 框架或业务主动抛出的响应状态异常 |
| 上游连接错误或超时 | 502 | 后端节点连接失败、TCP 超时、Netty 连接超时 |
通用 TimeoutException |
502 | 上层响应超时 |
| 其他异常 | 500 | 网关内部错误 |
它还会判断响应是否已提交。对于 SSE 等长连接,一旦开始写入响应体,就不应强行改写状态码;此时只记录日志,让底层 Netty 按既有连接语义断开。
flowchart TD
Enter["handle(异常)"] --> Committed{"响应是否已提交?"}
Committed -->|是| Rethrow["抛出异常,交由 Netty 断开连接"]
Committed -->|否| Classify["分类异常类型"]
Classify --> Sticky{"StickyUnavailableException?"}
Sticky -->|是| Map503["映射 sticky 状态码,默认 503"]
Sticky -->|否| Rse{"ResponseStatusException?"}
Rse -->|是| MapRse["映射其状态码,5xx 记警告日志"]
Rse -->|否| Upstream{"上游连接错误或超时?"}
Upstream -->|是| Map502Upstream["返回 502 连接失败"]
Upstream -->|否| Timeout{"TimeoutException?"}
Timeout -->|是| Map502Timeout["返回 502 响应超时"]
Timeout -->|否| Map500["返回 500 内部错误"]
Map503 --> WriteJson["写 JSON {code,message,data}"]
MapRse --> WriteJson
Map502Upstream --> WriteJson
Map502Timeout --> WriteJson
Map500 --> WriteJson
图示来源
章节来源
StickyUnavailableException 是一个运行时异常,封装了自定义 HTTP 状态码和人类可读消息。工厂方法 serviceUnavailable 默认返回 503。
它的设计目标是表达“粘性路由不可用”,而不是普通的网络故障。粘性路由不可用的一个重要语义是:不自动切换到其他节点。因为不同节点拥有不同的本地数据和内存状态,盲目切换只会把请求送到没有该用户数据的机器。
章节来源
粘性路由的核心依赖链如下:
classDiagram
class GatewayApplication
class CorsConfig
class WebClientConfig
class RequestIdFilter
class GatewayErrorHandler
class StickyUnavailableException
class StickyRouteFilter
class LoginRequestFilter
class LoginResponseFilter
class TokenResolver
class UserRouteService
class GatewayAttributes
GatewayApplication --> StickyRouteFilter : "启动后启用"
GatewayApplication --> GatewayErrorHandler : "启动后启用"
StickyRouteFilter --> StickyUnavailableException : "抛出粘性不可用"
StickyRouteFilter --> LoginRequestFilter : "依赖登录标记"
StickyRouteFilter --> LoginResponseFilter : "依赖登录响应后处理"
StickyRouteFilter --> TokenResolver : "解析 x-token"
StickyRouteFilter --> UserRouteService : "查询/绑定用户路由"
StickyRouteFilter --> GatewayAttributes : "读写内部属性"
LoginRequestFilter --> GatewayAttributes : "写入 LOGIN_REQUEST / LOGIN_USERNAME"
LoginResponseFilter --> GatewayAttributes : "读取 SERVICE_ID / LOGIN_CHOSEN_NODE_ID"
GatewayErrorHandler --> StickyUnavailableException : "识别粘性异常"
RequestIdFilter --> GatewayAttributes : "写入 REQUEST_ID"
图示来源
网关运行在 Spring WebFlux 和 Netty 之上,因此必须遵循响应式编程和非阻塞原则。
ReactiveStringRedisTemplate 配合 Schedulers.boundedElastic() 完成,避免在 Netty 事件循环线程上执行阻塞 SQL。boundedElastic 调度器。WebClient,避免和业务转发共享同一通道。TokenResolver 调用 StpUtil.getLoginIdByToken 时使用 boundedElastic,因为 sa-token 可能涉及阻塞 Redis 访问。UserRouteService 的数据库回源和绑定操作也使用 boundedElastic。LoginResponseFilter 的解析和绑定以 fire-and-forget 方式订阅,避免客户端断连取消传播中断数据库写操作。GatewayErrorHandler 在响应已提交时不再改写状态码,而是抛出异常,让 Netty 按既有连接语义断开。这对 SSE、流式响应、Range 下载很重要。Content-Disposition,便于附件下载和长连接场景中正确识别响应头。Accept-Encoding 改为 identity,以便 LoginResponseFilter 能正确解析响应体。WebClientConfig 设置的连接超时和响应超时仅用于探活。业务转发由 Spring Cloud Gateway 管理,不应误以为修改这里就能调大上传、SSE 或大文件下载的超时。章节来源
StickyUnavailableException 与 StickyRouteFilter 共同定义了粘性路由下 503 的多种语义。这些语义的关键共性是:503 不代表临时网络抖动,而是代表“不能按粘性策略继续转发”。
| 场景 | 触发位置 | 503 含义 | 典型排查方向 |
|---|---|---|---|
| 服务不存在 | StickyRouteFilter.filter |
命中的服务未加载或未注册 | 检查 gateway_service.path_prefix、管理接口是否成功写入 |
| 服务停用 | StickyRouteFilter.filter |
服务已存在但 enabled=false |
管理接口查看服务状态 |
| 无可用节点 | decideForLogin、anonymousNode |
服务有配置但没有健康节点 | 检查节点 base_url、防火墙、后端进程、健康检查 |
| 绑定节点不可用 | route |
用户绑定的节点 enabled=false 或健康检查 DOWN |
管理接口查看节点状态,恢复后仍保持绑定 |
| 用户未绑定节点 | bindToDefaultNode |
用户登录后仍未绑定,且没有默认节点 | 检查 gateway_service.default_node_id 和用户路由表 |
| 用户已绑定但节点不存在或停用 | route |
绑定记录指向的节点被删除或停用 | 管理接口解绑或重绑 |
flowchart TD
Start["粘性路由决策"] --> ServiceCheck{"服务存在且启用?"}
ServiceCheck -->|否| NoService["503:服务不存在或已停用"]
ServiceCheck -->|是| IsLogin{"是否为登录请求?"}
IsLogin -->|是| LoginPath["查用户名绑定 → 未绑定则轮询候选"]
LoginPath --> Candidate{"有候选节点?"}
Candidate -->|否| NoCandidate["503:服务当前没有可用节点"]
Candidate -->|是| RouteStep["校验绑定节点"]
IsLogin -->|否| NormalPath["x-token 解析 userId → 查绑定 → 无绑定则默认节点兜底"]
NormalPath --> DefaultCheck{"有默认节点?"}
DefaultCheck -->|否| NoBind["503:用户未绑定节点"]
DefaultCheck -->|是| BindTry["尝试 bindIfAbsent"]
BindTry --> RouteStep
RouteStep --> NodeValid{"节点存在且启用?"}
NodeValid -->|否| NodeDisabled["503:用户绑定的节点不存在或已停用"]
NodeValid --> HealthCheck{"健康检查 UP?"}
HealthCheck -->|否| NodeDown["503:用户绑定的后端节点不可用"]
HealthCheck -->|是| Forward["重写 URL 并转发"]
图示来源
CorsFilter。gateway.cors.enabled=true,否则会出现重复 Access-Control-Allow-Origin。allowCredentials=false。X-Gateway-Node、Content-Disposition、X-Request-Id。章节来源
GatewayProperties.healthCheck.timeout 是否合理。WebClient 使用的是 WebClientConfig 创建的 Bean,而不是业务转发通道。章节来源
GatewayErrorHandler 已被 Spring 扫描并注册。章节来源
RequestIdFilter 已注册为组件并被 Spring 扫描。X-Request-Id;若为空,网关会自动生成。gateway.requestId 属性。X-Request-Id。章节来源
/gateway/admin/status 查看服务、节点、健康状态、绑定数量。gateway_service.default_node_id 是否正确。gateway_user_route 表是否有用户绑定记录。章节来源
service.loginFullPath。{code:200, data:{token, userId, username}}。gateway:token:{serviceId}:{token} 是否写入 Redis。gateway_user_route 是否新增用户绑定。章节来源
网关基础设施层的关键价值在于:为粘性路由提供稳定的启动上下文、可配置的跨域边界、可控的探活 WebClient、可追踪的请求 ID、统一的全局异常出口,以及明确的“粘性不可用”错误语义。
其中,503 不是简单的“系统忙”,而是一个业务语义信号:当前请求不能按用户粘性策略继续转发。它可能表示服务不存在、服务停用、无可用节点、绑定节点不可用,或者用户未绑定节点。无论哪种情况,网关都不应自动切换到其他节点,以避免把请求打到没有该用户数据的机器上。
在实际运维中,应优先结合 X-Request-Id、管理接口状态、PostgreSQL 路由表和 Redis 缓存进行定位;在网络层则需特别注意 Netty/WebFlux 的非阻塞特性、SSE 长连接兼容性和 WebClient 超时的适用范围。