FizzGate内置插件全解析:IP黑白名单、灰度发布等9大核心插件功能清单
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):
- 命中白名单 → 直接放行;
- 命中黑名单 → 直接拦截,返回 403;
- 未配置白名单 → 默认放行;配置了白名单但未命中 → 拦截。
💡 小技巧:被拦截时的响应内容与格式也可自定义——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
想扩展自己的功能?项目里内置了两个开发模板:
- MyPlugin.java:最简模板,实现
FizzPluginFilter接口即可(见 MyPlugin.java#L18-L22) - MyPluginPlus.java:进阶模板,继承
AbstractFizzPlugin并配合@FizzConfig注解,配置自动反序列化为 Java 对象,开发更省事。完整的插件核心包使用说明见 plugin-core.md。
📡 公网专线三件套
启用专线功能后(依赖 DedicatedLineService Bean),以下三个插件会在专线链路上自动生效:
dedicatedLinePairingPlugin(DedicatedLinePairingPluginFilter.java):校验SHA256(专线ID_时间戳_密钥)签名,并限制时间戳偏差在 5 分钟 内,防重放攻击(见 DedicatedLinePairingPluginFilter.java#L98-L126)dedicatedLineCodecPlugin(DedicatedLineCodecPluginFilter.java):对请求与响应体做 AES 加解密,在公网上建立加密通道dedicatedLineApiAuthPlugin(DedicatedLineApiAuthPluginFilter.java):校验专线身份对目标 API 的访问授权
💡 选插件指南:常见场景速查
| 业务场景 | 推荐插件组合 |
|---|---|
| 限制接口只允许内网访问 | 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 插件系统"开箱即用、可无限扩展"的设计初衷。