夜雨聆风学习资料网

ARTICLE · 1385576

SkyWalking 网关插件在 SCG 2.2.8 上抛 NPE 导致网关请求 500 的排查

SkyWalking 网关插件在 SCG 2.2.8 上抛 NPE 导致网关请求 500 的排查

字数 1689,阅读大约需 9 分钟

SkyWalking 网关插件在 SCG 2.2.8 上抛 NPE 导致网关请求 500 的排查3

一、问题现象

mxf 项目(application/wzf/mxf)接入测试环境后,通过网关节点端口访问验证码接口拿不到验证码,前端表现为验证码空白、登录走不下去。网关日志里大约每 10 秒刷一条同样的异常:

2026-11-18 14:16:08.146 ERROR 1 --- [ctor-http-nio-3] c.mxftech.gateway.handler.ErrorExceptionHandler :网关请求异常 [GET http://192.168.120.50:32701/mxftech-auth/oauth/captcha]java.lang.NullPointerException: null    at org.apache.skywalking.apm.plugin.spring.cloud.gateway.v21x.HttpClientFinalizerResponseConnectionInterceptor.lambda$beforeMethod$0(HttpClientFinalizerResponseConnectionInterceptor.java:44)    at reactor.netty.http.client.HttpClientFinalizer.lambda$responseConnection$4(HttpClientFinalizer.java:102)    at reactor.core.publisher.MonoFlatMapMany$FlatMapManyMain.onNext(MonoFlatMapMany.java:163)    ...    at reactor.netty.resources.DefaultPooledConnectionProvider$PooledConnection.onStateChange(DefaultPooledConnectionProvider.java:454)

异常类型是 NPE,抛出点在 SkyWalking 的 v21x(Spring Cloud Gateway 2.1.x 插件)里,最后由网关自己的 ErrorExceptionHandler 兜住,请求直接失败。

二、排查过程

2.1 先确认是不是探针引起的

我先把这个项目 9 个服务的 skywalking.enabled 全部改成 false 再 sync。验证码立刻正常。这一步把业务代码、Nacos 路由、网关自身的过滤器都排除了,问题锁定在 SkyWalking 探针上。

2.2 打开网关探针,只保留 2.1.x 插件

我的第一版判断是「chart 把四个版本的 gateway 插件全拷进了 plugins/,重复插桩互相干扰」。按这个思路,我只留 2.1.x,把 2.0.x/3.x/4.x 排除:

env:  - name: SW_EXCLUDE_PLUGINS    value: spring-cloud-gateway-2.0.x,spring-cloud-gateway-3.x,spring-cloud-gateway-4.x

同步重建后验证码仍然 500,日志还是同一个 v21x 的 NPE。这个结果否掉了「多版本冲突」的判断。

2.3 用类直方图确认排除到底有没有生效

排除没生效和排除生效但插件自身有问题,是两回事。我进容器看 JVM 实际加载了哪些插件类:

kubectl exec -n dev <pod> -- sh -c \  'jcmd 1 GC.class_histogram | grep -oE "cloud\.gateway\.(v[0-9a-z]+)" | sort | uniq -c'

输出只有一行 v21x(14 个类),v20x、v3x、v4x 一个都没有。说明 SW_EXCLUDE_PLUGINS 的写法是对的、过滤也生效了,那么 NPE 只能是 2.1.x 插件自己的问题。

2.4 对比其它网关的 SCG 版本

同样的 chart、同样的 agent 版本,为什么别的网关不出事。我抽了 5 个还开着探针的网关(openapi、datamanage、manage、yjb、public),进容器看应用依赖:

kubectl exec -n dev <pod> -- sh -c \  'unzip -l /AppHome/app.jar | grep -oE "spring-cloud-gateway-server-[0-9][^ ]*\.jar"'

五个全是 spring-cloud-gateway-server-3.0.6.jar。再查 mxftech-gateway,是 spring-cloud-gateway-server-2.2.8.RELEASE.jar。3.0.6 的应用只会命中 v3x 插件,v21x 在 3.x 上根本不匹配,所以从来没生效;mxf 这个 2.2.8 是唯一会走到 v21x 的应用。

2.5 顺带确认插件 jar 的来源

plugins/ 目录里四个版本的 gateway 插件都在:

kubectl exec -n dev <pod> -- sh -c 'ls /AppHome/skywalking-agent/agent/plugins/ | grep -i cloud-gateway'# apm-spring-cloud-gateway-2.0.x-plugin-9.2.0.jar# apm-spring-cloud-gateway-2.1.x-plugin-9.2.0.jar# apm-spring-cloud-gateway-3.x-plugin-9.2.0.jar# apm-spring-cloud-gateway-4.x-plugin-9.2.0.jar

来源是 chart 里 gzeport-common/templates/_skywalking.tpl 第 28 行的网关分支,用通配符把可选的 gateway 插件整批拷进 plugins/:

cp /skywalking/agent/optional-plugins/apm-spring-cloud-gateway* /agent/agent/plugins/

三、根因分析

HttpClientFinalizerResponseConnectionInterceptor 的 beforeMethod 里有一步依赖连接上的 SkyWalking 上下文。从栈能看出这次调用走的是连接池复用路径(DefaultPooledConnectionProvider$PooledConnection.onStateChange → HttpClientFinalizer.lambda$responseConnection),这条路径上插件取不到它期望的上下文对象,第 44 行直接 NPE。

这个 NPE 没被吞掉。它从插件抛穿 reactor 链,落到网关的 ErrorExceptionHandler,整个请求就失败了。探针的一个兼容性问题,直接变成了业务不可用。

把两个版本的对应关系列出来,出问题的格子只有一个。

应用
SCG 版本
生效的 gateway 插件
结果
其它 12 个网关
3.0.6
v3x
正常
mxftech-gateway
2.2.8
v21x
连接池复用路径 NPE,请求 500

四、解决方案

当前的做法是在应用侧排除 gateway 插件,chart 不动。三个参数的实际取值:

参数
值
说明
skywalking.enabledtrue
探针保持开启,基础 agent 与其它插件继续工作
SW_EXCLUDE_PLUGINSspring-cloud-gateway-2.0.x,spring-cloud-gateway-2.1.x,spring-cloud-gateway-3.x,spring-cloud-gateway-4.x
四个 gateway 插件全部排除,避开 v21x 的 NPE
SW_AGENT_COLLECTOR_BACKEND_SERVICEStest-skywalking-oap.monitoring.svc.cluster.local:11800
上报到集群内 OAP Service
env:  - name: TZ    value: Asia/Shanghai  # 排除网关插件:实测 v21x(2.1.x)在该应用(spring-cloud-gateway-server 2.2.8)上  # 会在 HttpClientFinalizer 响应回调(连接池复用路径)抛 NPE,直接导致 /oauth/captcha 等请求 500  - name: SW_EXCLUDE_PLUGINS    value: spring-cloud-gateway-2.0.x,spring-cloud-gateway-2.1.x,spring-cloud-gateway-3.x,spring-cloud-gateway-4.x

代价是网关路由级的 span 暂时不采集,基础的 agent 与 webflux 服务端插件仍然生效,入站请求还能生成 entry span,跨服务的调用链不会在网关这里断掉。

验证通过后,我把另外 8 个非网关服务(auth、user、system、message、resource、csptt、ceb、develop)的探针重新打开。它们 isGateway 都是 false,不会加载 gateway 插件,不受这个 bug 影响。

五、验证

四步都过了才算修好:

# 1. 排除项进了容器kubectl exec -n dev deploy/mxftech-gateway -- sh -c 'echo $SW_EXCLUDE_PLUGINS'# 2. JVM 里不再有 gateway 插件类(预期 0)kubectl exec -n dev deploy/mxftech-gateway -- sh -c \  'jcmd 1 GC.class_histogram | grep -c "apm.plugin.spring.cloud.gateway"'# 3. 最近日志里没有该 NPE(预期 0)kubectl logs -n dev deploy/mxftech-gateway --since=10m | grep -c HttpClientFinalizerResponseConnectionInterceptor# 4. 最近日志里没有网关请求异常(预期 0)kubectl logs -n dev deploy/mxftech-gateway --since=10m | grep -c 网关请求异常

实测结果:Pod 重建后 0 重启,第 2 到第 4 步全部为 0,验证码与登录恢复正常。9 个服务的 values 用 helm template 全部渲染通过(initContainer 与 collector 地址都在)。

六、注意事项

  • • 排除项要写插件定义名。plugin.exclude_plugins 认的是插件 jar 内 skywalking-plugin.def 里的定义名(spring-cloud-gateway-2.1.x),写成 apm-spring-cloud-gateway-2.1.x-plugin 或 apm-...-9.2.0.jar 都不会生效。agent.config 第 181 行是 plugin.exclude_plugins=${SW_EXCLUDE_PLUGINS:}。
  • • 排除发生在 agent 加载插件定义的时候,和 jar 有没有被拷进 plugins/ 无关。四个 jar 全在目录里也能被排除干净,所以 chart 那行通配符拷贝不需要改,只是多占几 MB 磁盘。
  • • 不建议把 isGateway 改成 false。实测非网关服务的 plugins/ 里只有 spring-webflux-5.x-webclient-plugin、spring-webflux-6.x-webclient-plugin 这两个基础插件;网关额外多一个 apm-spring-webflux-5.x-plugin(服务端 WebFlux 入口)。改成 false 会把这个服务端插件一起取消,网关入站请求就不再有 entry span,调用链会在网关断开。用排除列表能只丢网关路由级 span。
  • • 新接入的 SCG 2.x 网关还会遇到同一个问题。目前仓库里 12 个网关都是 3.0.6,只有 mxf 是 2.2.8。后续如果还有 2.x 的应用接入,记得在它的 values 里加同样的排除项。
  • • 根治方向是让版本对齐。把 mxftech-gateway 的 Spring Cloud Gateway 升到 3.0.6 后,就能用其它网关长期验证过的 v3x 插件,届时把这些排除项删掉、isGateway 保持 true 即可;或者升级 SkyWalking agent 到修复该 NPE 的版本,但影响面覆盖全部应用,需要全量回归。
  • • 如果只想临时止血、不在意网关这一段调用链,把 isGateway 改 false 也能消掉报错,但按上面的分析,排除列表是更合适的选择。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料