网关管理接口.md 25 KB

网关管理接口

本文引用的文件

  • AdminController.java
  • AdminService.java
  • AdminAuthWebFilter.java
  • AdminApiException.java
  • ApiResult.java
  • IpWhitelist.java

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 端点规范
  6. AdminService 操作说明
  7. 依赖与刷新机制
  8. 性能与安全特性
  9. 错误响应格式
  10. 运维场景示例
  11. 故障排查
  12. 结论

简介

本文件面向网关管理接口的使用者和运维人员,系统性说明 /gateway/admin 下用于管理服务、节点和用户路由的 REST API。所有接口均受管理员认证控制,并通过 AdminService 完成业务封装;写操作完成后会触发路由刷新,使当前实例立即生效,其他实例通过注册中心对账收敛。

项目结构

网关管理相关代码集中在 com.zsjz.gateway.admin 包中:

graph TB
    AdminController["AdminController<br/>REST 控制器"] --> AdminService["AdminService<br/>业务编排"]
    AdminController --> ApiResult["ApiResult<br/>统一返回体"]
    AdminController --> AdminApiException["AdminApiException<br/>业务异常"]
    AdminAuthWebFilter["AdminAuthWebFilter<br/>管理员鉴权过滤器"] --> AdminController
    IpWhitelist["IpWhitelist<br/>IP 白名单匹配"] --> AdminAuthWebFilter

图表来源

  • AdminController.java:1-153
  • AdminService.java:1-290
  • AdminAuthWebFilter.java:1-90
  • ApiResult.java:1-37
  • AdminApiException.java:1-30
  • IpWhitelist.java:1-87

章节来源

  • AdminController.java:1-153
  • AdminService.java:1-290
  • AdminAuthWebFilter.java:1-90
  • ApiResult.java:1-37
  • AdminApiException.java:1-30
  • IpWhitelist.java:1-87

核心组件

  • AdminController:声明 /gateway/admin 下的所有 REST 端点,负责接收请求、参数绑定、调用 AdminService,并将结果包装为 ApiResult。
  • AdminService:封装服务、节点、用户路由的业务逻辑,包括校验、持久化、缓存清理和路由刷新。
  • AdminAuthWebFilter:在控制器之前拦截 /gateway/admin/**,执行启用开关、IP 白名单、登录态和管理员权限校验。
  • AdminApiException:管理接口专用业务异常,HTTP 状态码与返回体中的 code 保持一致。
  • ApiResult:统一返回结构 { code, message, data },成功码为 200。
  • IpWhitelist:支持单 IP 和 CIDR 的管理接口来源地址过滤。

章节来源

  • AdminController.java:1-153
  • AdminService.java:1-290
  • AdminAuthWebFilter.java:1-90
  • AdminApiException.java:1-30
  • ApiResult.java:1-37
  • IpWhitelist.java:1-87

架构总览

管理接口的典型请求链路如下:

sequenceDiagram
    participant Client as "客户端"
    participant Filter as "AdminAuthWebFilter"
    participant Controller as "AdminController"
    participant Service as "AdminService"
    participant Registry as "GatewayRegistry.reload()"

    Client->>Filter: "GET /gateway/admin/status"
    Filter->>Filter: "检查 admin.enabled"
    Filter->>Filter: "IP 白名单匹配"
    Filter->>Filter: "解析 x-token 并验证管理员"
    Filter-->>Client: "404/401/403(失败时)"
    Filter->>Controller: "放行"
    Controller->>Service: "调用业务方法"
    Service->>Registry: "reload()(写操作后)"
    Service-->>Controller: "业务数据"
    Controller-->>Client: "ApiResult"

图表来源

  • AdminAuthWebFilter.java:28-89
  • AdminController.java:27-153
  • AdminService.java:1-290

端点规范

所有管理端点的基础路径均为 /gateway/admin。除特别说明外,响应格式统一为 ApiResult<Object>:

HTTP 方法 URL 模式 主要用途 请求体或参数 关键行为
GET /gateway/admin/status 获取网关整体状态 无 返回服务列表及节点健康信息
GET /gateway/admin/services 获取服务列表 无 返回 status() 中的 services
POST /gateway/admin/services 新增服务 ServiceUpsert 校验唯一性、插入配置、刷新路由
PUT /gateway/admin/services/{serviceId} 更新服务 ServiceUpsert 校验 pathPrefix、更新配置、刷新路由
DELETE /gateway/admin/services/{serviceId} 删除服务 无 要求无节点、无用户绑定,再删除
POST /gateway/admin/services/{serviceId}/nodes 新增节点 NodeUpsert 校验 serviceId、baseUrl、插入配置、刷新路由
PUT /gateway/admin/nodes/{nodeId} 更新节点 NodeUpsert 校验 baseUrl、更新配置、刷新路由
DELETE /gateway/admin/nodes/{nodeId} 删除节点 无 要求该节点无用户绑定
POST /gateway/admin/nodes/{nodeId}/check 手动探测节点健康 无 立即执行一次健康探测
GET /gateway/admin/routes 分页查询用户路由 serviceId、可选 keyword、page、size 返回总数与分页项
POST /gateway/admin/routes/bind 绑定或重绑用户到节点 BindRequest 覆盖式绑定,清理旧路由并重建
DELETE /gateway/admin/routes/{id} 解绑指定路由 路径参数 id 删除路由并清理缓存
POST /gateway/admin/routes/import-existing 导入已有路由 Map<String,String>,包含 serviceId、nodeId 批量导入并返回插入数与总数
POST /gateway/admin/reload 手动重载路由 无 触发 GatewayRegistry.reload()

公共参数与约束

  • 基础路径:/gateway/admin
  • 管理员认证:必须通过 AdminAuthWebFilter,否则返回 404、401 或 403。
  • 通用响应:ApiResult<T>,字段为 code、message、data。
  • 分页默认值:page=0,size=20;服务端限制 size 最大为 200,最小为 1。
  • 阻塞操作保护:控制器中对同步数据库等阻塞调用使用 Schedulers.boundedElastic(),避免占用 Netty 事件循环线程。

章节来源

  • AdminController.java:27-153
  • ApiResult.java:1-37

AdminService 操作说明

服务操作

  • createService:校验 serviceId、pathPrefix,防止重复服务和 pathPrefix 冲突,写入服务配置后调用 registry.reload()。
  • updateService:校验服务存在、pathPrefix 唯一,更新配置后刷新路由。
  • deleteService:要求服务不存在节点、不存在用户绑定,然后删除配置并刷新路由。

ServiceUpsert 字段含义: | 字段 | 类型 | 说明 | |---|---|---| | id | String | 服务标识,全局唯一 | | name | String | 服务名称,不能为空 | | pathPrefix | String | 路径前缀,需全局唯一 | | loginPath | String | 登录路径 | | healthPath | String | 健康检查路径 | | defaultNodeId | String | 默认节点 | | enabled | Boolean | 是否启用,可为空,空表示启用 |

章节来源

  • AdminService.java:49-108
  • AdminService.java:248-255

节点操作

  • createNode:校验所属服务存在、节点 id 全局唯一、同一服务下 base-url 唯一,插入节点后刷新路由。
  • updateNode:按 nodeId 查找节点,校验 base-url 唯一,更新后刷新路由。
  • deleteNode:要求节点不存在用户绑定,删除后刷新路由。

NodeUpsert 字段含义: | 字段 | 类型 | 说明 | |---|---|---| | id | String | 节点 id,全局唯一 | | name | String | 节点名称,不能为空 | | baseUrl | String | 后端服务基地址,需同服务内唯一 | | enabled | Boolean | 是否启用,可为空,空表示启用 | | remark | String | 备注 |

章节来源

  • AdminService.java:110-169
  • AdminService.java:257-263

节点健康检查

  • checkNode:根据 nodeId 在当前服务列表中定位节点,调用健康探测器执行一次探活,返回节点状态。若节点不存在则抛出 notFound。

章节来源

  • AdminService.java:171-189
  • AdminController.java:79-82

用户路由操作

  • pageRoutes:按 serviceId 和可选 keyword 分页查询用户路由,返回 total 与 items。
  • bindRoute:预绑定或重绑。先校验 serviceId、nodeId 属于该服务且节点已启用;userId 与 username 至少提供一个;从系统用户表补全 userId 和 username;事务内删除该用户在该服务上的旧路由并插入新绑定;随后清理用户缓存。
  • unbind:按路由 id 删除路由,并清理对应用户缓存。
  • importExisting:将已有路由批量导入到指定服务与节点,返回插入数量和该服务的路由总数。

BindRequest 字段含义: | 字段 | 类型 | 说明 | |---|---|---| | serviceId | String | 目标服务 | | userId | Long | 系统用户 id,与 username 二选一 | | username | String | 系统用户名,与 userId 二选一 | | nodeId | String | 目标节点 |

章节来源

  • AdminService.java:191-246
  • AdminController.java:84-107

手动重载

  • reload:调用 GatewayRegistry.reload(),返回是否发生变更。

章节来源

  • AdminService.java:248-255
  • AdminController.java:109-113

依赖与刷新机制

写操作与路由刷新

大多数写操作在持久化成功后都会调用 GatewayRegistry.reload(),其效果是:

  • 当前网关实例立即重新加载路由。
  • 其他网关实例通过注册中心的对账机制(约 10 秒周期)逐步收敛到一致状态。

    flowchart TD
    Start["写操作开始"] --> Validate["参数与服务/节点校验"]
    Validate --> Persist["写入 GatewayConfigRepository"]
    Persist --> Reload["调用 GatewayRegistry.reload()"]
    Reload --> CurrentInstance["当前实例路由立即刷新"]
    Reload --> OtherInstances["其他实例通过注册中心对账收敛"]
    CurrentInstance --> End["操作完成"]
    OtherInstances --> End
    

图表来源

  • AdminService.java:49-255

章节来源

  • AdminService.java:1-10
  • AdminService.java:49-255

性能与安全特性

IP 白名单控制

AdminAuthWebFilter 在放行管理接口前会检查 gateway.admin.ip-whitelist:

  • 白名单为空时不限制来源 IP。
  • 支持单 IP 和 CIDR,例如 192.168.0.100 或 192.168.0.0/24。
  • 如果来源地址不在白名单中,直接返回 403。
  • 当网关前面有反向代理时,RemoteAddress 可能是反代地址,需要谨慎配置。

章节来源

  • AdminAuthWebFilter.java:14-26
  • AdminAuthWebFilter.java:40-55
  • IpWhitelist.java:1-87

阻塞 JDBC 调用保护 Netty 事件循环

AdminController 对所有可能阻塞的方法调用都包裹在 blocking() 中,内部使用 Mono.fromSupplier(...).subscribeOn(Schedulers.boundedElastic())。这样做的目的是:

  • 避免同步数据库访问、锁竞争或其他阻塞 IO 长时间占用 Netty 事件循环线程。
  • 将阻塞任务调度到弹性线程池,提高网关高并发处理能力。
  • 非阻塞的健康探测 checkNode 本身返回 Mono,因此直接在服务层处理。

章节来源

  • AdminController.java:14-24
  • AdminController.java:115-121
  • AdminService.java:171-189

管理员认证流程

AdminAuthWebFilter 的处理顺序为:

  1. 仅对 /gateway/admin/** 生效。
  2. 若 gateway.admin.enabled=false,返回 404。
  3. 校验来源 IP 是否在白名单。
  4. 读取请求头 x-token,解析出用户 id。
  5. 查询系统用户表,要求 is_admin=1 且 status=1。
  6. 通过后把管理员用户 id 放入请求属性,继续交给控制器处理。

    flowchart TD
    Request["收到 /gateway/admin/** 请求"] --> Enabled{"admin.enabled 是否为真"}
    Enabled -->|否| NotFound["返回 404 管理接口未启用"]
    Enabled -->|是| Whitelist{"IP 在白名单?"}
    Whitelist -->|否| Forbidden["返回 403 来源 IP 不在管理白名单"]
    Whitelist -->|是| Token{"是否存在有效 x-token"}
    Token -->|否| Unauthorized["返回 401 未登录或登录已失效"]
    Token -->|是| AdminCheck{"用户是管理员且状态正常?"}
    AdminCheck -->|否| ForbiddenAdmin["返回 403 需要管理员权限"]
    AdminCheck -->|是| Next["放行至控制器"]
    

图表来源

  • AdminAuthWebFilter.java:28-89

章节来源

  • AdminAuthWebFilter.java:28-89

错误响应格式

统一返回体 ApiResult

所有成功响应的 HTTP 状态码通常为 200,返回体结构为: | 字段 | 类型 | 说明 | |---|---|---| | code | int | 业务状态码,成功时为 200 | | message | String | 消息文本 | | data | Object | 业务数据,可为 null |

章节来源

  • ApiResult.java:1-37

业务异常 AdminApiException

AdminApiException 同时决定 HTTP 状态码和返回体 code: | 构造方式 | HTTP 状态码 | 语义 | |---|---:|---| | badRequest(message) | 400 | 参数错误、资源冲突或业务校验失败 | | notFound(message) | 404 | 服务、节点、路由或用户不存在 | | conflict(message) | 409 | 资源仍存在子资源,例如仍有节点或用户绑定 |

控制器会将 AdminApiException 转换为 ApiResult.error(status, message)。

章节来源

  • AdminApiException.java:1-30
  • AdminController.java:123-131

参数绑定异常 WebExchangeBindException

当 Spring WebFlux 无法绑定或校验 @RequestBody 时,会抛出 WebExchangeBindException。控制器将其统一转换为:

  • HTTP 状态码:400
  • 返回体:ApiResult.error(400, "请求参数错误:" + ex.getMessage())

常见触发场景:

  • ServiceUpsert、NodeUpsert、BindRequest 字段缺失或类型不匹配。
  • 前端传入了控制器未声明的字段但未正确忽略时也可能影响绑定。

章节来源

  • AdminController.java:133-140

运维场景示例

新增 ai-server 节点

适用场景:新增一个名为 ai-server 的后端节点,并将其归属到某个服务。

步骤:

  1. 确认目标服务存在。
  2. 调用 POST /gateway/admin/services/{serviceId}/nodes,请求体为 NodeUpsert,其中 name 可设为 ai-server,baseUrl 指向该服务的实际地址。
  3. 成功后该节点会进入服务配置,并触发路由刷新。
  4. 可通过 POST /gateway/admin/nodes/{nodeId}/check 手动探测节点健康。

参考实现位置:

  • AdminService.createNode
  • AdminController.createNode

章节来源

  • AdminService.java:110-137
  • AdminController.java:64-72

绑定用户到节点

适用场景:将某个用户的路由固定到指定节点,例如用于灰度发布或定向转发。

步骤:

  1. 准备 BindRequest,提供 serviceId、nodeId,并在 userId 与 username 中至少提供一个。
  2. 调用 POST /gateway/admin/routes/bind。
  3. 服务端会从系统用户表补全用户信息,删除该用户在服务上的旧路由,再插入新路由。
  4. 用户缓存会被清理,下次请求会重新加载最新路由。

参考实现位置:

  • AdminService.bindRoute
  • AdminController.bind

章节来源

  • AdminService.java:191-219
  • AdminController.java:101-L105

导入已有路由

适用场景:批量将系统中已有路由迁移到新的服务与节点组合。

步骤:

  1. 调用 POST /gateway/admin/routes/import-existing,请求体包含 serviceId 和 nodeId。
  2. 服务端会统计并返回 inserted(本次插入数量)与 total(该服务的路由总数)。
  3. 导入后路由仍遵循现有生命周期,后续可通过 /routes/{id} 解绑。

参考实现位置:

  • AdminService.importExisting
  • AdminController.importExisting

章节来源

  • AdminService.java:231-L246
  • AdminController.java:107-L111

手动重载配置

适用场景:在其他实例已经收敛、或怀疑路由缓存不一致时,主动触发当前实例重新加载路由。

步骤:

  1. 调用 POST /gateway/admin/reload。
  2. 返回 changed 表示是否检测到配置变化。
  3. 通常新增、修改、删除服务或节点后会自动刷新;该接口适合运维兜底。

参考实现位置:

  • AdminService.reload
  • AdminController.reload

章节来源

  • AdminService.java:248-L255
  • AdminController.java:109-L113

故障排查

请求返回 404 管理接口未启用

  • 原因:gateway.admin.enabled=false。
  • 现象:所有 /gateway/admin/** 直接返回 404,看起来像接口不存在。
  • 解决:启用管理接口配置后再访问。

章节来源

  • AdminAuthWebFilter.java:40-L47

请求返回 403 来源 IP 不在管理白名单

  • 原因:请求来源 IP 不在 gateway.admin.ip-whitelist。
  • 注意:如果网关前有 Nginx、Ingress 等反代,远端地址可能是反代地址。
  • 解决:调整白名单,或确保只有受信来源能访问管理端口。

章节来源

  • AdminAuthWebFilter.java:48-L55
  • IpWhitelist.java:1-L87

请求返回 401 未登录或登录已失效

  • 原因:缺少 x-token,或 token 解析不到用户。
  • 解决:使用已登录用户生成的 x-token 发起请求。

章节来源

  • AdminAuthWebFilter.java:56-L76

请求返回 403 需要管理员权限

  • 原因:用户不是管理员,或用户状态不是启用状态。
  • 解决:使用 is_admin=1 且 status=1 的管理员账号。

章节来源

  • AdminAuthWebFilter.java:77-L86

请求返回 400 请求参数错误或业务校验失败

  • 参数绑定失败:WebExchangeBindException,提示“请求参数错误”。
  • 业务校验失败:AdminApiException.badRequest,例如 pathPrefix 冲突、节点 base-url 冲突、节点停用、必填字段为空等。
  • 解决:对照请求体字段说明修正参数。

章节来源

  • AdminController.java:133-L140
  • AdminService.java:49-L246

删除服务或节点时报 409 冲突

  • 删除服务:服务下仍有节点或用户绑定。
  • 删除节点:节点上仍有用户绑定。
  • 解决:先删除子节点或解绑用户路由。

章节来源

  • AdminService.deleteService
  • AdminService.deleteNode

结论

网关管理接口以 /gateway/admin 为入口,通过 AdminAuthWebFilter 实现强管理员认证,再通过 AdminController 暴露简洁的 REST API,最终由 AdminService 完成服务、节点和用户路由的生命周期管理。写操作统一触发 GatewayRegistry.reload(),保证当前实例路由即时刷新,并结合注册中心对账实现多实例一致性。运维人员可基于这些接口完成新增节点、绑定路由、导入已有路由和手动重载等典型场景,同时应重视 IP 白名单、管理员权限、阻塞 IO 调度和统一错误响应格式。