企业官网建设流程全解析

作为一个每天跟网关打交道的人，我一开始还真没太把这个过滤器当回事。直到有一次一个前端同事来找我，说连不上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 Mono<Void> 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来“完善”这个URI：

URL 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变成http，wss变成https，然后走底层HTTP客户端发起升级请求。

同时注意，这个逻辑它做了一次容错：如果URI里没写端口，会按协议默认端口补上。比如客户端请求的是ws://example.com/chat，Netty实际建立连接时需要明确的目标地址，这里就补成了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返回的是一个Mono<Void>，这个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的关键代码大致长这样：

Flux<WebSocketMessage> 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。

逆向方向同理，两端都做一次retain+send，才保证引用计数平衡。这段逻辑你要是自己实现WebSocket代理，千万记得。

3.3 握手过程中的子协议协商

子协议协商是很多人忽略的一个细节。客户端发起WebSocket握手时可以带Sec-WebSocket-Protocol: xxx，表示它期望的服务端子协议。服务端如果支持，就在101响应里返回同样的子协议头。

NettyWebSocketService会把请求头里的Sec-WebSocket-Protocol解析出来放进ProxyServerWebSocketRequest.getSubProtocols()列表里，然后用这个列表去调用Reactor Netty客户端的.subprotocols(...)方法。如果客户端没带这个头，就传入空列表，不影响握手。

如果下游服务返回的子协议跟客户端期望的不一致，握手虽然能成功，但业务层的编解码可能出问题。我建议你在路由配置里或者下游服务端控制好子协议，不然OpenAPI 3.1都救不了你。

3.4 一个典型的源码级请求生命周期

画个简单的时序理解整个流程：

1. 浏览器发起GET /ws，带Upgrade: websocket。
2. Gateway的WebSocketRoutingFilter识别升级请求。
3. 拼接下游ws://backend-server:8080/ws。
4. 调用NettyWebSocketService.handleRequest。
5. Reactor Netty客户端向上游发起HTTP升级请求。
6. 上游返回101，两边WebSocketSession建立。
7. handleRequest返回一个Mono，开始双向数据relay。
8. 任一端断开，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: DEBUG

DEBUG模式下你会看到它判断请求是否为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: 65536

max-frame-payload-length控制WebSocket帧的最大有效载荷长度，默认是65536字节（64KB）。如果你业务里有大数据量推送，比如实时日志流、照片流，超过这个值就会握手成功但数据传输时报错。这种错误相当隐蔽，因为它不是断线，而是数据被截断或直接异常。

至于心跳，Gateway本身不会替你做心跳检测。你要么在下游服务做心跳，要么在客户端做心跳，要么在网关前置的负载均衡器（比如云上的四层LB）做空闲超时和心跳配置。我之前遇到一个线上问题，就是做了心跳但心跳间隔大于负载均衡器的空闲超时时间，结果连接还是被切了。

4.4 粘滞会话问题

如果你的WebSocket服务是多实例部署，且通过负载均衡访问那个lb://websocket-service，你要特别注意：WebSocket是长连接，连接一旦建立，后续业务消息必须一直走同一个后端实例。如果网关每次都负载均衡到不同实例，业务状态就彻底乱了。

Spring Cloud Gateway的ReactiveLoadBalancerClientFilter对同一个连接只会选一次服务实例（因为已经标记路由了），所以理论上一个WebSocket连接建立后不会中途切换实例。但还是建议你在下游业务里尽量设计成无状态的、或用外部存储共享会话状态，因为实例重启、滚动发布都会导致连接断开重连，重连时会被路由到别的实例，这时候如果会话数据全在本地内存，用户就会掉线。

5. 常见问题排查速查表与避坑心得

5.1 问题排查速查表

下面的表是我这些年排查WebSocket代理问题时最常遇到的几种情况，直接拿去对号入座。

5.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还叫HandshakeWebSocketService，NettyWebSocketService也是后来才有的。升级依赖时，如果发现WebSocketRoutingFilter源码变了样，先别慌，核心逻辑基本没变。新版里OracleWebSocketRoutingFilter、SockJSFallbackWebSocketRoutingFilter这些衍生类也在逐步调整，它们的关系如果你感兴趣，可以去翻源码里的过滤链顺序。

另外提醒一点：如果你引入了spring-boot-starter-websocket（Tomcat 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，说明网关这条链路通了；如果返回其他状态码，响应体里的内容多半能告诉你问题出在哪一层。这个习惯帮我省了无数次来回扯皮的沟通成本。源码解析类的文章很容易写完就忘，但如果你能带着“我这次要在生产环境把它调通”的目标去读，那些源码细节才会真正变成你自己的经验。