本文引用的文件
本文面向网关后端 PostgreSQL 中的三类网关表,目标是明确其数据结构、约束、索引和业务语义,并说明这些表如何支撑:
/gateway/admin/** 管理服务、节点和用户绑定。本设计适用于多台 ai-server 部署场景:每个节点拥有独立本地磁盘(DuckDB、附件、Agent 产物等),因此不能做普通无状态负载均衡,必须把同一用户的请求固定转发到其所属节点。
章节来源
网关模块 ai-gateway 是独立的 Spring Boot + Spring Cloud Gateway 应用,默认监听 8080 端口;业务后端 ai-server 仍运行在 8980 端口。网关本身不复制业务鉴权逻辑,也不持有案件数据源,只负责:
数据库层面,这三张表属于“平台库”,与 sys_user 等业务表共享同一个 PostgreSQL 实例,但由网关 DDL 脚本独立创建和维护。DDL 位于根仓库的 sql/gateway.sql,并通过 Spring spring.sql.init 在启动时执行。
graph TB
Client["客户端<br/>Electron / Web"] --> Gateway["ai-gateway :8080"]
Gateway --> Node1["ai-server 节点1<br/>:8980"]
Gateway --> Node2["ai-server 节点2<br/>:8980"]
Gateway --> PG["PostgreSQL<br/>gateway_service / gateway_node / gateway_user_route"]
Gateway --> Redis["Redis<br/>sa-token + 路由缓存"]
图表来源
章节来源
网关相关数据分为三层:
| 层级 | 表名 | 主要职责 |
|---|---|---|
| 服务层 | gateway_service |
定义对外路径前缀、登录路径、健康检查路径、默认节点和服务启用状态 |
| 节点层 | gateway_node |
登记一台 ai-server 实例的地址、所属服务、启用状态和备注 |
| 用户绑定层 | gateway_user_route |
记录某个用户或用户名被粘性绑定到的节点 |
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 UK
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
}
图表来源
章节来源
网关处理一个请求时,会依次完成以下判断:
x-token 解析 userId,再查用户绑定节点;重写目标 URL 并流式转发。
sequenceDiagram
participant C as "客户端"
participant F as "StickyRouteFilter"
participant R as "UserRouteRepository"
participant H as "NodeHealthRegistry"
participant N as "ai-server 节点"
C->>F: "HTTP 请求"
F->>F: "匹配服务路径前缀"
alt "登录请求"
F->>R: "按用户名查绑定节点"
R-->>F: "节点ID 或 空"
opt "未绑定"
F->>F: "健康节点轮询出候选节点"
end
else "普通请求"
F->>F: "从 x-token 解析 userId"
F->>R: "按 userId 查绑定节点"
R-->>F: "节点ID 或 空"
opt "未绑定但有默认节点"
F->>R: "bindIfAbsent(userId, null, defaultNodeId)"
R-->>F: "生效节点ID"
end
end
F->>H: "检查节点启用与健康状态"
H-->>F: "可用或不可用"
alt "节点可用"
F->>N: "流式转发请求"
N-->>C: "响应"
else "节点不可用"
F-->>C: "HTTP 503"
end
图表来源
章节来源
gateway_service该表描述一组对外路径前缀及其对应的后端节点集合。它是粘性路由的入口:网关先根据请求路径找到服务,再从服务中找节点。
| 字段 | 数据类型 | 主键/外键/索引 | 是否为空 | 业务含义 |
|---|---|---|---|---|
id |
VARCHAR(64) |
主键 | 否 | 服务唯一标识,如 zsjz-ai |
name |
VARCHAR(128) |
无 | 否 | 服务显示名称 |
path_prefix |
VARCHAR(128) |
唯一索引 uk_gateway_service_path_prefix |
否 | 对外路径前缀,例如 /js/a;全局唯一,不能以 / 结尾,也不能是 /gateway |
login_path |
VARCHAR(128) |
无 | 可空 | 相对于 path_prefix 的登录路径,例如 /auth/login;为空表示该服务不做登录粘性 |
health_path |
VARCHAR(255) |
无 | 否 | 完整健康检查路径,例如 /js/a/sys/health |
default_node_id |
VARCHAR(64) |
无 | 可空 | 存量用户兜底节点;上线前已存在但未绑定路由的用户可落在此节点 |
enabled |
SMALLINT |
无 | 否,默认 1 |
服务启用状态,1 表示启用 |
create_time |
TIMESTAMP |
无 | 否,默认当前时间 | 服务创建时间 |
update_time |
TIMESTAMP |
无 | 否,默认当前时间 | 服务更新时间 |
关键约束与行为:
path_prefix 全局唯一,避免不同服务抢占相同前缀;path_prefix 有额外校验:必须以 / 开头、不以 / 结尾、不能等于 /gateway、长度至少为 2;default_node_id 通常指向 gateway_node.id,但 DDL 没有强制外键约束;实际一致性由管理接口和运维流程保证;章节来源
gateway_node该表登记一台具体的 ai-server 实例。节点地址 base_url 不含路径,context-path 由转发的原始请求路径携带。
| 字段 | 数据类型 | 主键/外键/索引 | 是否为空 | 业务含义 |
|---|---|---|---|---|
id |
VARCHAR(64) |
主键 | 否 | 节点唯一标识,如 node-1 |
service_id |
VARCHAR(64) |
外键,引用 gateway_service(id) |
否 | 所属服务标识 |
name |
VARCHAR(128) |
无 | 否 | 节点显示名称 |
base_url |
VARCHAR(255) |
唯一索引 uk_gateway_node_service_base_url |
否 | 节点基础地址,格式为 http(s)://host:port,不含路径 |
enabled |
SMALLINT |
无 | 否,默认 1 |
节点启用状态 |
remark |
VARCHAR(512) |
无 | 可空 | 备注信息 |
create_time |
TIMESTAMP |
无 | 否,默认当前时间 | 节点创建时间 |
update_time |
TIMESTAMP |
无 | 否,默认当前时间 | 节点更新时间 |
关键约束与行为:
base_url 唯一,防止重复注册同一地址;service_id 是外键,删除服务时会受 ON DELETE RESTRICT 保护,必须先清理节点;base_url 由代码正则校验,不允许包含路径;章节来源
gateway_user_route该表实现“用户 → 节点”的粘性绑定。它支持两种方式识别用户:
user_id:对应 sys_user.id;username:用户名绑定,用于首次登录时可能尚未解析出 userId 的场景。| 字段 | 数据类型 | 主键/外键/索引 | 是否为空 | 业务含义 |
|---|---|---|---|---|
id |
BIGSERIAL |
主键 | 否 | 自增行标识,主要用于管理端分页和删除 |
service_id |
VARCHAR(64) |
外键,引用 gateway_service(id) |
否 | 该绑定所属的服务 |
user_id |
BIGINT |
部分唯一索引 uk_gateway_user_route_user |
可空 | 绑定到 sys_user.id;与 username 至少一个非空 |
username |
VARCHAR(64) |
部分唯一索引 uk_gateway_user_route_name |
可空 | 绑定到用户名;唯一性比较时使用小写,与 sys_user 用户名策略对齐 |
node_id |
VARCHAR(64) |
索引 idx_gateway_user_route_node |
否 | 目标节点 ID;节点不可用时网关返回 503,不自动切换 |
create_time |
TIMESTAMP |
无 | 否,默认当前时间 | 绑定创建时间 |
update_time |
TIMESTAMP |
无 | 否,默认当前时间 | 绑定更新时间 |
关键约束与行为:
ck_gateway_user_route_owner 保证 user_id 与 username 至少有一个非空;user_id 唯一;lower(username) 唯一;ON CONFLICT DO NOTHING,再由代码重新读取赢家,避免来回漂移;node_id 建立普通索引,便于按节点统计和迁移;章节来源
StickyRouteFilter 是粘性路由的核心过滤器,顺序为 10001,位于 Spring Cloud Gateway 的 URL 重写过滤器之后。它的主要职责包括:
GatewayRegistry 获取服务信息;UserRouteService 查询或绑定节点;GATEWAY_REQUEST_URL_ATTR,使后续 Netty 过滤器能正确转发;X-Gateway-Node,便于问题排查。对于登录请求,如果用户名已有绑定,直接使用该节点;如果没有绑定,会从健康节点中选出一个“候选节点”,但此时不写数据库。对于普通请求,如果用户未绑定且服务有 default-node-id,则调用 bindIfAbsent 进行兜底绑定;否则返回 503。
flowchart TD
Start["进入 StickyRouteFilter"] --> MatchService["匹配服务"]
MatchService --> IsLogin{"是否登录请求"}
IsLogin -->|是| FindByUsername["按用户名查绑定节点"]
FindByUsername --> Bound{"是否已绑定"}
Bound -->|是| UseBound["使用已绑定节点"]
Bound -->|否| SelectCandidate["健康节点轮询选出候选节点"]
IsLogin -->|否| ResolveToken["从 x-token 解析 userId"]
ResolveToken --> FindByUserId["按 userId 查绑定节点"]
FindByUserId --> HasBind{"是否有绑定"}
HasBind -->|是| UseBound
HasBind -->|否| DefaultCheck{"服务是否配置默认节点"}
DefaultCheck -->|是| BindDefault["bindIfAbsent(userId, null, defaultNodeId)"]
DefaultCheck -->|否| Return503["返回 503:用户未绑定节点"]
BindDefault --> UseBound
UseBound --> HealthCheck["校验节点启用与健康状态"]
HealthCheck --> Up{"节点可用?"}
Up -->|是| RewriteUrl["重写目标 URI 并转发"]
Up -->|否| Return503
图表来源
章节来源
LoginResponseFilter 在响应写入阶段拦截登录响应,只在满足以下条件时进行绑定:
code == 200;data.userId 非空;data.username 是非空文本。当条件满足时,它会:
token、userId、username;UserRouteService.bindIfAbsent(serviceId, userId, username, chosenNodeId);TokenResolver.cacheToken 把 gateway:token:{serviceId}:{token} 写入 Redis,TTL 24 小时;这个设计保证:
响应体过大或格式异常时降级为日志记录,不阻断登录。
sequenceDiagram
participant S as "StickyRouteFilter"
participant L as "LoginResponseFilter"
participant U as "UserRouteRepository"
participant T as "TokenResolver"
S->>S: "请求阶段决定候选节点"
S->>L: "继续链式过滤"
L->>L: "收集响应体并限制 256KB"
L->>L: "解析 code=200 且 data.userId、data.username 有效"
L->>U: "bindIfAbsent(serviceId, userId, username, chosenNodeId)"
U-->>L: "生效节点ID"
L->>T: "cacheToken(serviceId, token, userId)"
L-->>S: "响应原样返回"
图表来源
章节来源
GatewayConfigRepository 提供 JDBC 访问能力,配合 GatewayRegistry 实现内存快照和多实例对账。虽然具体 HTTP 控制器不在本文列出的文件中,但 Repository 暴露了以下管理能力:
| 能力 | 对应方法 | 操作对象 | 说明 |
|---|---|---|---|
| 计数 | countServices() |
gateway_service |
判断是否需要 YAML 播种 |
| 全量加载 | loadAll() |
服务与节点 | 构建 ServiceInfo 列表,按路径前缀降序排序 |
| 播种服务 | seedService(...) |
gateway_service |
首次启动时写入 |
| 播种节点 | seedNode(...) |
gateway_node |
首次启动时写入 |
| 新增服务 | upsertService(create=true, ...) |
gateway_service |
新建服务 |
| 更新服务 | upsertService(create=false, ...) |
gateway_service |
修改服务属性并刷新时间 |
| 删除服务 | deleteService(id) |
gateway_service |
删除服务 |
| 新增节点 | insertNode(...) |
gateway_node |
添加节点 |
| 更新节点 | updateNode(...) |
gateway_node |
修改节点地址和状态 |
| 删除节点 | deleteNode(id) |
gateway_node |
删除节点 |
| 用户路由查询 | findNodeIdByUserId(...) / findNodeIdByUsername(...) |
gateway_user_route |
粘性路由热路径 |
| 用户路由绑定 | bindIfAbsent(...) |
gateway_user_route |
幂等绑定,冲突时读回赢家 |
| 批量导入 | importExisting(serviceId, nodeId) |
gateway_user_route |
把未绑定的存量用户导入到指定节点 |
GatewayRegistry 负责:
RefreshRoutesEvent;章节来源
推荐直接使用仓库中的 DDL 脚本:
该脚本声明了:
CREATE TABLE IF NOT EXISTS;Spring 启动时通过以下配置自动执行 DDL:
spring:
sql:
init:
mode: always
schema-locations: classpath:db/gateway.sql
章节来源
| 表 | 约束类型 | 约束内容 | 目的 |
|---|---|---|---|
gateway_service |
主键 | id |
服务唯一标识 |
gateway_service |
唯一索引 | path_prefix |
防止路径前缀冲突 |
gateway_service |
默认值 | enabled = 1 |
默认启用 |
gateway_node |
主键 | id |
节点唯一标识 |
gateway_node |
唯一索引 | service_id, base_url |
同一服务内地址唯一 |
gateway_node |
外键 | service_id -> gateway_service(id) |
节点必须属于服务 |
gateway_node |
删除限制 | ON DELETE RESTRICT |
删除服务前必须先删节点 |
gateway_user_route |
主键 | id |
路由记录唯一标识 |
gateway_user_route |
检查约束 | user_id IS NOT NULL OR username IS NOT NULL |
至少提供一个用户标识 |
gateway_user_route |
部分唯一索引 | (service_id, user_id) WHERE user_id IS NOT NULL |
同一服务下用户 ID 唯一 |
gateway_user_route |
部分唯一索引 | (service_id, lower(username)) WHERE username IS NOT NULL |
同一服务下用户名唯一 |
gateway_user_route |
普通索引 | node_id |
提高按节点查询和统计效率 |
gateway_user_route |
外键 | service_id -> gateway_service(id) |
路由必须属于服务 |
gateway_user_route |
外键 | node_id -> gateway_node(id) |
路由必须指向有效节点 |
热点查询优先走 Redis
网关热路径使用 Redis 键:
gateway:token:{serviceId}:{token} → userId;gateway:route:user:{serviceId}:{userId} → nodeId;gateway:route:name:{serviceId}:{lower(username)} → nodeId。利用部分唯一索引减少冲突扫描
user_id 和 username 的路由查询分别命中不同的部分唯一索引,避免同时扫描两条规则。
按服务维度维护路由规模
由于 service_id 出现在所有高成本查询中,应确保管理端和导入程序始终带上正确的 service_id。
节点维度统计使用 idx_gateway_user_route_node
迁移、下线、扩容节点时,应先按 node_id 统计绑定用户数,再逐步解绑或重绑。
避免全表扫描 gateway_user_route
分页和管理查询应基于 service_id,必要时结合 keyword 对 username 或展示名模糊匹配。
章节来源
GatewayRegistry 会在其他实例写库后立即刷新自身快照;因此,服务/节点配置的最终一致性依靠 PostgreSQL 事务和 GatewayRegistry.reload() 收敛,而不是依赖外部注册中心。
用户绑定依赖数据库部分唯一索引:
bindIfAbsent 使用 ON CONFLICT DO NOTHING;节点恢复后自动标记 UP,用户映射保持不变。
stateDiagram-v2
[*] --> 正常
正常 --> 节点DOWN : "健康检查连续失败"
节点DOWN --> 正常 : "健康检查成功"
正常 --> 未绑定 : "用户首次登录且未绑定"
未绑定 --> 正常 : "bindIfAbsent 成功"
正常 --> 503 : "绑定节点不可用"
图表来源
章节来源
| 现象 | 可能原因 | 排查建议 |
|---|---|---|
| 登录后仍然提示“用户未绑定节点” | 服务未配置 default-node-id,或用户未成功登录 |
检查 gateway_service.default_node_id;查看 gateway_user_route 是否插入成功 |
| 登录成功但没有绑定记录 | 登录响应不是预期 JSON、code 不为 200、缺少 userId 或 username |
检查后端登录响应结构;查看 LoginResponseFilter 日志 |
| 绑定记录存在但请求仍 503 | 目标节点被禁用、健康检查失败,或节点地址错误 | 检查 gateway_node.enabled、base_url、健康检查结果 |
| 多节点部署后路由不一致 | 缓存未刷新或服务快照未重载 | 检查 GatewayRegistry.reload() 日志和 Redis 缓存 |
| 重复绑定导致冲突 | 并发首次登录或管理员重绑 | 使用 bindIfAbsent,不要直接覆盖;管理端删除旧绑定后再插入 |
| 健康检查持续失败 | 后端健康接口不可达、路径错误或后端未启动 | 检查 health_path、节点 base_url、后端 /sys/health |
常见 503 语义:
章节来源
gateway_service、gateway_node、gateway_user_route 三张表构成了网关粘性路由的数据底座:
gateway_service 定义“哪些路径属于哪个服务”;gateway_node 定义“这台服务的后端有哪些机器”;gateway_user_route 定义“哪个用户应该固定访问哪台机器”。配合 StickyRouteFilter 和 LoginResponseFilter,系统实现了:
GatewayRegistry 实现多实例配置一致性。在多节点部署环境中,应特别注意:
default-node-id 和批量导入逻辑。