ARTICLE · 1385576
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,整个请求就失败了。探针的一个兼容性问题,直接变成了业务不可用。
把两个版本的对应关系列出来,出问题的格子只有一个。
四、解决方案
当前的做法是在应用侧排除 gateway 插件,chart 不动。三个参数的实际取值:
skywalking.enabled | true | |
SW_EXCLUDE_PLUGINS | spring-cloud-gateway-2.0.x,spring-cloud-gateway-2.1.x,spring-cloud-gateway-3.x,spring-cloud-gateway-4.x | |
SW_AGENT_COLLECTOR_BACKEND_SERVICES | test-skywalking-oap.monitoring.svc.cluster.local:11800 |
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 也能消掉报错,但按上面的分析,排除列表是更合适的选择。















































































