FizzGate内置插件全解析:IP黑白名单、灰度发布等9大核心插件功能清单

原创2026-10-14 12:41:09768 阅读
文章标签:后端API网关微服务认证鉴权插件系统负载均衡

FizzGate内置插件全解析:IP黑白名单、灰度发布等9大核心插件功能清单

FizzGate 内置插件是这款 Java 微服务聚合网关的"能力扩展中心":IP 黑白名单、灰度发布、JWT/BasicAuth 鉴权、访问统计等功能都以插件形式预置在网关节点上,开箱即用。本文将带你快速看懂每一个内置插件的用途、关键配置和源码位置,方便你按需启用或二次开发。

📋 内置插件功能总览

FizzGate 的插件基于 FizzPluginFilter.java 接口实现,由 FizzPluginFilterChain.java 按路由配置顺序串联执行(见 FizzPluginFilterChain.java#L53-L66)。每个插件都支持两级配置:插件全局配置(所有路由共用)+ 路由级个性化配置(单条路由生效)。

内置插件清单如下:

插件 ID 功能 源码位置
fizz_plugin_ip IP 黑白名单访问控制 IpPlugin.java
GrayReleasePlugin 条件触发的灰度发布/流量切换 GrayReleasePlugin.java
authPlugin API 应用访问鉴权 AuthPluginFilter.java
basicAuthPlugin HTTP Basic 账号密码认证 BasicAuthPluginFilter.java
jwtAuthPlugin JWT Token 鉴权 JwtAuthPluginFilter.java
statPlugin 接口访问流量统计 StatPluginFilter.java
requestBodyPlugin 请求体预加载(供改写/读取) RequestBodyPlugin.java
专线三件套 专线签名、加解密、API 鉴权 dedicatedline/
myPlugin / myPluginPlus 自定义插件开发模板 MyPlugin.java

🛡️ IP 黑白名单插件:一步配置访问控制

fizz_plugin_ip 插件(IpPlugin.java)是控制接口访问来源的第一道闸门,支持在路由级配置 whiteIp 与 blackIp 两个字段。

支持的 4 种 IP 匹配格式(解析逻辑见 IpMatchUtils.java#L44-L94):

  • 单 IP:192.168.1.10
  • IP 范围:192.168.0.0-192.168.2.1
  • CIDR 网段:10.0.0.0/24
  • 通配符:192.168.*.10(自动展开为范围区间)

判定优先级(见 IpPlugin.java#L86-L115):

  1. 命中白名单 → 直接放行;
  2. 命中黑名单 → 直接拦截,返回 403;
  3. 未配置白名单 → 默认放行;配置了白名单但未命中 → 拦截。

💡 小技巧:被拦截时的响应内容与格式也可自定义——errorRespContentType 与 errorRespContent 两个配置项允许你返回任意 JSON 错误体(默认返回 {"msg":"非法IP","code":-1},见 RouterConfig.java)。

🚀 灰度发布插件:用条件表达式切换流量

GrayReleasePlugin(GrayReleasePlugin.java)是内置插件中能力最强的一个:通过 OGNL 条件表达式判断请求是否命中"灰度流量",命中后动态改写路由,把流量切到灰度环境。

核心配置项只有 3 个(见 GrayReleasePlugin.java#L186-L206):

  • triggerCondition:OGNL 触发条件表达式
  • routeType:命中后切换到的路由类型(服务发现 / 反向代理 / 服务编排 / 直接响应)
  • routeConfig:新路由的后端配置(serviceName、path、header、timeout 等)

条件表达式能访问的请求上下文变量:

变量 含义
method / path HTTP 方法 / 请求路径
query / header / cookie 查询参数 / 请求头 / Cookie
form / body 表单参数 / JSON 请求体字段
client.ip 客户端真实 IP

插件还内置了一批好用的工具函数(见 GrayReleasePlugin.java#L79-L171):exist() 判断字段存在、matches() 正则匹配、random() 按比例放量、clientIpInRange() 判断 IP 段、jwtClaim() 读取 JWT 中的声明字段——无需写一行代码,配置表达式即可完成"按用户标签灰度""按 10% 比例放量"等场景。

反向代理模式下,插件还会在多后端地址间做轮询(见 GrayReleasePlugin.java#L446-L455),适合灰度多副本负载均衡。

🔐 三大鉴权插件怎么选

API 鉴权:authPlugin

authPlugin(AuthPluginFilter.java)校验"应用-服务-API"三元组的访问授权关系,是 FizzGate 自动授权选择的执行入口,鉴权数据来自 ApiConfigService.java。

账号密码认证:basicAuthPlugin

basicAuthPlugin(BasicAuthPluginFilter.java#L127-L149)解析 Authorization: Basic xxx 头并做 Base64 解码比对,同样支持两级用户表:

  • 全局 users:插件级通用账号(见 GlobalConfig.java)
  • 路由级 users:单条路由专属账号,优先于全局生效

认证失败返回标准 401 并携带 WWW-Authenticate 头,兼容所有支持 Basic 认证的客户端。

Token 认证:jwtAuthPlugin

jwtAuthPlugin(JwtAuthPluginFilter.java)从 Authorization 头提取 Bearer Token 并验签,支持的算法相当全面(见 JwtAuthPluginFilter.java#L178-L209):

  • 对称算法:HS256 / HS384 / HS512(用 secretKey)
  • 非对称算法:RS256 / RS384 / RS512、ES256 / ES256K / ES384 / ES512(用 PEM 格式 publicKey)

两个进阶开关很实用:

  • passHeader:验证通过后是否剥离 Authorization 头,避免 Token 透传给后端
  • extractClaims:将 JWT 声明放入请求上下文,后续插件可直接取用

失败时的状态码(statusCode)、响应类型(contentType)与响应体(respBody)均可自定义,方便对接前端统一错误处理。

📊 其他常用内置插件

访问统计:statPlugin

statPlugin(StatPluginFilter.java)按 10 秒时间窗聚合 服务+方法+路径 维度的访问数据,为限流、熔断、降级等策略提供流量基础数据。

请求体预加载:requestBodyPlugin

requestBodyPlugin(RequestBodyPlugin.java)本身不做业务,而是把流式请求体一次性读入内存并装饰请求对象,让后续插件能够读取甚至改写请求体——灰度插件读取 body 字段做条件判断,正是基于这个能力。

自定义插件模板:myPlugin 与 myPluginPlus

想扩展自己的功能?项目里内置了两个开发模板:

📡 公网专线三件套

启用专线功能后(依赖 DedicatedLineService Bean),以下三个插件会在专线链路上自动生效:

💡 选插件指南:常见场景速查

业务场景 推荐插件组合
限制接口只允许内网访问 fizz_plugin_ip(白名单配 CIDR 网段)
屏蔽已知攻击来源 IP fizz_plugin_ip(黑名单 + 自定义 403 响应)
新功能小流量验证 GrayReleasePlugin(random() < 0.1 按比例放量)
按 VIP 用户标签走新版后端 GrayReleasePlugin(jwtClaim() / exist() 条件)
内部系统账号保护 basicAuthPlugin
开放平台 Token 校验 jwtAuthPlugin + extractClaims
对外 API 按应用授权 authPlugin
公网跨地域安全接入 专线三件套

内置插件覆盖了网关日常使用的绝大多数治理场景;而当你的需求超出内置能力时,myPluginPlus 模板 + plugin-core.md 提供的开发框架,可以让你用几十行代码快速扩展出自己的插件——这正是 FizzGate 插件系统"开箱即用、可无限扩展"的设计初衷。

登录后查看全文
fizz-gateway-node