服务注册中心与健康检查.md 34 KB

服务注册中心与健康检查

本文引用的文件

  • GatewayRegistry.java
  • ServiceInfo.java
  • NodeInfo.java
  • HealthChecker.java
  • NodeHealthRegistry.java
  • GatewayConfigRepository.java
  • StickyRouteFilter.java
  • NodeSelector.java
  • UserRouteService.java
  • GatewayProperties.java
  • gateway.sql

目录

  1. 引言
  2. 项目结构定位
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与容量特性
  8. 多实例部署与配置变更传播
  9. 故障排查指南
  10. 结论

引言

本文件聚焦网关模块中的服务注册、健康检查与粘性路由机制。系统以 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.java:1-116
  • GatewayConfigRepository.java:1-174
  • HealthChecker.java:1-62
  • NodeHealthRegistry.java:1-68
  • StickyRouteFilter.java:1-180
  • NodeSelector.java:1-45
  • UserRouteService.java:1-117

章节来源

  • gateway.sql:1-107

核心组件

组件 关键职责 重要行为
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 播种、健康检查阈值、间隔、超时等

章节来源

  • GatewayRegistry.java:1-116
  • ServiceInfo.java:1-32
  • NodeInfo.java:1-13
  • GatewayConfigRepository.java:1-174
  • HealthChecker.java:1-62
  • NodeHealthRegistry.java:1-68
  • NodeSelector.java:1-45
  • StickyRouteFilter.java:1-180
  • UserRouteService.java:1-117
  • GatewayProperties.java:1-81

架构总览

网关的服务注册与健康检查是一个“数据库事实源 + 内存快照 + 定时对账”的组合:

  1. 事实来源:PostgreSQL 中的 gateway_service 和 gateway_node 表。
  2. 配置快照:GatewayRegistry.services 保存 List<ServiceInfo>,按 pathPrefix 长度降序排列。
  3. 初始播种:首次启动若服务表为空,把 application.yaml 中 gateway.services 写入数据库。
  4. 运行期加载:写库后调用 reload() 同步重载;其他实例通过 @Scheduled(fixedDelayString="${gateway.registry-poll-interval:10s}") 定期拉取。
  5. 路由刷新:快照变化且 initialized=true 时发布 RefreshRoutesEvent,通知 Spring Cloud Gateway 刷新路由缓存。
  6. 健康检查:HealthChecker 周期探测每个启用节点的健康路径,结果写入 NodeHealthRegistry。
  7. 路由决策: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.java:23-116
  • GatewayConfigRepository.java:25-112
  • HealthChecker.java:28-62
  • NodeHealthRegistry.java:18-68

详细组件分析

服务注册与内存快照:GatewayRegistry

GatewayRegistry 是整个注册中心的入口。它持有三个依赖:

  • GatewayConfigRepository:负责读 PostgreSQL。
  • GatewayProperties:提供首次启动时的 YAML 播种数据。
  • ApplicationEventPublisher:在配置变更后发布路由刷新事件。

其核心字段为 volatile List<ServiceInfo> services,这是当前实例对 gateway_service 和 gateway_node 的内存快照。initialized 标志用于区分“启动期第一次加载”和“运行期后续对账”。

启动流程

  1. @PostConstruct init() 先执行 seedFromYamlIfNeeded(),再执行 reload()。
  2. seedFromYamlIfNeeded() 只在 repository.countServices() == 0 时工作:遍历 properties.getServices(),逐个插入服务和节点。
  3. reload() 调用 repository.loadAll(),比较新旧快照,仅在变化时替换并可能发布事件。
  4. 每次 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
    

图表来源

  • GatewayRegistry.java:23-89

对账机制

pollForChanges() 使用 Spring 调度器,默认每 10 秒执行一次,参数来自 ${gateway.registry-poll-interval:10s}。异常会被捕获并记录警告,不会中断调度。

这个设计的关键语义是:

  • 写操作通常发生在某个网关实例的管理接口上,该实例会立即调用 reload()。
  • 其他实例不知道谁写了数据库,只能靠定时任务发现变化。
  • 如果多个实例同时写,PostgreSQL 的唯一索引和约束负责一致性;网关侧通过 equals(services) 去重。

章节来源

  • GatewayRegistry.java:1-116

数据模型:ServiceInfo 与 NodeInfo

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 : "包含"

图表来源

  • ServiceInfo.java:1-32
  • NodeInfo.java:1-13

章节来源

  • ServiceInfo.java:1-32
  • NodeInfo.java:1-13

配置加载与 YAML 播种:GatewayConfigRepository

GatewayConfigRepository 是 JDBC 访问层,承担三类职责:

  1. 读取:countServices() 和 loadAll()。
  2. 播种:seedService() 和 seedNode()。
  3. 管理:服务与节点的增删改查,供管理接口使用。

loadAll() 的实现逻辑是:

  1. 先查询 gateway_node,按 service_id 分组。
  2. 再查询 gateway_service,组装成 ServiceInfo。
  3. 按 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>"]

图表来源

  • GatewayConfigRepository.java:25-69

章节来源

  • GatewayConfigRepository.java:1-174

健康检查与节点状态:HealthChecker 与 NodeHealthRegistry

HealthChecker 是一个定时任务:

  • 初始延迟 5 秒。
  • 固定延迟由 ${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 视为可用

这种设计有两个重要含义:

  1. 刚启动时不会立刻把所有节点标记为不可用,避免匿名用户短时间内全部 503。
  2. 已绑定用户的路由不会因为节点 DOWN 就自动切换,而是返回 503,因为用户数据可能在该节点本地磁盘上。

    stateDiagram-v2
    [*] --> UNKNOWN : "首次探活"
    UNKNOWN --> UP : "一次成功"
    UNKNOWN --> DOWN : "连续失败达到阈值"
    UP --> DOWN : "连续失败达到阈值"
    DOWN --> UP : "一次成功"
    

图表来源

  • NodeHealthRegistry.java:18-68
  • HealthChecker.java:28-62

章节来源

  • HealthChecker.java:1-62
  • NodeHealthRegistry.java:1-68

粘性路由与健康拒绝:StickyRouteFilter 与 NodeSelector

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["继续过滤器链"]

图表来源

  • StickyRouteFilter.java:28-180
  • NodeSelector.java:1-45
  • UserRouteService.java:1-117

章节来源

  • StickyRouteFilter.java:1-180
  • NodeSelector.java:1-45

用户路由缓存:UserRouteService

用户到节点的粘性绑定并非每次都直连 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
    

图表来源

  • UserRouteService.java:31-117
  • StickyRouteFilter.java:88-124

章节来源

  • UserRouteService.java:1-117

数据库事实源:gateway_service 与 gateway_node

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/** 管理接口进行。

章节来源

  • gateway.sql:1-107

依赖关系分析

各组件之间的依赖关系如下:

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.java:13-21
  • StickyRouteFilter.java:28-39
  • HealthChecker.java:20-26
  • NodeSelector.java:15-23
  • UserRouteService.java:24-30

耦合特征:

  • GatewayRegistry 向上依赖 Spring 事件发布器,向下依赖配置仓库和配置属性。
  • StickyRouteFilter 是业务最重的组件,同时依赖注册表、健康注册表、节点选择器和用户路由服务。
  • 健康状态是每实例本地内存,不跨实例同步;这简化了实现,但也意味着健康状态在不同网关实例间短暂不一致。
  • 用户粘性绑定通过 Redis + PostgreSQL 组合保证热路径性能和最终一致性。

章节来源

  • GatewayRegistry.java:1-116
  • StickyRouteFilter.java:1-180
  • HealthChecker.java:1-62
  • NodeHealthRegistry.java:1-68
  • UserRouteService.java:1-117

性能与容量特性

配置加载

  • GatewayRegistry.reload() 是 synchronized,避免多线程同时替换 services 快照。
  • GatewayConfigRepository.loadAll() 分两次查询:先节点,后服务,然后内存组装并按前缀长度排序。
  • 排序时间复杂度约为 O(n log n),n 为服务数量;实际网关服务数量通常较小。
  • findServiceByPath() 按已排序列表查找,命中第一个匹配的前缀即返回,属于短路匹配。

健康检查

  • 健康检查使用 Reactor Mono 异步探测,每个节点 probe() 订阅后立即返回,避免阻塞调度线程。
  • 健康状态存储在 ConcurrentHashMap 中,读写开销接近常数时间。
  • 只有状态翻转时输出健康日志,避免每秒刷屏。
  • failureThreshold 默认为 3,需要连续失败 3 次才标记 DOWN,减少网络抖动导致的误判。

路由决策

  • 粘性路由在过滤器链中顺序为 10001,紧接 URL 生成之后。
  • 用户路由先查 Redis,失败再查 PostgreSQL;Redis 写失败不阻断请求。
  • NodeSelector 使用 AtomicInteger 做简单轮询,适合无状态匿名流量。
  • 已绑定用户即使节点 DOWN 也不切换,避免用户数据跨节点不一致。

潜在瓶颈

场景 风险 缓解建议
大量服务定义 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,因此不同实例可能在短时间内对同一节点给出不同健康判断。
  • 已绑定用户的路由是持久化的:即使节点暂时 DOWN,已绑定用户仍会尝试访问原节点并收到 503,而不是自动切到其他节点。
  • 如果多个实例同时写数据库,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
    

图表来源

  • GatewayRegistry.java:67-116
  • GatewayConfigRepository.java:114-174

章节来源

  • GatewayRegistry.java:67-116

故障排查指南

网关启动后没有可转发服务

现象:日志出现“gateway_service 表为空且 gateway.services 未配置,网关没有任何可转发服务”。

可能原因:

  • PostgreSQL 中 gateway_service 表为空。
  • application.yaml 中 gateway.services 未配置或为空。
  • YAML 中服务或节点校验失败。

排查步骤:

  1. 检查数据库中 gateway_service 表是否有数据。
  2. 检查 GatewayProperties.services 是否包含合法服务定义。
  3. 确认 pathPrefix 以 / 开头、不以 / 结尾、不是 /gateway。
  4. 确认 baseUrl 是 http(s)://host[:port],不含路径。

章节来源

  • GatewayRegistry.java:43-66
  • GatewayConfigRepository.java:148-174
  • GatewayProperties.java:33-81

配置变更后其他实例未生效

现象:某实例更新了配置,但其他实例仍在旧路由。

可能原因:

  • 其他实例尚未完成下一轮 pollForChanges()。
  • 配置未真正写入 PostgreSQL。
  • refresh-routes 事件监听未触发。

排查步骤:

  1. 确认管理接口写库成功。
  2. 观察日志中是否出现“网关配置已重载”。
  3. 检查 gateway.registry-poll-interval 是否过大。
  4. 确认 PostgreSQL 连接正常。

章节来源

  • GatewayRegistry.java:67-116

用户请求返回 503,提示节点不可用

现象:已绑定用户访问后端时报 503,错误中包含节点不可用或未绑定节点。

可能原因:

  • 用户绑定的节点被标记为 DOWN。
  • 用户未绑定节点且未配置 defaultNodeId。
  • 用户绑定的节点被停用。
  • 服务本身不存在或已停用。

排查步骤:

  1. 查看 NodeHealthRegistry 健康日志,确认节点是否 DOWN。
  2. 检查 gateway_user_route 中用户是否绑定到预期节点。
  3. 检查 gateway_service.default_node_id 是否配置。
  4. 确认节点 enabled=1。
  5. 手动触发健康探测或等待下一次探活。

章节来源

  • StickyRouteFilter.java:65-169
  • NodeHealthRegistry.java:22-68

健康检查频繁标记 DOWN

现象:节点在 UP 和 DOWN 之间反复切换。

可能原因:

  • 后端健康接口不稳定。
  • gateway.health-check.failure-threshold 过小。
  • 网络抖动导致偶发失败。
  • 健康路径配置错误。

排查步骤:

  1. 确认 {base_url}{health_path} 可达。
  2. 检查后端健康接口是否返回 2xx。
  3. 调整 gateway.health-check.failure-threshold。
  4. 调整 gateway.health-check.interval。
  5. 查看 NodeHealthRegistry.HealthLogger 输出的状态变更日志。

章节来源

  • HealthChecker.java:28-62
  • NodeHealthRegistry.java:31-68
  • GatewayProperties.java:43-56

匿名用户全部 503

现象:未登录用户无法访问任何后端节点。

可能原因:

  • 所有节点都被禁用。
  • 所有节点都被标记为 DOWN。
  • 服务中没有启用节点。

排查步骤:

  1. 检查 gateway_node.enabled。
  2. 检查 NodeHealthRegistry 中节点状态。
  3. 确认 NodeSelector.select() 能选出候选节点。
  4. 临时放行一个节点验证后端连通性。

章节来源

  • NodeSelector.java:25-45
  • StickyRouteFilter.java:126-142

结论

该网关服务注册与健康检查机制以 PostgreSQL 为事实来源,通过 GatewayRegistry 维护内存快照,并通过 YAML 播种和定时对账实现初始化和多实例一致性。ServiceInfo 和 NodeInfo 提供了清晰的数据模型,pathPrefix 支持精确的路由前缀匹配,defaultNodeId 为存量用户提供兜底路由。

健康检查采用每实例本地状态,结合连续失败阈值和单次成功恢复策略,在保证稳定性的同时避免过度敏感。粘性路由保证用户会话和数据归属一致,同时在节点不可用时明确返回 503,而不是静默切换到未知节点。

在生产环境中,应重点关注:

  • PostgreSQL 中服务与节点配置的准确性。
  • 健康检查间隔和失败阈值的合理性。
  • 多实例对账延迟对配置变更生效的影响。
  • 已绑定用户在节点 DOWN 时的用户体验和告警策略。
  • Redis 不可用时的用户路由降级行为。