本文引用的文件
本文件面向网关管理接口的使用者和运维人员,系统性说明 /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
图表来源
章节来源
/gateway/admin 下的所有 REST 端点,负责接收请求、参数绑定、调用 AdminService,并将结果包装为 ApiResult。/gateway/admin/**,执行启用开关、IP 白名单、登录态和管理员权限校验。code 保持一致。{ code, message, data },成功码为 200。章节来源
管理接口的典型请求链路如下:
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"
图表来源
所有管理端点的基础路径均为 /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/adminAdminAuthWebFilter,否则返回 404、401 或 403。ApiResult<T>,字段为 code、message、data。page=0,size=20;服务端限制 size 最大为 200,最小为 1。Schedulers.boundedElastic(),避免占用 Netty 事件循环线程。章节来源
serviceId、pathPrefix,防止重复服务和 pathPrefix 冲突,写入服务配置后调用 registry.reload()。ServiceUpsert 字段含义:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | String | 服务标识,全局唯一 |
| name | String | 服务名称,不能为空 |
| pathPrefix | String | 路径前缀,需全局唯一 |
| loginPath | String | 登录路径 |
| healthPath | String | 健康检查路径 |
| defaultNodeId | String | 默认节点 |
| enabled | Boolean | 是否启用,可为空,空表示启用 |
章节来源
NodeUpsert 字段含义:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | String | 节点 id,全局唯一 |
| name | String | 节点名称,不能为空 |
| baseUrl | String | 后端服务基地址,需同服务内唯一 |
| enabled | Boolean | 是否启用,可为空,空表示启用 |
| remark | String | 备注 |
章节来源
notFound。章节来源
total 与 items。BindRequest 字段含义:
| 字段 | 类型 | 说明 |
|---|---|---|
| serviceId | String | 目标服务 |
| userId | Long | 系统用户 id,与 username 二选一 |
| username | String | 系统用户名,与 userId 二选一 |
| nodeId | String | 目标节点 |
章节来源
GatewayRegistry.reload(),返回是否发生变更。章节来源
大多数写操作在持久化成功后都会调用 GatewayRegistry.reload(),其效果是:
其他网关实例通过注册中心的对账机制(约 10 秒周期)逐步收敛到一致状态。
flowchart TD
Start["写操作开始"] --> Validate["参数与服务/节点校验"]
Validate --> Persist["写入 GatewayConfigRepository"]
Persist --> Reload["调用 GatewayRegistry.reload()"]
Reload --> CurrentInstance["当前实例路由立即刷新"]
Reload --> OtherInstances["其他实例通过注册中心对账收敛"]
CurrentInstance --> End["操作完成"]
OtherInstances --> End
图表来源
章节来源
AdminAuthWebFilter 在放行管理接口前会检查 gateway.admin.ip-whitelist:
192.168.0.100 或 192.168.0.0/24。403。RemoteAddress 可能是反代地址,需要谨慎配置。章节来源
AdminController 对所有可能阻塞的方法调用都包裹在 blocking() 中,内部使用 Mono.fromSupplier(...).subscribeOn(Schedulers.boundedElastic())。这样做的目的是:
checkNode 本身返回 Mono,因此直接在服务层处理。章节来源
AdminAuthWebFilter 的处理顺序为:
/gateway/admin/** 生效。gateway.admin.enabled=false,返回 404。x-token,解析出用户 id。is_admin=1 且 status=1。通过后把管理员用户 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["放行至控制器"]
图表来源
章节来源
所有成功响应的 HTTP 状态码通常为 200,返回体结构为:
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码,成功时为 200 |
| message | String | 消息文本 |
| data | Object | 业务数据,可为 null |
章节来源
AdminApiException 同时决定 HTTP 状态码和返回体 code:
| 构造方式 | HTTP 状态码 | 语义 |
|---|---:|---|
| badRequest(message) | 400 | 参数错误、资源冲突或业务校验失败 |
| notFound(message) | 404 | 服务、节点、路由或用户不存在 |
| conflict(message) | 409 | 资源仍存在子资源,例如仍有节点或用户绑定 |
控制器会将 AdminApiException 转换为 ApiResult.error(status, message)。
章节来源
当 Spring WebFlux 无法绑定或校验 @RequestBody 时,会抛出 WebExchangeBindException。控制器将其统一转换为:
400ApiResult.error(400, "请求参数错误:" + ex.getMessage())常见触发场景:
ServiceUpsert、NodeUpsert、BindRequest 字段缺失或类型不匹配。章节来源
适用场景:新增一个名为 ai-server 的后端节点,并将其归属到某个服务。
步骤:
POST /gateway/admin/services/{serviceId}/nodes,请求体为 NodeUpsert,其中 name 可设为 ai-server,baseUrl 指向该服务的实际地址。POST /gateway/admin/nodes/{nodeId}/check 手动探测节点健康。参考实现位置:
章节来源
适用场景:将某个用户的路由固定到指定节点,例如用于灰度发布或定向转发。
步骤:
BindRequest,提供 serviceId、nodeId,并在 userId 与 username 中至少提供一个。POST /gateway/admin/routes/bind。参考实现位置:
章节来源
适用场景:批量将系统中已有路由迁移到新的服务与节点组合。
步骤:
POST /gateway/admin/routes/import-existing,请求体包含 serviceId 和 nodeId。inserted(本次插入数量)与 total(该服务的路由总数)。/routes/{id} 解绑。参考实现位置:
章节来源
适用场景:在其他实例已经收敛、或怀疑路由缓存不一致时,主动触发当前实例重新加载路由。
步骤:
POST /gateway/admin/reload。changed 表示是否检测到配置变化。参考实现位置:
章节来源
gateway.admin.enabled=false。/gateway/admin/** 直接返回 404,看起来像接口不存在。章节来源
gateway.admin.ip-whitelist。章节来源
x-token,或 token 解析不到用户。x-token 发起请求。章节来源
is_admin=1 且 status=1 的管理员账号。章节来源
WebExchangeBindException,提示“请求参数错误”。AdminApiException.badRequest,例如 pathPrefix 冲突、节点 base-url 冲突、节点停用、必填字段为空等。章节来源
章节来源
网关管理接口以 /gateway/admin 为入口,通过 AdminAuthWebFilter 实现强管理员认证,再通过 AdminController 暴露简洁的 REST API,最终由 AdminService 完成服务、节点和用户路由的生命周期管理。写操作统一触发 GatewayRegistry.reload(),保证当前实例路由即时刷新,并结合注册中心对账实现多实例一致性。运维人员可基于这些接口完成新增节点、绑定路由、导入已有路由和手动重载等典型场景,同时应重视 IP 白名单、管理员权限、阻塞 IO 调度和统一错误响应格式。