WebSocket网关实战：从502错误到高可用架构设计

1. 从一次“502 Bad Gateway”说起：为什么需要WebSocket Gateway

最近在折腾OpenClaw的时候，遇到了一个让人头大的问题。项目跑起来，前端页面看着一切正常，但当我尝试发送一条指令，或者等待一个长耗时任务返回时，控制台冷不丁就抛出一行刺眼的红字：unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responses。这个错误就像幽灵一样，时有时无，尤其是在处理需要流式输出或者长时间等待模型响应的场景时，几乎成了家常便饭。

一开始，我以为是后端服务挂了，但检查日志发现，核心的模型推理服务（比如我本地部署的Ollama）明明运行得好好的。问题出在哪？经过一番排查，矛头指向了网络通信的“中间人”——网关（Gateway）。在传统的HTTP请求-响应模式下，客户端发起请求，服务端处理完毕一次性返回结果，连接随即关闭。这种模式对于即时、短小的交互没问题，但对于OpenClaw这类需要与大型语言模型（LLM）进行持续、双向对话，或者需要实时接收任务执行状态、代码执行流输出的场景，就显得力不从心了。HTTP长轮询（Long Polling）或服务器发送事件（SSE）虽然能模拟实时，但都有各自的局限，比如连接开销大、协议不够“原生”。

这时，WebSocket就登场了。它提供了真正的全双工通信通道，一旦握手建立，客户端和服务器可以在任意时刻互发消息，连接持久存在，完美契合实时交互的需求。但是，直接把WebSocket服务暴露给公网或复杂的内部网络环境是不安全也不现实的。我们需要一个统一的入口来管理这些WebSocket连接，进行认证、路由、负载均衡、协议转换、限流熔断等一系列操作。这个入口，就是WebSocket Gateway。

在OpenClaw的架构里，WebSocket Gateway扮演着至关重要的“交通枢纽”角色。它不仅是前端（Web UI、客户端应用）与后端各种服务（模型服务、代码执行器、工具调用服务等）之间的桥梁，更是保障整个系统稳定、高效、可扩展的关键组件。我们开头提到的502 Bad Gateway错误，很多时候就是Gateway在转发请求到后端服务时，后端服务无响应、崩溃或者网络不通导致的。理解Gateway的原理，是解决这类问题、进而深度定制和优化OpenClaw系统的必经之路。本文将深入拆解OpenClaw中WebSocket Gateway的实现原理、核心配置以及那些你在部署和开发中一定会遇到的“坑”。

2. WebSocket Gateway的核心职责与架构定位

要理解Gateway，首先要跳出“它只是一个转发请求的代理”这种简单认知。在一个像OpenClaw这样复杂的智能体系统中，Gateway承担着多维度的职责，其架构定位决定了整个系统的通信形态和可靠性边界。

2.1 四大核心职责

1. 协议代理与路由这是Gateway最基础的功能。客户端（通常是浏览器）通过ws://或wss://协议连接到Gateway。Gateway内部需要根据请求的路径（Path）、头信息（Headers）或其他元数据，将WebSocket连接请求正确地路由到后端的某个具体服务。例如，OpenClaw中，处理用户对话的请求可能被路由到llama2:8000，而处理代码执行的请求则被路由到code-executor:8080。Gateway需要维护一个路由表，并动态地处理连接的生命周期。

2. 连接管理与状态维护WebSocket是长连接，Gateway必须高效地管理成千上万个并发的连接。这包括连接的建立（握手）、保持活跃（心跳检测）、以及优雅地关闭。Gateway需要实现心跳机制（Ping/Pong）来检测死连接并及时清理，释放资源。同时，对于一些需要会话状态的场景，Gateway可能还需要在内存或外部存储（如Redis）中维护一些轻量的会话上下文，虽然业务状态通常建议放在后端服务。

3. 安全与治理Gateway是系统的边防哨所，所有安全策略都在这里第一道落地：

• 认证（Authentication）：在WebSocket握手阶段（HTTP Upgrade请求），Gateway可以检查Authorization头、Cookie或查询参数中的Token，验证用户身份。未通过认证的连接请求将被直接拒绝（返回401或403）。
• 限流与熔断（Rate Limiting & Circuit Breaker）：防止单个用户或异常流量打垮后端服务。Gateway可以对特定IP、用户或路由路径进行请求频率限制。当发现某个后端服务连续失败（如连接超时、返回5xx错误）时，可以快速熔断，直接拒绝发往该服务的请求，并定期尝试恢复，避免雪崩效应。Sentinel、Resilience4j等库常被集成用于此目的。
• 请求/响应转换与过滤：Gateway可以修改进出站的请求和响应头，例如透传X-Forwarded-For客户端真实IP，添加统一的跟踪ID（Trace ID）用于全链路日志追踪。

4. 负载均衡与高可用当后端某个服务有多个实例时（例如，部署了多个模型推理Pod），Gateway需要具备负载均衡能力，将新的WebSocket连接均匀地分发到健康的实例上。常见的策略有轮询（Round Robin）、随机（Random）、最少连接（Least Connections）等。结合服务发现（如Nacos、Consul、Eureka），Gateway可以动态感知后端服务实例的上线和下线，实现高可用。

2.2 在OpenClaw中的架构定位

在OpenClaw的典型部署中，Gateway通常处于架构的最前端。我们来看一个简化的逻辑视图：

[浏览器/客户端] | | (wss://your-domain.com/ws) v [WebSocket Gateway (Spring Cloud Gateway / 自定义实现)] | (内部协议，可能仍是WebSocket或转为HTTP) v [服务集群] ├── [智能体核心服务 (处理对话、规划)] -> [大模型API (如Ollama, OpenAI)] ├── [代码执行服务 (Crestodian等)] └── [工具调用服务 (搜索、计算等)]

Gateway在这里抽象了后端服务的复杂性。对于前端来说，它只需要和一个固定的Gateway地址建立WebSocket连接。至于后端是单体服务还是微服务，是本地Ollama还是云端API，前端无需关心。这种设计极大地提升了系统的灵活性和可维护性。

3. 深入握手与连接建立：从HTTP到WebSocket

WebSocket连接并非凭空建立，它始于一个特殊的HTTP请求。理解这个握手过程，对于调试error during websocket handshake:这类问题至关重要。

3.1 标准握手流程

1. 客户端发起HTTP Upgrade请求：客户端（如浏览器）向服务器（即我们的Gateway）发送一个标准的HTTP GET请求，但包含两个关键头信息：

   GET /chat HTTP/1.1 Host: localhost:8080 Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== Sec-WebSocket-Version: 13

   • Upgrade: websocket和Connection: Upgrade表明客户端希望将协议升级为WebSocket。
   • Sec-WebSocket-Key是一个Base64编码的随机值，由客户端生成，用于握手验证。
   • Sec-WebSocket-Version指定协议版本，13是当前广泛使用的版本。

2. 服务端响应握手：服务端（Gateway）收到请求后，需要验证该请求是否合法（如路径是否存在、认证是否通过）。如果接受升级，则返回一个HTTP 101 Switching Protocols响应：

   HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

   • 状态码必须是101。
   • Sec-WebSocket-Accept的值是通过一个固定算法计算出来的：将客户端发送的Sec-WebSocket-Key加上一个固定的GUID字符串258EAFA5-E914-47DA-95CA-C5AB0DC85B11，然后计算其SHA-1哈希值，最后进行Base64编码。客户端会验证这个值，确保对方是合法的WebSocket服务器。

3. 连接升级：一旦101响应被客户端接收，底层的TCP连接就被“升级”了。之后的通信将不再使用HTTP协议，而是使用WebSocket数据帧格式进行双向二进制或文本消息传输。

3.2 Gateway在握手阶段的处理逻辑

作为Gateway，它在握手阶段扮演着双重角色：既是客户端（相对于后端业务服务）的服务器，又是后端业务服务的客户端。

1. 接收客户端握手请求：Gateway监听特定端口（如8080），等待客户端的HTTP Upgrade请求。
2. 执行前置过滤器（Pre-Filter）：这是实现安全与治理的关键环节。Gateway会在这里执行路由定位、身份认证（检查JWT Token）、限流判断、请求头修改等操作。如果任何一个过滤器失败（例如Token无效），Gateway会直接返回一个非101的HTTP响应，如401 Unauthorized或403 Forbidden，这就是握手失败，错误信息可能就是error during websocket handshake: unexpected response code: 401。
3. 向后端服务发起握手：当前置过滤器通过后，Gateway需要根据路由规则，找到对应的后端服务地址（例如http://llama-svc:8000）。然后，Gateway会模拟一个客户端，向后端服务发起一个新的HTTP Upgrade请求。这个过程称为“代理握手”。这里有一个关键点：Gateway通常需要将原始请求的一些头信息（如Sec-WebSocket-Key）原样或处理后转发给后端，同时可能添加一些内部头信息（如X-Real-IP）。
4. 处理后端响应并转发：Gateway收到后端服务的响应。如果后端返回101，说明后端服务接受WebSocket连接。Gateway随后会将这个101响应转发给原始客户端。至此，一个“管道”就打通了：客户端<->Gateway<->后端服务，两段都是WebSocket连接。如果后端服务返回的不是101（例如502、503），Gateway就需要处理这个错误，通常会向客户端返回一个错误响应，这也就是我们常看到的502 Bad Gateway的根源之一。

一个常见的坑：unexpected response code: 200这个错误经常在使用某些代理或配置不当时出现。它意味着客户端收到了一个状态码为200的HTTP响应，而不是预期的101。可能的原因有：

• Nginx/Apache等反向代理配置错误：代理服务器没有正确理解WebSocket协议，将Upgrade请求当作普通HTTP请求处理了，并返回了其默认的200页面或错误页面。解决方案是在代理配置中显式支持WebSocket。

  # Nginx 配置示例 location /ws/ { proxy_pass http://backend_gateway; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; # 以下两行对保持连接活跃很重要 proxy_read_timeout 3600s; proxy_send_timeout 3600s; }

• Gateway路由配置错误：请求可能被路由到了一个只处理普通HTTP的端点，该端点处理了GET请求并返回了200。
• 应用服务器（如Tomcat）配置：需要确保应用服务器支持WebSocket。对于Spring Boot，通常引入spring-boot-starter-websocket依赖即可，但需检查是否有自定义过滤器拦截了Upgrade请求。

4. 消息流动与连接维护：Gateway如何做“管道工”

握手成功，连接建立，真正的数据流动才开始。Gateway在这里的角色就像一个高效的“管道工”，负责在客户端和后端服务之间双向、无损地搬运数据帧，并确保管道本身的健康。

4.1 数据帧的转发机制

WebSocket通信的基本单位是“帧”（Frame）。Gateway在技术上并不需要理解帧里承载的业务内容（JSON文本还是二进制数据），它的核心工作是进行TCP流的透明代理。但实现方式上有讲究：

1. 字节流透传：最直接的方式是，在Gateway内部为每个WebSocket连接创建两个通道：一个从客户端到后端（client->gateway->backend），一个从后端到客户端（backend->gateway->client）。Gateway从一端读取到原始的TCP字节流后，直接写入另一端。这种方式效率最高，Gateway完全不解码WebSocket帧。Netty等高性能网络框架常采用此模式。

2. 帧级别代理：Gateway会解析WebSocket帧，获取其操作码（Opcode，如文本、二进制、关闭、Ping/Pong），然后再转发。这种方式给了Gateway更多控制权，例如：

   • 可以拦截和处理特定类型的帧：比如，Gateway可以自己响应Ping帧，而不必转发给后端，减轻后端压力。
   • 可以实现消息级别的过滤和审计：可以解析文本帧中的JSON内容，进行敏感词过滤或日志记录。
   • 更容易实现高级功能：如消息广播、会话绑定等。 OpenClaw的Gateway更可能采用这种方式，因为它需要与业务逻辑有一定交互，例如将消息路由到不同的处理链。

代码示例：Spring Cloud Gateway的简单WebSocket路由

# application.yml spring: cloud: gateway: routes: - id: websocket_route uri: lb:ws://backend-service # 指向后端WebSocket服务，lb表示负载均衡 predicates: - Path=/api/ws/** filters: - StripPrefix=1 # 去掉路径前缀 /api

这个配置告诉Gateway，所有以/api/ws/开头的请求，都代理到backend-service这个服务（通过服务发现找到实例），并去掉路径中的/api前缀。对于WebSocket，uri协议需要用ws://或wss://。

4.2 心跳、超时与连接保活

长连接面临的最大挑战之一就是稳定性。网络波动、服务重启、防火墙策略都可能导致连接意外中断。Gateway必须有一套机制来检测和处理死连接。

1. Ping/Pong心跳：WebSocket协议定义了Ping（操作码0x9）和Pong（操作码0xA）控制帧。Gateway可以主动向客户端或后端服务发送Ping帧，并期望在合理时间内收到Pong回复。如果超时未收到，则可以认为连接已失效，主动关闭它。

   • 策略：Gateway可以定时（如每30秒）向客户端发送Ping。同时，它也应该处理来自客户端的Ping，并回复Pong。对于后端服务，Gateway作为客户端，也需要实现心跳逻辑。

2. 读写超时（Idle Timeout）：这是防止连接僵死的重要设置。如果在一个连接上，长时间（如300秒）没有读取到任何数据，或者长时间无法写入数据，则应触发超时，关闭连接。

   • 在Spring Cloud Gateway中配置：

     spring: cloud: gateway: httpclient: connect-timeout: 1000 # 连接超时 1秒 response-timeout: 5s # 响应超时 5秒 pool: max-idle-time: 60s # 连接池空闲时间

     注意，对于WebSocket，response-timeout可能不适用，需要依赖底层Netty的idleStateHandler。

3. 连接重连策略（客户端侧）：虽然这是客户端的职责，但Gateway的设计需要考虑到这一点。Gateway应能优雅地处理连接断开，并在客户端重连时，尽可能恢复会话上下文（如果设计了有状态会话）。客户端在检测到连接关闭后，应实现指数退避等策略进行重连。

4.3 处理连接断开与“502 Bad Gateway”

现在我们可以更深入地分析开头的错误：unexpected status 502 bad gateway: unknown error, url: http://127.0.0.1:15721/v1/responses。

这个错误发生在Gateway试图与后端服务（地址127.0.0.1:15721）通信时。502 Bad Gateway是一个HTTP状态码，表明Gateway从上游服务器收到了一个无效的响应。在WebSocket场景下，这通常意味着：

1. 后端服务进程崩溃或未启动：服务根本不在15721端口监听。
2. 网络问题：防火墙规则阻止了Gateway到后端服务端口的通信。
3. 后端服务繁忙或处理异常：服务进程还在，但因为死锁、内存溢出、或内部错误，无法正常处理新的连接请求，TCP连接建立失败或被拒绝。
4. 协议不匹配：Gateway以为后端是WebSocket服务，但实际后端是一个普通的HTTP服务，返回了非101的响应（如200、404、500），Gateway将其解释为502错误。
5. 后端服务主动断开：在握手成功后，后端服务可能因为自身错误（如got exception）而立即关闭了连接，Gateway感知到后向上游传递了错误。

排查步骤：

• 检查后端服务状态：curl -v http://127.0.0.1:15721/health或查看服务日志。
• 检查网络连通性：从Gateway容器/主机telnet 127.0.0.1 15721。
• 查看Gateway日志：通常会有更详细的错误信息，例如连接被拒绝（Connection refused）、连接超时（Connection timeout）等。
• 查看后端服务日志：搜索错误堆栈，例如OpenClaw日志中可能出现的openclaw llamap svr operator(): got exception，这指明了后端服务内部的具体问题。

5. 高级特性与生产环境配置

理解了基础原理后，我们来看看如何配置一个健壮、可用于生产环境的WebSocket Gateway。这里以Spring Cloud Gateway为例，因为它与OpenClaw的Java技术栈契合度很高。

5.1 集成服务发现与负载均衡

在微服务架构中，后端服务实例是动态变化的。Gateway需要集成服务发现中心（如Nacos）。

spring: application: name: openclaw-gateway cloud: nacos: discovery: server-addr: localhost:8848 gateway: discovery: locator: enabled: true # 开启通过服务发现自动创建路由 routes: - id: openclaw-ws-route # 使用 lb:// 前缀，后面跟注册在Nacos中的服务名 uri: lb:ws://openclaw-core-service predicates: - Path=/v1/chat/ws filters: - TokenRelay # 如果使用OAuth2，可以中继Token

这样配置后，Gateway会自动从Nacos获取openclaw-core-service的所有健康实例列表，并使用负载均衡器（默认为轮询）将WebSocket连接请求分发到不同的实例上。

5.2 集成Sentinel实现限流与熔断

对于公开的API，限流是保护后端服务的必备手段。我们可以集成Sentinel来保护WebSocket路由。

1. 添加依赖：

   <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId> </dependency> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-alibaba-sentinel-gateway</artifactId> </dependency>

2. 配置流控规则（可以通过Sentinel Dashboard动态配置）：

   • 针对WebSocket连接建立限流：限制每秒/每分钟允许建立的WebSocket连接数（Route ID为资源）。
   • 针对消息限流：限制某个客户端每秒发送的消息数量（这需要更细粒度的控制，可能结合自定义过滤器实现）。

3. 配置熔断降级：当路由到某个后端服务的失败率（如超时、5xx错误）超过阈值时，Sentinel会熔断该路由，在一段时间内所有请求快速失败，直接返回预设的响应（如一个友好的错误消息），而不是堆积并拖垮Gateway和后端。

5.3 关键配置参数详解

以下是一些在application.yml中需要特别关注的配置，它们直接影响WebSocket连接的稳定性和性能：

server: # Netty服务器配置，对WebSocket性能影响大 netty: connection-timeout: 5000 # 连接超时时间 idle-timeout: 3600000 # 连接空闲超时（1小时），对于长连接很重要 spring: cloud: gateway: # 全局HTTP客户端配置，用于Gateway向后端发起请求（包括WebSocket握手） httpclient: connect-timeout: 2000 # 连接后端超时 response-timeout: 0 # 响应超时，0表示不超时（对WebSocket流很重要） pool: type: elastic # 连接池类型 max-connections: 1000 # 最大连接数 max-idle-time: 60s # 连接最大空闲时间 acquire-timeout: 45000 # 从池中获取连接的超时时间 # WebSocket特殊配置（如果使用特定实现） websocket: max-frame-payload-length: 65536 # 单帧最大负载长度，防止过大消息攻击

• response-timeout: 0：对于WebSocket代理，通常建议设置为0或一个非常大的值，因为连接一旦建立，就会一直保持，没有“响应结束”的概念。设置超时会导致长时间没有消息交互时连接被误杀。
• max-frame-payload-length：限制单次传输消息的大小，是安全防护的一部分。

5.4 自定义过滤器应对复杂场景

Spring Cloud Gateway的强大之处在于其过滤器链。我们可以编写自定义过滤器来处理OpenClaw特有的逻辑。

场景：在WebSocket握手时注入用户身份假设前端在连接时通过查询参数传递了Token：ws://gateway/ws?token=eyJhbGci...。我们需要在Gateway中验证这个Token，并将用户信息传递给后端服务。

@Component public class WsAuthFilter implements GlobalFilter, Ordered { @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request = exchange.getRequest(); // 1. 判断是否为WebSocket握手请求 if (isWebSocketUpgrade(request)) { // 2. 从查询参数获取token String token = request.getQueryParams().getFirst("token"); if (StringUtils.hasText(token)) { // 3. 验证token（伪代码） UserInfo userInfo = jwtUtil.validateToken(token); if (userInfo != null) { // 4. 将用户信息添加到请求头，传递给后端服务 ServerHttpRequest newRequest = request.mutate() .header("X-User-Id", userInfo.getUserId()) .header("X-User-Name", userInfo.getUsername()) .build(); return chain.filter(exchange.mutate().request(newRequest).build()); } } // 5. 认证失败，拒绝握手 exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED); return exchange.getResponse().setComplete(); } // 非WebSocket请求，直接放行 return chain.filter(exchange); } private boolean isWebSocketUpgrade(ServerHttpRequest request) { String upgrade = request.getHeaders().getUpgrade(); return "websocket".equalsIgnoreCase(upgrade); } @Override public int getOrder() { return -1; // 高优先级，在其他过滤器之前执行 } }

这个过滤器会在握手阶段拦截请求，完成Token验证，并将用户信息以HTTP头的方式传递给后端业务服务。后端服务就可以直接从请求头中获取用户上下文，无需再次解析Token。

6. 实战：从零搭建与调试OpenClaw的WebSocket Gateway

理论说得再多，不如动手实践。让我们基于Spring Cloud Gateway，一步步搭建一个用于OpenClaw的WebSocket Gateway，并解决几个典型问题。

6.1 项目初始化与基础依赖

使用Spring Initializr创建一个新项目，选择依赖：

• Spring Cloud Gateway
• Reactive Web(Netty运行时，必须)
• Lombok(可选，简化代码)

pom.xml关键依赖：

<dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-gateway</artifactId> </dependency> <!-- 如果集成Nacos --> <dependency> <groupId>com.alibaba.cloud</groupId> <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId> </dependency>

6.2 核心路由配置

在application.yml中配置路由，假设我们的OpenClaw核心服务在localhost:8081提供了WebSocket端点/ws/chat。

server: port: 8080 # Gateway服务端口 spring: application: name: openclaw-gateway cloud: gateway: routes: - id: openclaw_chat_ws uri: ws://localhost:8081 # 后端WebSocket服务地址 predicates: - Path=/api/v1/chat/ws filters: # 重写路径：将 /api/v1/chat/ws 重写为后端服务的 /ws/chat - RewritePath=/api/v1/chat/ws, /ws/chat # 添加响应头，方便调试 - AddResponseHeader=X-Gateway, openclaw-gateway # 全局CORS配置（如果前端是浏览器） globalcors: cors-configurations: '[/**]': allowed-origins: "*" # 生产环境应指定具体域名 allowed-methods: "*" allowed-headers: "*" allow-credentials: true

启动Gateway（端口8080）和后端服务（端口8081）。前端应连接ws://localhost:8080/api/v1/chat/ws。

6.3 调试与问题排查

问题1：连接失败，前端报WebSocket connection to 'ws://localhost:8080/api/v1/chat/ws' failed

• 检查1：服务是否启动：确认Gateway（8080）和后端服务（8081）进程都在运行。
• 检查2：后端WebSocket端点是否存在：用curl或Postman/Apifox发送一个WebSocket握手请求到后端，看是否返回101。

  curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: localhost:8081" -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" http://localhost:8081/ws/chat

  预期应看到HTTP/1.1 101 Switching Protocols。
• 检查3：Gateway日志：启用Debug日志查看路由匹配和过滤器执行情况。

  logging: level: org.springframework.cloud.gateway: DEBUG reactor.netty.http.client: DEBUG

问题2：连接建立后立即断开，Gateway日志出现io.netty.handler.codec.DecoderException: javax.net.ssl.SSLException: Received fatal alert: internal_error

• 分析：这通常发生在混合使用ws和wss，或者SSL/TLS配置不正确时。确保你的URI协议一致。如果后端服务是ws，Gateway配置的uri也必须是ws://。如果后端是wss（自签名或正式证书），Gateway需要配置信任该证书，或者使用ssl: true相关配置（在Spring Cloud Gateway中，对ws://和wss://的支持是内置的，但wss需要正确配置HTTP客户端信任库）。

问题3：连接一段时间后无规律断开，日志有ReadTimeoutException或idle timeout

• 解决：这是读写超时问题。需要调整Netty和HTTP客户端的超时设置，如上文5.3节所示。最关键的是将spring.cloud.gateway.httpclient.response-timeout设置为一个很大的值或0。同时，确保客户端和服务端都实现了Ping/Pong心跳保活机制。

6.4 使用Apifox测试WebSocket连接

图形化工具能更直观地测试。以Apifox为例：

1. 新建一个WebSocket请求。
2. 地址栏填写：ws://localhost:8080/api/v1/chat/ws。
3. 在“请求头”或“查询参数”中添加认证信息（如果配置了上述的WsAuthFilter，可以加?token=xxx）。
4. 点击“连接”。如果成功，状态会显示“已连接”。
5. 在下方消息框发送一条JSON消息，例如OpenClaw的对话指令：{"message": "你好，请介绍下你自己。", "stream": true}。
6. 观察响应消息。如果配置了流式输出，你会看到多条返回消息。

通过Apifox，你可以清晰地看到握手请求和响应，以及每一条来往的数据帧，是调试Gateway路由和过滤器的利器。

7. 进阶：处理OpenClaw中的流式响应与错误传递

OpenClaw与大模型交互的一个核心特性是流式响应（Streaming Response）。模型生成Token的过程是逐步的，后端服务会通过同一个WebSocket连接，持续不断地向前端发送部分结果。这对Gateway提出了特殊要求。

7.1 流式响应的代理挑战

在流式场景下，后端服务可能长时间（数十秒甚至数分钟）保持连接活跃并持续发送数据帧。Gateway必须：

• 保持连接畅通：不能因为超时设置而中断连接。
• 高效转发数据帧：避免在Gateway层造成缓冲区堆积或额外的序列化/反序列化开销。
• 正确处理错误：如果流式传输过程中后端服务崩溃，Gateway需要将错误（如连接重置）及时、准确地通知给客户端，而不是让客户端一直等待。

配置要点：除了设置超时，还需要关注Netty的缓冲区大小。

spring: cloud: gateway: httpclient: # 增加响应缓冲区大小，应对大流量流式数据 max-in-memory-size: 10MB # 默认是256KB，对于大模型流式输出可能不够

7.2 错误传递与用户体验

当Gateway收到后端返回的502 Bad Gateway时，如何传递给前端？直接关闭WebSocket连接并设置一个关闭帧（Close Frame）的理由码（Reason Code）是一种方式。WebSocket协议定义了4000-4999为私有用途。

我们可以自定义一个错误处理过滤器，在收到后端错误时，向客户端发送一个包含错误信息的最后文本消息，然后优雅地关闭连接。

@Component public class WsErrorHandlingFilter implements GlobalFilter, Ordered { @Override public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) { return chain.filter(exchange).onErrorResume(throwable -> { // 判断是否是WebSocket请求 if (isWebSocketUpgrade(exchange.getRequest())) { // 获取已建立的WebSocket会话（这需要更底层的处理，此处为概念演示） // 在实际中，可能需要订阅连接关闭事件或使用更低级的API // 这里简化处理：记录日志，依赖Gateway默认的错误返回机制 log.error("WebSocket代理出错: {}", throwable.getMessage()); // Gateway通常会返回一个502响应给握手请求，或直接断开连接 } // 对于非WebSocket错误，继续传递 return Mono.error(throwable); }); } // ... isWebSocketUpgrade 方法省略 }

更佳实践是，在Gateway和后端服务的通信协议中，约定一个错误消息格式。例如，即使在后端服务内部异常时，也尝试发送一个格式为{"type": "error", "content": "Internal server error"}的JSON文本帧到Gateway，再由Gateway原样转发给客户端。这样客户端就能友好地展示错误信息，而不是遭遇突兀的连接断开。

7.3 性能监控与度量

在生产环境，我们需要监控Gateway的健康状况。

• Spring Boot Actuator：暴露/actuator/gateway/routes端点查看路由信息，/actuator/metrics查看各项指标（如请求计数、延迟）。
• Micrometer + Prometheus + Grafana：集成Micrometer，将Gateway的详细指标（如活跃WebSocket连接数、每秒新建连接数、路由延迟百分位数、错误率等）导出到Prometheus，并在Grafana中绘制仪表盘。
• 分布式追踪：集成Sleuth/Zipkin，为每一个WebSocket连接及其转发的消息分配Trace ID，可以在复杂的微服务调用链中追踪一个用户对话的全路径，对于排查unexpected status 502 bad gateway这类问题非常有帮助。

搭建一个稳定、高效的WebSocket Gateway，是OpenClaw这类实时交互系统不可或缺的一环。它远不止是简单的端口转发，而是集安全、路由、负载均衡、容错、监控于一体的基础设施组件。吃透其原理，掌握其配置，才能让你在部署和运维OpenClaw时游刃有余，从容应对各种网络和性能挑战。当再次面对502 Bad Gateway时，你不再是无头苍蝇，而是能够沿着Gateway这条线索，直击问题根源。