作为一个每天跟网关打交道的人我一开始还真没太把这个过滤器当回事。直到有一次一个前端同事来找我说连不上WebSocket服务浏览器控制台一直报101 Switching Protocols没收到我才意识到网关做WebSocket代理远没有想象中那么简单。HTTP请求转发错了顶多返回个错误码WebSocket一旦握手失败整个长连接链路全部断裂而且排查起来特别诡异——因为日志里可能啥都没有。这篇文章我打算彻底把WebSocketRoutingFilter这个过滤器的源码掰开揉碎讲清楚它到底做了什么、为什么需要它、以及你在配置和排查时最容易掉进去的坑。适合已经对Spring Cloud Gateway有一定了解、想深入源码或者正在被WebSocket代理问题折磨的后端开发者。1. WebSocketRoutingFilter在网关里的定位它不是路由是“升级”1.1 为什么Gateway需要WebSocketRoutingFilter先想一个问题普通的HTTP请求网关拿到之后直接转发给下游服务拿到响应再返回给客户端这就完了。但WebSocket协议不一样。WebSocket连接开始的时候是一个HTTP请求带着Upgrade: websocket头然后服务端返回101 Switching Protocols之后这条TCP连接就脱离了HTTP的语义变成全双工的、持续可读写的长连接。关键点就在这里101之后网关不能再用HTTP请求/响应的模型来处理这条连接了。请求已经“升级”成了WebSocket网关必须介入这个升级过程替客户端完成到下游WebSocket服务的握手然后把后续的帧数据双向转发。如果你在Spring Cloud Gateway里不配任何东西直接转发一个WebSocket请求会发生什么实际上Gateway默认也是能处理一部分的但如果你用了lb://负载均衡、或者下游地址是ws://开头的、或者你想要更精细地控制握手头这些场景下没有WebSocketRoutingFilter是不行的。这个过滤器的定位很简单在所有路由过滤器里它负责识别WebSocket升级请求并把请求转交给WebSocketService去完成真实的代理握手和双向数据转发。1.2 过滤器顺序与职责边界Spring Cloud Gateway的过滤器链大体分三块路由过滤器RouteFilter、负载均衡过滤器ReactiveLoadBalancerClientFilter、Netty路由过滤器NettyRoutingFilter等最终由NettyRoutingFilter真正把HTTP请求发出去。WebSocketRoutingFilter在链路里处于比较靠后的位置它的顺序值比NettyRoutingFilter低也就是先执行。但它有个特殊操作一旦它认为当前是WebSocket请求它会直接修改请求的URL把它改成下游WebSocket服务的地址然后调WebSocketService.handleRequest()去接管后续流程同时给ServerWebExchange打一个标记绕过后面正常的HTTP转发过滤器。换句话说WebSocket请求走到WebSocketRoutingFilter这里就“下高速”了后面的HTTP过滤器它根本不走。这也是为什么你有时候生产环境WebSocket断了去看那些常规HTTP过滤器日志却什么都没有——因为真正干活的是这个过滤器加WebSocketService。1.3 与NettyRoutingFilter的协作方式源码里有一行非常关键if (ServerWebExchangeUtils.isAlreadyRouted(exchange)) { return chain.filter(exchange); }这是网关过滤器通用的“路由标记”机制。如果前面已经有人处理了这个请求比如WebSocketRoutingFilter自己处理了后面的NettyRoutingFilter看到isAlreadyRouted()为true就直接放行不再重复转发。这行代码是理解整个过滤器链的钥匙。WebSocketRoutingFilter处理完握手之后设置ServerWebExchangeUtils.ALREADY_ROUTED_ATTRIBUTE属性后置的过滤器全部不再干活。你要是自己写过滤器也得养成这个习惯——如果处理完了就标记状态避免链路重复执行。2. 核心源码拆解filter方法到底做了什么2.1 第一步判断是不是WebSocket升级请求WebSocketRoutingFilter的核心方法就是filter(ServerWebExchange exchange, GatewayFilterChain chain)它的第一步是判断当前请求是否为WebSocket升级请求Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { if (!isWebSocketUpgrade(exchange)) { return chain.filter(exchange); } // 后续处理... } private boolean isWebSocketUpgrade(ServerWebExchange exchange) { HttpHeaders headers exchange.getRequest().getHeaders(); return includesToken(headers.get(HttpHeaders.UPGRADE), websocket); }注意这里的includesToken不是简单的字符串相等而是按token规则匹配。HTTP头里可以出现多个token比如Upgrade: h2c, websocket实际逻辑是解析逗号分隔的token列表忽略大小写去匹配websocket。所以不要写死判断websocket.equals(upgradeHeader)。这里我补充一个容易忽略的点它只判断Upgrade头没有像Servlet容器那样去强校验Connection: Upgrade。也就是说一个没有正确设置Connection头的请求也可能进入WebSocket分支。实际见过有人用HTTP代理工具测试时把Connection头弄丢了网关照样把它当WebSocket请求转发了出去然后下游就报400。虽然网关宽松下游可不一定宽松。2.2 第二步获取路由信息并解析目标URL判断确认是WebSocket升级请求后过滤器开始进入真正的转发逻辑。首先它从exchange里拿Route信息然后取Route的URI接着要通过WebSocketService来“完善”这个URIURL url exchange.getRequest().getURI(); String scheme url.getScheme(); boolean isSecure scheme ! null scheme.equalsIgnoreCase(wss); int port url.getPort(); if (port -1) { port isSecure ? 443 : 80; } // 将 ws/wss 转为 http/https以便后续使用 HttpClient 进行握手 URI requestUrl new URI(isSecure ? https : http, url.getRawUserInfo(), url.getHost(), port, url.getRawPath(), url.getRawQuery(), url.getRawFragment());这块逻辑很关键。WebSocket的URI scheme是ws://或wss://但底层它仍然要走HTTP握手协议。Reactor Netty的WebSocket客户端是用HTTP升级的所以这里需要把ws变成httpwss变成https然后走底层HTTP客户端发起升级请求。同时注意这个逻辑它做了一次容错如果URI里没写端口会按协议默认端口补上。比如客户端请求的是ws://example.com/chatNetty实际建立连接时需要明确的目标地址这里就补成了http://example.com:80/chat。2.3 第三步处理转发头与代理头在拼接URI之后过滤器还要处理一套HTTP头把网关自己加上去的转发头修正过来HttpHeaders headers exchange.getRequest().getHeaders().mutate() .clear() .putAll(exchange.getRequest().getHeaders()) .remove(HttpHeaders.HOST) .remove(HttpHeaders.CONTENT_LENGTH) .remove(HttpHeaders.COOKIE) .put(HttpHeaders.HOST, targetHost) .put(HttpHeaders.CONNECTION, Upgrade) .build();这一步的意图很明显既然是代理到下游WebSocket服务那么Host头必须改成下游目标的主机名加端口targetHost不能让下游看到客户端原始域名。Content-Length要移除因为WebSocket握手阶段的请求体通常是空的。Cookie也直接移除避免把网关侧会话的Cookie泄露给下游会话Cookie应该由下游业务自行处理。Connection: Upgrade必须保留且明确指定。之前有同学问我为什么他手动改头后连接变成普通HTTP请求了多半就是把Connection头给覆盖掉了。这一行代码算是保命符。2.4 第四步标记路由并交由WebSocketService接管接下来是整段最核心的一句exchange.getAttributes().put(ServerWebExchangeUtils.ALREADY_ROUTED_ATTRIBUTE, true); return this.webSocketService.handleRequest(exchange, new ProxyServerWebSocketRequest(requestUrl, headers));注意代理请求被封装成了一个ProxyServerWebSocketRequest它不但包含了目标URI和改好的头还额外暴露了一个方法getSubProtocols()。这个子协议列表来自Sec-WebSocket-Protocol请求头WebSocketService在握手时要用它和服务端做子协议协商。handleRequest返回的是一个MonoVoid这个Mono的完成意味着整个WebSocket连接的代理生命周期结束。也就是说网关建立的这两段WebSocket连接客户端到网关、网关到下游服务会长期挂在这个Mono上直到其中一端断开Mono才结束。这也是为什么你会看到一个WebSocket请求的日志“卡”在那里很久那不是卡死而是长连接还活着。2.5 断点实战你该在哪些位置打点我在调试时习惯在以下几处打断点观察filter方法入口确认请求是否进入了WebSocket分支。requestUrl拼接完之后确认目标地址、端口、scheme是否正确。handleRequest调用处确认ALREADY_ROUTED_ATTRIBUTE已经打下去了后面的过滤器不会重复处理。进入NettyWebSocketService.handleRequest之后观察握手是否成功。如果你用的是IDEA建议直接用Remote调试连到测试环境的网关进程设置条件断点isWebSocketUpgrade(exchange)返回true时暂停。这样你就能在它干活之前一眼看清Headers、URI、Route等信息。3. 深挖WebSocketService握手到双向代理的幕后细节3.1 NettyWebSocketService的本质WebSocketService是个接口Spring Cloud Gateway的默认实现类叫NettyWebSocketService旧版本里叫NettyWebSocketAdapter之类的不同版本类名有细微差异但核心逻辑一致。它的职责就是拿着刚才拼好的目标URI和协议头主动连向下游WebSocket服务完成真实的WebSocket握手。实现上它内部用了一个ReactorNettyWebSocketClient这是Spring WebFlux对Reactor Netty的WebSocket客户端封装。连接成功后你会拿到一个WebSocketSession下游服务那头的同时handleRequest内部还会把ProxyServerWebSocketRequest升级为一个ReactorServerWebSocketSession这个东西代表“网关作为服务端对客户端的那一段WebSocket会话”。handleRequest的返回值大致逻辑是return this.websocketClient.execute(requestUrl, headers, clientSession - handleProxyRequest(exchange, serverRequest, clientSession) );clientSession就是网关连到上游的WebSocket会话handleProxyRequest内部要做的是把客户端请求升级成服务端会话然后在这两个会话之间做双向数据搬运。3.2 双向数据relay与Netty引用计数双向数据转发是最容易出Bug的地方。WebSocketMessage有编码和解码的buffer而且Netty对ByteBuf是有引用计数管理的。如果直接把下游收到的WebSocketMessage原封不动转给上游很容易出现重复释放引用或者内存泄漏。NettyWebSocketService里处理relay的关键代码大致长这样FluxWebSocketMessage relay clientSession.receive() .map(message - { // 注意 retain()因为要发送到另一个 session return serverSession.mutate().withPayload(message.getPayload().retain()) .setType(message.getType()).build(); }); serverSession.send(relay).then() .and(clientSession.send(serverSession.receive().map(...)))这里有个retain()。很多人不理解为什么需要它。原因是Reactor Netty的WebSocketMessage在receive()之后一旦响应链往下走它的payload ByteBuf可能会被释放。你要把它发送到另一个连接就必须先retain()一次把引用计数加一发送完成后对方会释放它。如果不retain就可能发送一个已经释放的ByteBuf轻则内容乱码重则直接抛IllegalReferenceCountException。逆向方向同理两端都做一次retainsend才保证引用计数平衡。这段逻辑你要是自己实现WebSocket代理千万记得。3.3 握手过程中的子协议协商子协议协商是很多人忽略的一个细节。客户端发起WebSocket握手时可以带Sec-WebSocket-Protocol: xxx表示它期望的服务端子协议。服务端如果支持就在101响应里返回同样的子协议头。NettyWebSocketService会把请求头里的Sec-WebSocket-Protocol解析出来放进ProxyServerWebSocketRequest.getSubProtocols()列表里然后用这个列表去调用Reactor Netty客户端的.subprotocols(...)方法。如果客户端没带这个头就传入空列表不影响握手。如果下游服务返回的子协议跟客户端期望的不一致握手虽然能成功但业务层的编解码可能出问题。我建议你在路由配置里或者下游服务端控制好子协议不然OpenAPI 3.1都救不了你。3.4 一个典型的源码级请求生命周期画个简单的时序理解整个流程浏览器发起GET /ws带Upgrade: websocket。Gateway的WebSocketRoutingFilter识别升级请求。拼接下游ws://backend-server:8080/ws。调用NettyWebSocketService.handleRequest。Reactor Netty客户端向上游发起HTTP升级请求。上游返回101两边WebSocketSession建立。handleRequest返回一个Mono开始双向数据relay。任一端断开Mono结束整个请求周期结束。4. 实战配置与调试让WebSocketRoutingFilter在你的项目里转起来4.1 路由配置示例最基础的路由配置直接转发到固定地址spring: cloud: gateway: routes: - id: websocket_route uri: ws://backend-server:9090 predicates: - Path/ws/**如果下游服务注册到了注册中心想走负载均衡用lb://- id: websocket_route_lb uri: lb:ws://websocket-service predicates: - Path/ws/**这两种写法都能被WebSocketRoutingFilter正确处理。模式上它支持lb:ws://、lb:wss://等Scheme。如果你自己写自定义URI解析器一定要在代码里兼容这些scheme前缀否则isSecure判断可能会出错。4.2 打开调试日志想干净地观察这个过滤器做了什么日志配置很简单logging: level: org.springframework.cloud.gateway.filter.WebSocketRoutingFilter: DEBUG org.springframework.cloud.gateway.filter.NettyRoutingFilter: DEBUGDEBUG模式下你会看到它判断请求是否为WebSocket升级、以及最终是否走到了HTTP转发逻辑。如果你想看更底层的握手细节还得开Reactor Netty的日志logging: level: reactor.netty: DEBUG但说实话reactor.netty的DEBUG日志量非常大线上别开只在本地调试时开。我一般更推荐用抓包工具直接看握手包这样最直观。4.3 超时与心跳配置WebSocket长连接最怕的就是某端长时间无数据被中间设备或系统判定为死连接后悄悄断开。此时客户端还傻傻地觉得连接是好的直到下一次发消息才发现断了。这种“假死”问题网关层面一个关键配置是WebSocket客户端的写超时spring: cloud: gateway: httpclient: websocket: max-frame-payload-length: 65536max-frame-payload-length控制WebSocket帧的最大有效载荷长度默认是65536字节64KB。如果你业务里有大数据量推送比如实时日志流、照片流超过这个值就会握手成功但数据传输时报错。这种错误相当隐蔽因为它不是断线而是数据被截断或直接异常。至于心跳Gateway本身不会替你做心跳检测。你要么在下游服务做心跳要么在客户端做心跳要么在网关前置的负载均衡器比如云上的四层LB做空闲超时和心跳配置。我之前遇到一个线上问题就是做了心跳但心跳间隔大于负载均衡器的空闲超时时间结果连接还是被切了。4.4 粘滞会话问题如果你的WebSocket服务是多实例部署且通过负载均衡访问那个lb://websocket-service你要特别注意WebSocket是长连接连接一旦建立后续业务消息必须一直走同一个后端实例。如果网关每次都负载均衡到不同实例业务状态就彻底乱了。Spring Cloud Gateway的ReactiveLoadBalancerClientFilter对同一个连接只会选一次服务实例因为已经标记路由了所以理论上一个WebSocket连接建立后不会中途切换实例。但还是建议你在下游业务里尽量设计成无状态的、或用外部存储共享会话状态因为实例重启、滚动发布都会导致连接断开重连重连时会被路由到别的实例这时候如果会话数据全在本地内存用户就会掉线。5. 常见问题排查速查表与避坑心得5.1 问题排查速查表下面的表是我这些年排查WebSocket代理问题时最常遇到的几种情况直接拿去对号入座。症状可能原因排查位置与解决建议握手一直没返回101最终超时下游地址不通或下游服务没启用WebSocket支持先直连下游服务测试握手检查路由URI的host/port握手返回400 Bad RequestHost头错误、Connection头被覆盖、Sec-WebSocket-Key缺失检查Header传递逻辑网关转发时会处理Host头但下游的Nginx/防火墙也可能篡改连接建立后秒断下游WebSocket空闲超时太短或心跳未生效调整下游空闲超时配置确认心跳能穿过网关到达下游数据偶尔出现乱码或抛IllegalReferenceCountExceptionByteBuf引用计数问题这种一般不会出现在官方默认实现里如果你二次开发过代理逻辑检查retain/释放大帧数据发送失败超过max-frame-payload-length限制调整spring.cloud.gateway.httpclient.websocket.max-frame-payload-length子协议协商失败业务层报错客户端与下游Sec-WebSocket-Protocol不一致核对客户端、网关路由、下游服务三处子协议配置日志显示已路由但后面还是走HTTP转发过滤器顺序配置错误或自定义过滤器在WebSocketRoutingFilter之前设置了alreadyRouted检查过滤器顺序值不要在WebSocket请求上手动调setAlreadyRouted5.2 我踩过的几个坑第一个坑是把ws://写成了http://。看起来很简单但当时配置是同事从一段网上复制的路由模板改的uri: http://websocket-service结果WebSocketRoutingFilter判断scheme不是webSocket相关的直接把请求当成普通HTTP请求扔给NettyRoutingFilter了下游Nginx面对普通GET请求只能返回404。这类配置错误日志里根本不会报错你得看过滤器链路才能发现。第二个坑是代理头被自定义全局过滤器清掉了。项目里有个全局过滤器统一删除Connection头理由是“防止HTTP走私攻击”。结果WebSocket请求走到WebSocketRoutingFilter时Upgrade头还在、Connection头没了握手自然不会成功。这类问题极难排查因为你的全局过滤器在处理WebSocket请求时也会执行。后来我的解决方式是在所有全局过滤器里跳过WebSocket升级请求或者在删除Connection头之前先判断Upgrade头里有没有websocket。第三个坑是生产环境偶发断连。后来抓包发现是云负载均衡器的空闲超时只有60秒而业务心跳是90秒一次。这个完全不是代码问题但会让你排查到怀疑人生。所以我后来做WebSocket代理时都会顺手在架构图上标注一下各层空闲超时时间。这不是网关心态而是长连接链路里每一层的超时都可能杀死你的连接。5.3 一定不要忽略的版本差异Spring Cloud Gateway的版本迭代里WebSocketRoutingFilter相关的类名、包名发生过调整。比如比较早的版本里WebSocketService还叫HandshakeWebSocketServiceNettyWebSocketService也是后来才有的。升级依赖时如果发现WebSocketRoutingFilter源码变了样先别慌核心逻辑基本没变。新版里OracleWebSocketRoutingFilter、SockJSFallbackWebSocketRoutingFilter这些衍生类也在逐步调整它们的关系如果你感兴趣可以去翻源码里的过滤链顺序。另外提醒一点如果你引入了spring-boot-starter-websocketTomcat WebSocket要格外注意它和Reactor Netty的WebSocket实现可能冲突。Spring Cloud Gateway默认用的是Netty你再加一套Tomcat的WebSocket握手处理两边对Upgrade头的处理逻辑会互相干扰。我之前在某个项目里踩过这个现象是本地直连没问题、一过网关就挂。解决方案很干脆Gateway服务里别乱塞Servlet容器的WebSocket支持。最后说几句实在话WebSocketRoutingFilter源码看下来会发现它本身并不复杂真正的复杂度在Reactor Netty那层连接复用、ByteBuf生命周期、背压处理、线程模型。但你不需要成为Netty专家也能用好它——只要你理解它干的三件事识别升级请求、修正目标和头部、交给WebSocketService做双向转发就已经能排查掉80%的问题了。从实际使用角度我最后再分享一个习惯每次改动网关配置或过滤器后都先用一条命令验证WebSocket握手不要急着让前端联调。命令很简单curl -i -N -H Connection: Upgrade -H Upgrade: websocket -H Host: your-gateway-host -H Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw -H Sec-WebSocket-Version: 13 http://your-gateway-host/ws如果返回101说明网关这条链路通了如果返回其他状态码响应体里的内容多半能告诉你问题出在哪一层。这个习惯帮我省了无数次来回扯皮的沟通成本。源码解析类的文章很容易写完就忘但如果你能带着“我这次要在生产环境把它调通”的目标去读那些源码细节才会真正变成你自己的经验。