# 多节点扩展与负载均衡
**本文引用的文件**
- [StickyRouteFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java)
- [LoginRequestFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java)
- [LoginResponseFilter.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.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)
- [TokenResolver.java](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.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)
- [GatewayRegistry.java](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java)
- [NodeHealthRegistry.java](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java)
- [HealthChecker.java](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/HealthChecker.java)
- [ServiceInfo.java](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/ServiceInfo.java)
- [NodeInfo.java](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeInfo.java)
- [StickyUnavailableException.java](file://ai-gateway/src/main/java/com/zsjz/gateway/support/StickyUnavailableException.java)
- [gateway.sql](file://sql/gateway.sql)
## 目录
1. [引言](#引言)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能与水平扩展](#性能与水平扩展)
8. [监控与排障](#监控与排障)
9. [结论](#结论)
## 引言
本方案为 ai-server 提供多节点扩展与粘性负载均衡。核心约束是:同一用户的请求必须始终路由到同一个 ai-server 节点,避免跨节点访问本地磁盘、附件、DuckDB 案件数据以及会话状态不一致。网关层不实现传统意义上的“自动故障转移”,而是通过“用户 → 节点”绑定 + 健康检查 + 登录绑定机制,在绑定节点不可用时返回 503,由运维或上层重试控制切换。
## 项目结构
代码位于两个主要子模块中:
- ai-gateway:Spring Cloud Gateway 实现的粘性网关,负责服务发现、节点健康检查、用户粘性路由、登录前后处理、Redis 缓存等。
- sql:定义网关使用的 PostgreSQL 表 gateway_service、gateway_node、gateway_user_route,作为服务注册与粘性绑定的事实来源。
```mermaid
graph TB
subgraph "网关层 ai-gateway"
LRF["LoginRequestFilter
解析登录用户名"]
SRF["StickyRouteFilter
粘性路由决策与 URL 重写"]
LResF["LoginResponseFilter
登录成功后绑定节点并缓存 token"]
URS["UserRouteService
用户路由 Redis+PG 读写"]
URRepo["UserRouteRepository
JDBC 访问 gateway_user_route"]
TR["TokenResolver
x-token → userId"]
NSel["NodeSelector
匿名/新用户轮询"]
Reg["GatewayRegistry
服务/节点内存快照"]
HReg["NodeHealthRegistry
节点 UP/DOWN 状态"]
HC["HealthChecker
定时探活"]
end
subgraph "数据存储"
PG["PostgreSQL
gateway_service / gateway_node / gateway_user_route"]
Redis["Redis
token 缓存 / 路由缓存"]
end
subgraph "后端节点"
A1["ai-server 节点 1"]
A2["ai-server 节点 2"]
An["ai-server 节点 n"]
end
LRF --> SRF
SRF --> URS
SRF --> TR
SRF --> NSel
LResF --> URS
LResF --> TR
URS --> URRepo
URS --> Redis
TR --> Redis
TR -->|"sa-token"| Redis
Reg --> PG
HC --> Reg
HC --> HReg
SRF --> Reg
SRF --> HReg
SRF --> A1
SRF --> A2
SRF --> An
```
**图示来源**
- [StickyRouteFilter.java:41-179](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L41-L179)
- [LoginRequestFilter.java:38-119](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L38-L119)
- [LoginResponseFilter.java:41-175](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L41-L175)
- [UserRouteService.java:25-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L25-L116)
- [UserRouteRepository.java:17-200](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L17-L200)
- [TokenResolver.java:25-99](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L25-L99)
- [NodeSelector.java:18-44](file://ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java#L18-L44)
- [GatewayRegistry.java:17-115](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java#L17-L115)
- [NodeHealthRegistry.java:10-67](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java#L10-L67)
- [HealthChecker.java:17-61](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/HealthChecker.java#L17-L61)
- [gateway.sql:1-107](file://sql/gateway.sql#L1-L107)
**章节来源**
- [StickyRouteFilter.java:1-180](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L1-L180)
- [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)
- [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)
- [gateway.sql:1-107](file://sql/gateway.sql#L1-L107)
## 核心组件
- StickyRouteFilter:粘性路由核心过滤器,从 x-token 解析 userId,查找绑定节点,校验节点可用,重写目标 URL,并附加 X-Gateway-Node 响应头。
- LoginRequestFilter:登录前预处理,解析 username,标记登录请求,允许下游 StickyRouteFilter 按 username 查找已有绑定。
- LoginResponseFilter:登录成功后把用户绑定到 StickyRouteFilter 选出的节点,并把 token → userId 写入 Redis 缓存。
- UserRouteService:用户路由的 Redis 两级缓存与 PostgreSQL 事实源读写。
- UserRouteRepository:JDBC 访问 gateway_user_route 及 sys_user,实现幂等绑定和并发安全。
- TokenResolver:x-token → userId 解析,优先走网关 token 缓存,未命中时走 sa-token。
- NodeSelector:匿名请求和新用户选择健康节点的轮询器。
- GatewayRegistry:服务与节点配置内存快照,从 PostgreSQL 加载,支持 YAML 播种和多实例对账。
- NodeHealthRegistry:每个网关实例维护的节点健康状态。
- HealthChecker:定时调用 ai-server 健康端点,更新 NodeHealthRegistry。
- StickyUnavailableException:粘性路由不可用时的统一异常,HTTP 状态码固定为 503。
**章节来源**
- [StickyRouteFilter.java:41-179](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L41-L179)
- [LoginRequestFilter.java:38-119](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L38-L119)
- [LoginResponseFilter.java:41-175](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L41-L175)
- [UserRouteService.java:25-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L25-L116)
- [UserRouteRepository.java:17-200](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L17-L200)
- [TokenResolver.java:25-99](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L25-L99)
- [NodeSelector.java:18-44](file://ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java#L18-L44)
- [GatewayRegistry.java:17-115](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java#L17-L115)
- [NodeHealthRegistry.java:10-67](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java#L10-L67)
- [HealthChecker.java:17-61](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/HealthChecker.java#L17-L61)
- [StickyUnavailableException.java:7-24](file://ai-gateway/src/main/java/com/zsjz/gateway/support/StickyUnavailableException.java#L7-L24)
## 架构总览
粘性路由不是简单的负载均衡,而是“用户亲和 + 有限可用性”的组合:
- 匿名用户和无绑定用户按健康节点轮询。
- 已登录用户通过 userId 或 username 绑定到具体节点。
- 绑定节点 DOWN 时返回 503,不自动切换到其他节点。
- 服务与节点配置存储在 PostgreSQL,网关启动时可从 YAML 播种。
- 健康检查只判断进程存活,不深入检查 PG/Redis/ES;业务侧应保证单节点内本地资源一致。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant GW as "ai-gateway"
participant AuthSrv as "ai-server 认证接口"
participant DB as "PostgreSQL"
participant R as "Redis"
Client->>GW: "POST {pathPrefix}{loginPath}"
GW->>GW: "LoginRequestFilter 解析 username"
GW->>GW: "StickyRouteFilter 决定节点"
GW->>AuthSrv: "转发登录请求"
AuthSrv-->>GW: "Result"
GW->>GW: "LoginResponseFilter 解析成功响应"
GW->>DB: "bindIfAbsent(serviceId, userId, username, nodeId)"
GW->>R: "cacheToken(serviceId, token, userId)"
GW-->>Client: "透传登录响应 + X-Gateway-Node"
```
**图示来源**
- [LoginRequestFilter.java:38-119](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L38-L119)
- [StickyRouteFilter.java:60-179](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L60-L179)
- [LoginResponseFilter.java:60-175](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L60-L175)
- [UserRouteService.java:73-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L73-L116)
- [TokenResolver.java:43-99](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L43-L99)
## 详细组件分析
### 粘性路由 StickyRouteFilter
StickyRouteFilter 是粘性路由的核心。其职责包括:
1. 根据路由元数据获取 serviceId。
2. 判断是否为登录请求。
3. 登录请求:先查 username 是否已有绑定;若无,则从健康节点中选择一个候选节点,但不写库。
4. 普通请求:从 x-token 解析 userId;若 userId 有效但无绑定,尝试绑定到 defaultNodeId;若仍无绑定,返回 503。
5. token 解析失败时,按匿名请求处理,让后端返回 401。
6. 最终校验选定节点是否存在、启用且健康;通过后重写 GATEWAY_REQUEST_URL_ATTR,并添加 X-Gateway-Node 响应头。
```mermaid
flowchart TD
Start(["进入 StickyRouteFilter"]) --> GetRoute["获取 Route 与 serviceId"]
GetRoute --> IsLogin{"是否登录请求?"}
IsLogin -->|是| DecideLogin["按 username 查找绑定
未绑定则轮询健康节点"]
IsLogin -->|否| ResolveToken["从 x-token 解析 userId"]
ResolveToken --> HasUserId{"是否解析出 userId?"}
HasUserId -->|否| Anonymous["匿名轮询健康节点"]
HasUserId -->|是| FindBound["查找用户绑定节点"]
FindBound --> BoundExists{"是否有绑定?"}
BoundExists -->|是| UseBound["使用绑定节点"]
BoundExists -->|否| DefaultNode{"service 是否配置默认节点?"}
DefaultNode -->|是| BindDefault["bindIfAbsent(userId, defaultNodeId)"]
DefaultNode -->|否| ErrorNoBind["抛出 503:用户未绑定节点"]
BindDefault --> UseBound
DecideLogin --> SelectNode["轮询健康节点"]
SelectNode --> UseBound
Anonymous --> UseBound
UseBound --> ValidateNode["校验节点存在/启用/健康"]
ValidateNode --> Valid{"节点可用?"}
Valid -->|否| ErrorDown["抛出 503:绑定节点不可用"]
Valid -->|是| Rewrite["重写目标 URI + 设置 X-Gateway-Node"]
Rewrite --> End(["继续下游过滤链"])
```
**图示来源**
- [StickyRouteFilter.java:60-179](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L60-L179)
- [StickyUnavailableException.java:16-24](file://ai-gateway/src/main/java/com/zsjz/gateway/support/StickyUnavailableException.java#L16-L24)
关键设计点:
- order 为 10001,位于 Spring Cloud Gateway 内置 RouteToRequestUrlFilter 之后,用于重写实际目标 URL。
- 目标 URL 使用 baseUrl + requestUri.getRawPath() + requestUri.getRawQuery() 拼接,避免二次编码。
- 所有“不可用”场景统一抛出 StickyUnavailableException.serviceUnavailable,HTTP 状态码为 503。
**章节来源**
- [StickyRouteFilter.java:41-179](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L41-L179)
- [StickyUnavailableException.java:7-24](file://ai-gateway/src/main/java/com/zsjz/gateway/support/StickyUnavailableException.java#L7-L24)
### 登录请求处理 LoginRequestFilter
LoginRequestFilter 只在配置的 loginFullPath 上生效,流程如下:
1. 通过 GatewayRegistry 找到对应 ServiceInfo。
2. 合并读取请求体,限制最大 64KB。
3. 解析 JSON body 中的 username。
4. 设置 GatewayAttributes.LOGIN_REQUEST 和 LOGIN_USERNAME。
5. 将 Accept-Encoding 改为 identity,避免后端 gzip 导致响应无法被 LoginResponseFilter 解析。
6. 重建请求体,确保下游仍能消费原始 body。
```mermaid
flowchart TD
Enter(["进入 LoginRequestFilter"]) --> MatchLogin["匹配 pathPrefix + loginPath"]
MatchLogin -->|不匹配| PassThrough["直接透传"]
MatchLogin -->|匹配| ReadBody["读取请求体(≤64KB)"]
ReadBody --> ParseUsername["解析 JSON 中的 username"]
ParseUsername --> SetAttrs["设置 LOGIN_REQUEST 与 LOGIN_USERNAME"]
SetAttrs --> FixEncoding["Accept-Encoding 改为 identity"]
FixEncoding --> RebuildBody["重建可重复读取的请求体"]
RebuildBody --> Next["进入下游过滤器"]
```
**图示来源**
- [LoginRequestFilter.java:38-119](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L38-L119)
**章节来源**
- [LoginRequestFilter.java:1-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L1-L120)
### 登录响应绑定 LoginResponseFilter
LoginResponseFilter 在响应写出阶段拦截登录响应:
1. 仅对 pathPrefix + loginPath 的 POST 响应处理。
2. 收集响应体,上限 256KB。
3. 解析 Result,要求 code=200,data.userId 非空,data.username 非空。
4. 从 exchange 属性中取出 StickyRouteFilter 设置的 SERVICE_ID 和 LOGIN_CHOSEN_NODE_ID。
5. 调用 userRouteService.bindIfAbsent 做幂等绑定。
6. 调用 tokenResolver.cacheToken 写入 token → userId 缓存。
7. 无论绑定成功与否,都不修改原始响应体。
```mermaid
sequenceDiagram
participant GW as "ai-gateway"
participant LResF as "LoginResponseFilter"
participant URS as "UserRouteService"
participant TR as "TokenResolver"
participant PG as "PostgreSQL"
participant R as "Redis"
GW->>LResF: "捕获登录响应"
LResF->>LResF: "解析 code=200 + data.token/userId/username"
LResF->>URS: "bindIfAbsent(serviceId, userId, username, chosenNodeId)"
URS->>PG: "INSERT ON CONFLICT DO NOTHING"
PG-->>URS: "生效节点"
URS->>R: "写入路由缓存 key"
LResF->>TR: "cacheToken(serviceId, token, userId)"
TR->>R: "写入 gateway:token:{serviceId}:{token}"
LResF-->>GW: "透传原始响应"
```
**图示来源**
- [LoginResponseFilter.java:60-175](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L60-L175)
- [UserRouteService.java:73-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L73-L116)
- [TokenResolver.java:43-99](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L43-L99)
**章节来源**
- [LoginResponseFilter.java:1-176](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L1-L176)
### 用户路由服务与持久化
UserRouteService 提供两类能力:
- 读路径:先从 Redis 缓存读取,未命中再查 PostgreSQL,然后回写缓存。
- 写路径:通过 UserRouteRepository 执行幂等绑定,成功后同时写 userId 和 username 对应的缓存键。
UserRouteRepository 使用 JdbcTemplate 直接操作 PostgreSQL:
- findNodeIdByUserId 和 findNodeIdByUsername 查询绑定。
- bindIfAbsent 先查已有绑定,再 INSERT ON CONFLICT DO NOTHING,最后读回赢家,保证并发下唯一性。
- importExisting 支持存量用户批量导入到某个节点。
数据库模型由 gateway.sql 定义:
- gateway_service:服务定义,包含 path_prefix、login_path、health_path、default_node_id。
- gateway_node:节点定义,base_url 不含 context-path。
- gateway_user_route:用户粘性绑定,支持 user_id 或 username 唯一绑定,含部分唯一索引。
```mermaid
erDiagram
GATEWAY_SERVICE ||--o{ GATEWAY_NODE : "包含"
GATEWAY_SERVICE ||--o{ GATEWAY_USER_ROUTE : "拥有"
GATEWAY_NODE ||--o{ GATEWAY_USER_ROUTE : "被绑定"
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 {
bigserial id PK
varchar service_id FK
bigint user_id
varchar username
varchar node_id FK
timestamp create_time
timestamp update_time
}
```
**图示来源**
- [gateway.sql:1-107](file://sql/gateway.sql#L1-L107)
**章节来源**
- [UserRouteService.java:25-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L25-L116)
- [UserRouteRepository.java:17-200](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L17-L200)
- [gateway.sql:1-107](file://sql/gateway.sql#L1-L107)
### Token 解析与缓存
TokenResolver 负责将 x-token 转为 userId:
1. 如果 token 为空,直接返回空。
2. 从 Redis 键 gateway:token:{serviceId}:{token} 读取 userId。
3. 缓存未命中时调用 StpUtil.getLoginIdByToken 从 sa-token 共享 Redis 解析。
4. 解析成功后写回缓存,TTL 24 小时。
5. 解析失败返回空 Mono,由 StickyRouteFilter 按匿名请求处理。
```mermaid
flowchart TD
In(["TokenResolver.resolveUserId"]) --> CheckToken{"token 是否为空?"}
CheckToken -->|是| Empty["返回空"]
CheckToken -->|否| CacheRead["读取 gateway:token:{serviceId}:{token}"]
CacheRead --> Hit{"缓存命中?"}
Hit -->|是| ReturnCache["返回 userId"]
Hit -->|否| SaToken["调用 StpUtil.getLoginIdByToken"]
SaToken --> ParseOk{"解析成功?"}
ParseOk -->|否| Empty
ParseOk -->|是| WriteCache["写入 Redis,TTL 24h"]
WriteCache --> ReturnParsed["返回 userId"]
```
**图示来源**
- [TokenResolver.java:43-99](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L43-L99)
**章节来源**
- [TokenResolver.java:1-100](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L1-L100)
### 节点选择与轮询
NodeSelector 为匿名请求和新用户选择节点:
- 只考虑 enabled=true 且 NodeHealthRegistry.isUp=true 的节点。
- 使用基于 serviceId 的 AtomicInteger 轮询。
- 没有可用节点时返回 null,由调用方返回 503。
注意:NodeSelector 不影响已绑定用户;已绑定用户即使 DOWN 也不会被换掉。
**章节来源**
- [NodeSelector.java:18-44](file://ai-gateway/src/main/java/com/zsjz/gateway/route/NodeSelector.java#L18-L44)
### 服务注册中心与配置同步
GatewayRegistry 维护服务与节点的内存快照:
- 启动时若 gateway_service 为空,则从 YAML 播种。
- reload() 从 PostgreSQL 重新加载,变化时发布 RefreshRoutesEvent。
- 每 10 秒轮询一次,实现多网关实例配置收敛。
- ServiceInfo.matchesPath 支持最长前缀匹配。
```mermaid
classDiagram
class GatewayRegistry {
-List~ServiceInfo~ services
-boolean initialized
+init()
+seedFromYamlIfNeeded()
+reload() boolean
+pollForChanges()
+getServices() List
+getService(id) Optional
+findServiceByPath(rawPath) Optional
}
class ServiceInfo {
+String id
+String name
+String pathPrefix
+String loginPath
+String healthPath
+String defaultNodeId
+boolean enabled
+List~NodeInfo~ nodes
+loginFullPath() String
+matchesPath(rawPath) boolean
+findNode(nodeId) Optional
}
class NodeInfo {
+String id
+String serviceId
+String name
+String baseUrl
+boolean enabled
+String remark
}
GatewayRegistry --> ServiceInfo : "管理"
ServiceInfo --> NodeInfo : "包含"
```
**图示来源**
- [GatewayRegistry.java:17-115](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java#L17-L115)
- [ServiceInfo.java:7-31](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/ServiceInfo.java#L7-L31)
- [NodeInfo.java:5-12](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeInfo.java#L5-L12)
**章节来源**
- [GatewayRegistry.java:17-115](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java#L17-L115)
- [ServiceInfo.java:7-31](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/ServiceInfo.java#L7-L31)
- [NodeInfo.java:5-12](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeInfo.java#L5-L12)
### 节点健康检查与健康状态
HealthChecker 定时对所有启用节点发起 GET {baseUrl}{healthPath}:
- 成功时记录 UP,连续失败达到阈值记录 DOWN。
- 1 次成功立即恢复 UP。
- UNKNOWN 初始状态视为可用,避免刚启动时全部匿名请求 503。
NodeHealthRegistry 是每个网关实例的本地健康状态表,不跨实例同步。
**章节来源**
- [HealthChecker.java:17-61](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/HealthChecker.java#L17-L61)
- [NodeHealthRegistry.java:10-67](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java#L10-L67)
## 依赖关系分析
粘性路由相关组件的依赖关系如下:
```mermaid
graph LR
StickyRouteFilter --> GatewayRegistry
StickyRouteFilter --> NodeHealthRegistry
StickyRouteFilter --> NodeSelector
StickyRouteFilter --> TokenResolver
StickyRouteFilter --> UserRouteService
LoginResponseFilter --> UserRouteService
LoginResponseFilter --> TokenResolver
LoginResponseFilter --> GatewayRegistry
UserRouteService --> UserRouteRepository
UserRouteService --> Redis
TokenResolver --> Redis
HealthChecker --> GatewayRegistry
HealthChecker --> NodeHealthRegistry
GatewayRegistry --> PostgreSQL
UserRouteRepository --> PostgreSQL
```
**图示来源**
- [StickyRouteFilter.java:41-179](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L41-L179)
- [LoginResponseFilter.java:41-175](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L41-L175)
- [UserRouteService.java:25-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L25-L116)
- [UserRouteRepository.java:17-200](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L17-L200)
- [TokenResolver.java:25-99](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L25-L99)
- [HealthChecker.java:17-61](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/HealthChecker.java#L17-L61)
- [GatewayRegistry.java:17-115](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java#L17-L115)
**章节来源**
- [StickyRouteFilter.java:41-179](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L41-L179)
- [UserRouteService.java:25-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L25-L116)
- [TokenResolver.java:25-99](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L25-L99)
- [GatewayRegistry.java:17-115](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/GatewayRegistry.java#L17-L115)
## 性能与水平扩展
### 多节点部署拓扑
推荐拓扑:
- 多个 ai-server 实例,每个实例持有本地磁盘、附件、DuckDB 案件数据、Agent 会话。
- 多个 ai-server 实例共享 PostgreSQL/pgvector、Redis、Elasticsearch、Neo4j 等外部存储。
- 单个或集群式 ai-gateway 做粘性转发,前端只暴露网关入口。
```mermaid
graph TB
FE["前端 / 客户端"]
GW1["ai-gateway 实例 1"]
GW2["ai-gateway 实例 2"]
AS1["ai-server 节点 1"]
AS2["ai-server 节点 2"]
AS3["ai-server 节点 3"]
PG["PostgreSQL / pgvector"]
RD["Redis"]
ES["Elasticsearch"]
N4["Neo4j"]
FE --> GW1
FE --> GW2
GW1 --> AS1
GW1 --> AS2
GW1 --> AS3
GW2 --> AS1
GW2 --> AS2
GW2 --> AS3
AS1 --> PG
AS2 --> PG
AS3 --> PG
AS1 --> RD
AS2 --> RD
AS3 --> RD
AS1 --> ES
AS2 --> ES
AS3 --> ES
AS1 --> N4
AS2 --> N4
AS3 --> N4
```
该图是概念部署图,不映射单一源码文件,因此不提供图示来源。
### 水平扩展建议
- 节点扩容策略
- 新增 ai-server 节点后,先在 PostgreSQL 中登记 gateway_node,并在 gateway_service 中关联。
- 存量用户可通过管理接口重绑,或使用 importExisting 将未绑定用户迁移到新节点。
- 新用户首次登录由 NodeSelector 轮询健康节点,后续由 sticky 绑定保持亲和。
- 登录顶号与会话释放
- 当账号被顶下线或踢下线时,Sa-Token 会失效,TokenResolver 解析不到 userId,StickyRouteFilter 退化为匿名轮询,后端返回 401 引导重新登录。
- 被顶下线用户下次登录可能落到新节点,这是粘性路由的预期行为;如需强制原节点,需通过管理接口重新绑定。
- DuckDB 最大案件数与内存比例
- 由于案件数据在节点本地,扩容时必须避免把一个逻辑用户的多个案件分散到不同节点。
- 建议按用户维度分配 ai-server 节点,并结合 DuckDB 最大案件数和 JVM 堆内存调整,防止单节点内存打满。
- 向量索引重建成本
- pgvector 向量索引重建通常较重,建议在低峰期按节点分批执行,避免同时影响多个 ai-server。
- Elasticsearch 与 Neo4j 共享配置
- ES/Neo4j 是共享后端,不应成为粘性路由的限制因素;但要注意连接池、线程池、索引刷新频率对多节点并发访问的影响。
- Redis 热点键
- 路由缓存 key 粒度为 serviceId + userId 或 serviceId + username,token 缓存 key 粒度为 serviceId + token。
- 大用户量下应避免把所有流量集中到一个 Redis 节点;建议使用分片或集群模式,并注意连接池容量。
[本节为通用扩展建议,不直接分析具体源码行]
## 监控与排障
### 节点健康状态查询
- 关注 NodeHealthRegistry 的状态变化日志,特别是 DOWN 状态输出。
- 确认 HealthChecker 是否正常调度,健康端点是否正确返回 2xx。
- 若节点持续 DOWN,检查 ai-server 进程、健康端点、网络连通性。
**章节来源**
- [NodeHealthRegistry.java:10-67](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/NodeHealthRegistry.java#L10-L67)
- [HealthChecker.java:17-61](file://ai-gateway/src/main/java/com/zsjz/gateway/registry/HealthChecker.java#L17-L61)
### 粘性路由失效
常见表现:同一用户请求落到不同节点。
排查要点:
1. 检查 StickyRouteFilter 是否拿到 route 和 serviceId。
2. 检查 x-token 是否能被 TokenResolver 正确解析为 userId。
3. 检查 Redis 中 gateway:token:{serviceId}:{token} 是否存在。
4. 检查 PostgreSQL 中 gateway_user_route 是否有 serviceId + userId 或 serviceId + username 的记录。
5. 检查是否误用了匿名轮询分支。
**章节来源**
- [StickyRouteFilter.java:60-179](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L60-L179)
- [TokenResolver.java:43-99](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L43-L99)
- [UserRouteRepository.java:37-70](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L37-L70)
- [gateway.sql:60-107](file://sql/gateway.sql#L60-L107)
### 登录绑定错乱
常见表现:登录后下一次请求路由到不同节点。
排查要点:
1. 检查 LoginRequestFilter 是否正确解析 username。
2. 检查 LoginResponseFilter 是否正确识别 loginFullPath。
3. 检查 LoginResponseFilter 是否成功解析 code=200 且 data.userId、data.username 非空。
4. 检查 UserRouteService.bindIfAbsent 是否落库成功。
5. 检查是否有多台网关实例竞争绑定,但唯一索引应保证一致性。
**章节来源**
- [LoginRequestFilter.java:38-119](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginRequestFilter.java#L38-L119)
- [LoginResponseFilter.java:60-175](file://ai-gateway/src/main/java/com/zsjz/gateway/route/LoginResponseFilter.java#L60-L175)
- [UserRouteRepository.java:84-120](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L84-L120)
### Redis 热点键
风险点:
- gateway:token:{serviceId}:{token} 在高并发下可能成为热点。
- gateway:route:user:{serviceId}:{userId} 和 gateway:route:name:{serviceId}:{username} 也可能热点。
定位方法:
1. 观察 Redis 连接池使用率和慢查询。
2. 统计高频 token 和用户 ID 的请求分布。
3. 如 Redis 成为瓶颈,考虑增加分片、提升单机性能,或评估是否将 token 校验更多下沉到 ai-server。
**章节来源**
- [TokenResolver.java:43-99](file://ai-gateway/src/main/java/com/zsjz/gateway/route/TokenResolver.java#L43-L99)
- [UserRouteService.java:41-116](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L41-L116)
### 数据库连接池耗尽
风险点:
- UserRouteRepository 使用 JdbcTemplate,阻塞 IO 放在 boundedElastic 执行。
- 高并发下 PostgreSQL 连接过多可能导致连接池耗尽。
定位方法:
1. 监控 PostgreSQL 活跃连接数、慢查询、锁等待。
2. 检查 JDBC 连接池大小、超时配置。
3. 减少频繁的用户路由查询,避免在热路径上重复查库。
4. 对存量用户导入使用 batch 方式,避免大量小事务。
**章节来源**
- [UserRouteRepository.java:17-200](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteRepository.java#L17-L200)
- [UserRouteService.java:41-72](file://ai-gateway/src/main/java/com/zsjz/gateway/route/UserRouteService.java#L41-L72)
### 绑定节点 DOWN 的处理
当前实现明确不自动切换:
- StickyRouteFilter 校验节点健康状态,DOWN 时抛出 503。
- StickyUnavailableException.serviceUnavailable 统一返回 HTTP 503。
- 这不是 bug,而是为了避免跨节点访问本地磁盘和会话不一致。
修复思路:
- 运维层面:尽快恢复节点或手动迁移用户绑定。
- 应用层面:若确实需要自动故障转移,应在业务层引入跨节点状态同步,但这会显著改变系统语义。
**章节来源**
- [StickyRouteFilter.java:120-179](file://ai-gateway/src/main/java/com/zsjz/gateway/route/StickyRouteFilter.java#L120-L179)
- [StickyUnavailableException.java:7-24](file://ai-gateway/src/main/java/com/zsjz/gateway/support/StickyUnavailableException.java#L7-L24)
## 结论
本方案以“用户 → 节点”绑定为核心,结合登录前后处理器、Redis 缓存、PostgreSQL 持久化和健康检查,实现 ai-server 的多节点粘性扩展。其关键约束是:绑定节点不可用时返回 503,不自动切换,以保证本地磁盘和会话一致性。生产扩展时应重点关注 Redis 热点、数据库连接池、DuckDB 内存占用、向量索引重建成本,以及 ES/Neo4j 共享资源的并发压力。治理粘性路由问题应从 token 解析、用户绑定、服务配置、节点健康四个维度逐步定位。