本文引用的文件
本文件聚焦网关模块中的服务注册、健康检查与粘性路由机制。系统以 PostgreSQL 的 gateway_service 和 gateway_node 表作为事实来源,在网关进程内维护一份轻量内存快照;启动阶段允许通过 YAML 配置播种初始数据,运行期则通过管理接口写入数据库,并由其他网关实例周期性对账刷新。节点健康状态由每个网关实例独立维护,用于拒绝不可用后端节点,但已绑定用户的路由保持粘性,不自动切换。
该机制的目标是:
服务注册与健康检查代码集中在 ai-gateway 子模块中,主要位于以下包:
| 包 | 职责 |
|---|---|
com.zsjz.gateway.registry |
服务/节点配置、健康检查、健康状态注册表 |
com.zsjz.gateway.route |
粘性路由、节点选择、用户路由缓存 |
com.zsjz.gateway.config |
网关配置属性 |
sql |
PostgreSQL 初始化脚本 |
graph TB
PG["PostgreSQL<br/>gateway_service / gateway_node"]
Repo["GatewayConfigRepository<br/>JDBC 访问层"]
Reg["GatewayRegistry<br/>内存快照 + 定时对账"]
HC["HealthChecker<br/>定时探活"]
HReg["NodeHealthRegistry<br/>节点健康状态"]
NSel["NodeSelector<br/>健康节点轮询"]
SR["StickyRouteFilter<br/>粘性路由过滤器"]
UR["UserRouteService<br/>Redis + PG 用户路由缓存"]
PG --> Repo
Repo --> Reg
Reg --> SR
Reg --> HC
HC --> HReg
NSel --> HReg
SR --> NSel
SR --> UR
图表来源
章节来源
| 组件 | 关键职责 | 重要行为 |
|---|---|---|
GatewayRegistry |
维护 List<ServiceInfo> 内存快照 |
启动时播种 YAML;同步 reload();initialized 标志避免初始循环事件;定时 pollForChanges() |
ServiceInfo |
一个对外路径前缀及其节点组 | loginFullPath()、matchesPath()、findNode() |
NodeInfo |
一台后端 ai-server 实例 |
包含 id、serviceId、name、baseUrl、enabled、remark |
GatewayConfigRepository |
PostgreSQL 配置访问层 | 计数、加载、播种、增删改查、校验规则 |
HealthChecker |
定时探测节点健康 | 每间隔调用 GET {base_url}{health_path},按阈值更新 DOWN/UP |
NodeHealthRegistry |
每实例本地节点健康状态 | UNKNOWN 视为可用;连续失败达阈值变 DOWN;一次成功恢复 UP |
NodeSelector |
无绑定请求的健康节点轮询 | 过滤 enabled 且 isUp 的节点 |
StickyRouteFilter |
粘性路由主过滤器 | 登录/普通/匿名分支;拒绝不可用节点;重写目标 URL |
UserRouteService |
用户到节点的粘性绑定 | Redis 热缓存 + PG 事实来源;bindIfAbsent 并发安全 |
GatewayProperties |
网关配置属性 | services 播种、健康检查阈值、间隔、超时等 |
章节来源
网关的服务注册与健康检查是一个“数据库事实源 + 内存快照 + 定时对账”的组合:
gateway_service 和 gateway_node 表。GatewayRegistry.services 保存 List<ServiceInfo>,按 pathPrefix 长度降序排列。application.yaml 中 gateway.services 写入数据库。reload() 同步重载;其他实例通过 @Scheduled(fixedDelayString="${gateway.registry-poll-interval:10s}") 定期拉取。initialized=true 时发布 RefreshRoutesEvent,通知 Spring Cloud Gateway 刷新路由缓存。HealthChecker 周期探测每个启用节点的健康路径,结果写入 NodeHealthRegistry。路由决策:StickyRouteFilter 根据用户名或 token 确定节点,并结合 NodeHealthRegistry.isUp 拒绝 DOWN 节点。
sequenceDiagram
participant App as "应用启动"
participant Reg as "GatewayRegistry"
participant Repo as "GatewayConfigRepository"
participant DB as "PostgreSQL"
participant Pub as "ApplicationEventPublisher"
participant HC as "HealthChecker"
participant HReg as "NodeHealthRegistry"
App->>Reg: "@PostConstruct init()"
Reg->>Repo: "countServices()"
alt "表为空"
Reg->>Repo: "seedService / seedNode(YAML)"
Repo->>DB: "INSERT ... ON CONFLICT DO NOTHING"
end
Reg->>Repo: "loadAll()"
Repo->>DB: "SELECT gateway_node, gateway_service"
DB-->>Repo: "ServiceInfo + NodeInfo"
Repo-->>Reg: "List<ServiceInfo>"
Reg->>Reg: "reload() -> initialized=false"
Note over Reg,Pub: "initially 不发布 RefreshRoutesEvent"
loop "固定延迟"
Reg->>Repo: "loadAll()"
Repo->>DB: "SELECT"
DB-->>Repo: "新快照"
Repo-->>Reg: "changed?"
alt "快照变化且已初始化"
Reg->>Pub: "publish(RefreshRoutesEvent)"
end
end
loop "健康检查"
HC->>HReg: "recordSuccess / recordFailure"
end
图表来源
GatewayRegistry 是整个注册中心的入口。它持有三个依赖:
GatewayConfigRepository:负责读 PostgreSQL。GatewayProperties:提供首次启动时的 YAML 播种数据。ApplicationEventPublisher:在配置变更后发布路由刷新事件。其核心字段为 volatile List<ServiceInfo> services,这是当前实例对 gateway_service 和 gateway_node 的内存快照。initialized 标志用于区分“启动期第一次加载”和“运行期后续对账”。
@PostConstruct init() 先执行 seedFromYamlIfNeeded(),再执行 reload()。seedFromYamlIfNeeded() 只在 repository.countServices() == 0 时工作:遍历 properties.getServices(),逐个插入服务和节点。reload() 调用 repository.loadAll(),比较新旧快照,仅在变化时替换并可能发布事件。每次 reload() 都会把 initialized 置为 true,从而保证第二次及以后的对账可以发布事件。
flowchart TD
Start(["init()"]) --> Seed["seedFromYamlIfNeeded()"]
Seed --> CheckEmpty{"gateway_service 是否为空?"}
CheckEmpty -->|否| Reload["reload()"]
CheckEmpty -->|是| LoadYaml["读取 gateway.services"]
LoadYaml --> HasDefs{"是否有服务定义?"}
HasDefs -->|否| Warn["记录警告:无任何可转发服务"]
HasDefs -->|是| SeedSvc["seedService / seedNode"]
SeedSvc --> Reload
Reload --> Changed{"快照是否变化?"}
Changed -->|是| Publish{"initialized 是否为 true?"}
Publish -->|是| Event["发布 RefreshRoutesEvent"]
Publish -->|否| Skip["跳过事件,避免启动循环"]
Changed -->|否| SetInit["设置 initialized = true"]
Event --> SetInit
Skip --> SetInit
图表来源
pollForChanges() 使用 Spring 调度器,默认每 10 秒执行一次,参数来自 ${gateway.registry-poll-interval:10s}。异常会被捕获并记录警告,不会中断调度。
这个设计的关键语义是:
reload()。equals(services) 去重。章节来源
ServiceInfo 是一个 Java record,对应 gateway_service 表的核心业务信息,并附带一组 NodeInfo:
| 字段 | 含义 |
|---|---|
id |
服务唯一标识 |
name |
服务显示名 |
pathPrefix |
对外路径前缀,如 /js/a |
loginPath |
相对 pathPrefix 的登录路径,可为空 |
healthPath |
完整健康检查路径,如 /js/a/sys/health |
defaultNodeId |
存量用户兜底节点 id |
enabled |
是否启用 |
nodes |
该服务的后端节点列表 |
ServiceInfo.loginFullPath() 会把 pathPrefix 与 loginPath 拼接,未配置登录路径时返回 null。matchesPath(rawPath) 的判断规则是:
pathPrefix;pathPrefix + "/" 开头。这意味着 /js/a 能匹配 /js/a 和 /js/a/sys/health,但不会错误匹配 /js/ab。
NodeInfo 更简单,表示一台后端 ai-server 实例,包含 id、serviceId、name、baseUrl、enabled、remark。
classDiagram
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~NodeInfo~
}
class NodeInfo {
+string id
+string serviceId
+string name
+string baseUrl
+boolean enabled
+string remark
}
ServiceInfo "1" --> "*" NodeInfo : "包含"
图表来源
章节来源
GatewayConfigRepository 是 JDBC 访问层,承担三类职责:
countServices() 和 loadAll()。seedService() 和 seedNode()。loadAll() 的实现逻辑是:
gateway_node,按 service_id 分组。gateway_service,组装成 ServiceInfo。pathPrefix.length() 降序排序,确保最长前缀优先匹配。播种时使用 ON CONFLICT DO NOTHING,因此重复执行脚本或多次启动不会破坏已有数据。
flowchart TD
Load["loadAll()"] --> QueryNodes["查询 gateway_node<br/>按 service_id 分组"]
QueryNodes --> QueryServices["查询 gateway_service"]
QueryServices --> Assemble["组装 ServiceInfo + NodeInfo"]
Assemble --> Sort["按 pathPrefix 长度降序排序"]
Sort --> Return["返回 List<ServiceInfo>"]
图表来源
章节来源
HealthChecker 是一个定时任务:
${gateway.health-check.interval:10s} 控制。GatewayRegistry.getServices() 中所有启用的节点。GET {base_url}{health_path}。healthRegistry.recordSuccess(nodeId)。healthRegistry.recordFailure(nodeId, reason, threshold)。NodeHealthRegistry 维护每实例本地的 ConcurrentHashMap<String, Health>,其中 Health 包含状态、最近错误、最近检查时间和连续失败次数。
健康状态规则如下:
| 条件 | 状态 |
|---|---|
| 尚未探活 | UNKNOWN |
| 连续失败数达到阈值 | DOWN |
| 任意一次成功 | UP |
isUp() 查询 |
DOWN 为不可用;UNKNOWN 和 UP 视为可用 |
这种设计有两个重要含义:
已绑定用户的路由不会因为节点 DOWN 就自动切换,而是返回 503,因为用户数据可能在该节点本地磁盘上。
stateDiagram-v2
[*] --> UNKNOWN : "首次探活"
UNKNOWN --> UP : "一次成功"
UNKNOWN --> DOWN : "连续失败达到阈值"
UP --> DOWN : "连续失败达到阈值"
DOWN --> UP : "一次成功"
图表来源
章节来源
StickyRouteFilter 是全局过滤器,顺序为 10001,位于 RouteToRequestUrlFilter(10000)之后。它的职责是根据请求类型决定目标节点,并改写请求 URL。
| 请求类型 | 决策逻辑 |
|---|---|
| 登录请求 | 若 username 已绑定,直接使用绑定节点;否则从健康节点中选一个候选,但不写库 |
| 普通请求 | 解析 x-token 得到 userId;有绑定则用绑定节点;无绑定则尝试 defaultNodeId 兜底;解析不出 token 则走匿名轮询 |
| 匿名请求 | 从健康节点轮询 |
当最终选出的节点不存在、被停用,或者 healthRegistry.isUp(nodeId) 为假时,过滤器抛出 StickyUnavailableException.serviceUnavailable,返回 503。
NodeSelector.select() 只考虑 node.enabled() 且 healthRegistry.isUp(nodeId) 的节点,并在多个候选之间做模数轮询。对于只有一个候选的节点,直接返回该节点。
flowchart TD
Enter(["filter()"]) --> Match["匹配 Route 与 serviceId"]
Match --> Enabled{"服务存在且启用?"}
Enabled -->|否| ErrSvc["服务不可用"]
Enabled -->|是| IsLogin{"是否登录请求?"}
IsLogin -->|是| LoginDecide["username 绑定节点 or 健康候选"]
IsLogin -->|否| TokenCheck{"是否存在 x-token?"}
TokenCheck -->|否| Anonymous["健康节点轮询"]
TokenCheck -->|是| Resolve["解析 userId"]
Resolve --> Bound{"用户已绑定节点?"}
Bound -->|是| UseBound["使用绑定节点"]
Bound -->|否| DefaultCheck{"有 defaultNodeId?"}
DefaultCheck -->|是| BindDefault["bindIfAbsent 兜底绑定"]
DefaultCheck -->|否| NoBind["返回 503 用户未绑定"]
UseBound --> HealthCheck["healthRegistry.isUp()"]
BindDefault --> HealthCheck
Anonymous --> HealthCheck
LoginDecide --> HealthCheck
HealthCheck -->|DOWN| ErrDown["503 节点不可用"]
HealthCheck -->|UP| Rewrite["重写 GATEWAY_REQUEST_URL_ATTR"]
Rewrite --> Next["继续过滤器链"]
图表来源
章节来源
用户到节点的粘性绑定并非每次都直连 PostgreSQL。UserRouteService 使用 Redis 作为热缓存,PostgreSQL 作为事实来源:
| 键模式 | 含义 | TTL |
|---|---|---|
gateway:route:user:{serviceId}:{userId} |
用户 ID 到节点 | 无 |
gateway:route:name:{serviceId}:{lower(username)} |
用户名到节点 | 无 |
行为特点:
bindIfAbsent 通过数据库唯一索引裁决并发,保证同一用户在同一服务下只绑定到一个节点。管理端重绑或解绑后,会同步清除 Redis 缓存。
sequenceDiagram
participant Client as "客户端"
participant Filter as "StickyRouteFilter"
participant Cache as "UserRouteService"
participant Redis as "Redis"
participant DB as "PostgreSQL"
Client->>Filter: "携带 x-token 的请求"
Filter->>Cache: "findNodeIdByUserId(serviceId, userId)"
Cache->>Redis: "get(key)"
alt "缓存命中"
Redis-->>Cache: "nodeId"
Cache-->>Filter: "nodeId"
else "缓存未命中"
Cache->>DB: "查询用户路由"
DB-->>Cache: "nodeId"
Cache->>Redis: "set(key, nodeId)"
Cache-->>Filter: "nodeId"
end
图表来源
章节来源
PostgreSQL 初始化脚本定义了四张相关表:
| 表 | 用途 | 关键约束 |
|---|---|---|
gateway_service |
服务定义:对外路径前缀、健康路径、登录路径、默认节点 | id 主键;path_prefix 唯一索引 |
gateway_node |
后端节点:每台 ai-server 实例 |
service_id 外键;(service_id, base_url) 唯一索引 |
gateway_user_route |
用户粘性绑定:用户或用户名到节点 | 部分唯一索引,user_id 或 username 至少一个非空 |
| 其他辅助索引 | 提高 node_id 查询效率 | idx_gateway_user_route_node |
gateway_service 注释明确说明:首次启动若表为空,用 application.yaml 的 gateway.services 播种;之后以数据库为准,YAML 不再覆盖。变更通过 /gateway/admin/** 管理接口进行。
章节来源
各组件之间的依赖关系如下:
graph LR
Properties["GatewayProperties"] --> Registry["GatewayRegistry"]
Repo["GatewayConfigRepository"] --> Registry
Registry --> Filter["StickyRouteFilter"]
Registry --> Checker["HealthChecker"]
Checker --> HealthReg["NodeHealthRegistry"]
Filter --> HealthReg
Filter --> Selector["NodeSelector"]
Filter --> UserRoute["UserRouteService"]
Selector --> HealthReg
UserRoute --> Repo
图表来源
耦合特征:
GatewayRegistry 向上依赖 Spring 事件发布器,向下依赖配置仓库和配置属性。StickyRouteFilter 是业务最重的组件,同时依赖注册表、健康注册表、节点选择器和用户路由服务。章节来源
GatewayRegistry.reload() 是 synchronized,避免多线程同时替换 services 快照。GatewayConfigRepository.loadAll() 分两次查询:先节点,后服务,然后内存组装并按前缀长度排序。O(n log n),n 为服务数量;实际网关服务数量通常较小。findServiceByPath() 按已排序列表查找,命中第一个匹配的前缀即返回,属于短路匹配。Mono 异步探测,每个节点 probe() 订阅后立即返回,避免阻塞调度线程。ConcurrentHashMap 中,读写开销接近常数时间。failureThreshold 默认为 3,需要连续失败 3 次才标记 DOWN,减少网络抖动导致的误判。NodeSelector 使用 AtomicInteger 做简单轮询,适合无状态匿名流量。| 场景 | 风险 | 缓解建议 |
|---|---|---|
| 大量服务定义 | loadAll() 组装和排序成本上升 |
控制服务数量,拆分无关前缀 |
| 高频配置变更 | 频繁 ReloadRoutesEvent 刷新路由 |
批量变更后再触发重载 |
| 大量节点健康探测 | 外部 HTTP 调用增多 | 调整 gateway.health-check.interval |
| Redis 不可用 | 用户路由回源数据库 | 已有降级逻辑,注意数据库负载 |
| 单实例长时间未对账 | 配置变更延迟 | 调小 gateway.registry-poll-interval |
[本节为通用性能指导,不直接分析具体代码行]
在多实例部署中,所有网关实例共享同一个 PostgreSQL 数据库。配置传播机制如下:
| 步骤 | 参与者 | 行为 |
|---|---|---|
| 1 | 管理员 | 调用 /gateway/admin/** 修改服务或节点 |
| 2 | 管理接口所在实例 | 写 PostgreSQL,随后调用 reload() |
| 3 | 其他实例 | 通过 @Scheduled(fixedDelayString="${gateway.registry-poll-interval:10s}") 发现变化 |
| 4 | 发现变化的实例 | 替换内存快照并发布 RefreshRoutesEvent |
| 5 | Spring Cloud Gateway | 重建路由定位器,使新配置生效 |
需要注意:
pollForChanges() 默认每 10 秒执行一次,可通过环境变量或配置文件覆盖。NodeHealthRegistry,因此不同实例可能在短时间内对同一节点给出不同健康判断。如果多个实例同时写数据库,PostgreSQL 的唯一索引和外键约束保证数据一致性;网关侧依靠 equals(services) 消除重复刷新。
sequenceDiagram
participant Admin as "管理员"
participant InstA as "实例 A"
participant InstB as "实例 B"
participant PG as "PostgreSQL"
Admin->>InstA: "POST /gateway/admin/** 修改配置"
InstA->>PG: "UPDATE / INSERT"
InstA->>InstA: "reload() -> 发布 RefreshRoutesEvent"
Note over InstA: "立即生效"
loop "每 10 秒"
InstB->>PG: "SELECT gateway_service / gateway_node"
PG-->>InstB: "新快照"
InstB->>InstB: "reload() -> changed? -> 发布 RefreshRoutesEvent"
end
图表来源
章节来源
现象:日志出现“gateway_service 表为空且 gateway.services 未配置,网关没有任何可转发服务”。
可能原因:
gateway_service 表为空。application.yaml 中 gateway.services 未配置或为空。排查步骤:
gateway_service 表是否有数据。GatewayProperties.services 是否包含合法服务定义。pathPrefix 以 / 开头、不以 / 结尾、不是 /gateway。baseUrl 是 http(s)://host[:port],不含路径。章节来源
现象:某实例更新了配置,但其他实例仍在旧路由。
可能原因:
pollForChanges()。refresh-routes 事件监听未触发。排查步骤:
gateway.registry-poll-interval 是否过大。章节来源
现象:已绑定用户访问后端时报 503,错误中包含节点不可用或未绑定节点。
可能原因:
DOWN。defaultNodeId。排查步骤:
NodeHealthRegistry 健康日志,确认节点是否 DOWN。gateway_user_route 中用户是否绑定到预期节点。gateway_service.default_node_id 是否配置。enabled=1。章节来源
现象:节点在 UP 和 DOWN 之间反复切换。
可能原因:
gateway.health-check.failure-threshold 过小。排查步骤:
{base_url}{health_path} 可达。gateway.health-check.failure-threshold。gateway.health-check.interval。NodeHealthRegistry.HealthLogger 输出的状态变更日志。章节来源
现象:未登录用户无法访问任何后端节点。
可能原因:
排查步骤:
gateway_node.enabled。NodeHealthRegistry 中节点状态。NodeSelector.select() 能选出候选节点。章节来源
该网关服务注册与健康检查机制以 PostgreSQL 为事实来源,通过 GatewayRegistry 维护内存快照,并通过 YAML 播种和定时对账实现初始化和多实例一致性。ServiceInfo 和 NodeInfo 提供了清晰的数据模型,pathPrefix 支持精确的路由前缀匹配,defaultNodeId 为存量用户提供兜底路由。
健康检查采用每实例本地状态,结合连续失败阈值和单次成功恢复策略,在保证稳定性的同时避免过度敏感。粘性路由保证用户会话和数据归属一致,同时在节点不可用时明确返回 503,而不是静默切换到未知节点。
在生产环境中,应重点关注: