1. 从一次线上事故引出进度条永远停在了 43%先说个真实场景。上个月某天凌晨客户运维群突然炸了说管理后台的“批量数据导出进度条”卡在 43% 再也不动。查了后端日志任务还在正常跑数据库里进度字段也在持续刷新但前端页面就像被按了暂停键。我第一反应是 WebSocket 断了结果一看页面控制台连接的是 SSE 接口错误码 503。再往后追发现了一个特别微妙的现象Spring Cloud Gateway 转发普通 HTTP 接口一切正常唯独转发 SSE 流式接口时要么连接建立后没数据要么推了几条就静默断开。那次事故从出现到定位折腾了半个晚上最后根源是网关层的响应超时配置。很多人以为 SSE 就是“后端开个长连接不停 write 数据”网关作为透传层应该天然支持。但实际上 Spring Cloud Gateway 是基于 Netty 的响应式网关它的很多默认设计都是面向“短平快”请求的。把 SSE 流式响应丢进去就像拿高速公路收费站去处理一支马拉松队伍——不是不能过但过了几道默认关卡就会被拦下来、限流甚至直接踢出去。这篇文章就把我在实际项目中踩过的坑、排查的思路、以及最终落地的转发方案完整拆开讲一遍。适合三类人看一是刚准备用 Gateway 转发 SSE 但还没上线的二是已经被线上 SSE 不稳定折磨到焦头烂额的三是想彻底搞懂网关与长连接之间底层逻辑的同学。2. 先搞清楚 SSE 在网关这一层到底发生了什么2.1 SSE 与普通 HTTP 请求的本质差异SSE 全称 Server-Sent Events服务端单向推送技术数据格式是text/event-stream。它的工作方式很朴素客户端发起一个普通 GET 请求服务端不结束响应而是持续往同一个连接里写数据块。每个数据块以data:开头、空行结尾浏览器原生EventSource对象负责解析和触发事件。这里有一个很关键的点SSE 本质上仍然是一次 HTTP 响应但这个响应永远不会正常结束直到业务结束或连接被切断。对比一下普通请求与 SSE 的差异维度普通 REST 请求SSE 长连接响应结束时机业务处理完即结束业务全程保持连接持续推送响应头 Content-Typeapplication/json 等text/event-stream数据到达方式一次性返回完整 body分多次、逐步写入 body连接持续时间毫秒到秒级秒到小时级对中间层的要求短连接超时即可不能有缓冲、不能全局短超时、不能压缩缓冲网关在中间扮演的角色不是简单把请求转发过去就完事。它需要对上游响应做字节级透传每一个写回客户端的DataBuffer都应该尽可能快地 flush。但现实是网关默认会做很多“对普通请求友好、对 SSE 致命”的处理。2.2 浏览器 EventSource 自带的重连机制掩盖了真正的故障这一点特别容易误导排查方向。浏览器的 EventSource 在连接断开后会自动重连而且默认间隔只有 1~3 秒。如果网关因为超时或缓冲把连接掐断了前端用户看到的不是“报错”而是页面卡住不动或者过了几秒突然又收到几条旧数据接着又卡住。这种“时断时续”的现象表面上像后端推送逻辑有 Bug实际上链路根本没通。更坑的是重连时浏览器会自动携带Last-Event-ID头服务端如果没有针对这个头实现“续传”那重连后推给前端的就是最新数据中间空档期的数据就丢了。进度条一会儿 43%重连后直接跳到 51%然后再也不动用户会以为程序算错数了实际上只是缺了中间一批事件。理解了这两点再看 Spring Cloud Gateway就能明白它默认配置下会踩多少个坑了。3. 五大坑位逐个拆解超时、缓冲、压缩、心跳与响应改写3.1 坑位一默认响应超时就是一个定时炸弹Spring Cloud Gateway 底层用的是 Reactor Netty 的HttpClient这个客户端的response-timeout默认值是5 秒。注意这不是“连接超时”而是“从发送请求到收到完整响应所允许的时间”。普通接口 5 秒内返回完全够用但 SSE 接口如果服务端前几秒不推数据或者推送节奏比较慢网关会直接判死主动断开连接后端连接顺手被掐掉。这个坑最恶心的地方在于它不像普通超时那样稳定复现。假如你的 SSE 接口启动后立即推送一批数据比如初始化进度 0% 到 10%网关收到这些数据后超时计时器是在“收到第一个字节”时重置还是在整个响应未完成时就一刀切实际上 Reactor Netty 的 response-timeout 计算的是“整个响应是否在指定时间内完成”。但 SSE 这种永远不会“完成”的响应只要有一次数据到达间隔超过阈值就可能被掐断。解决这个问题的第一步很简单把这个超时时间调到足够大或者针对 SSE 路由单独设置。全局配置方式spring: cloud: gateway: httpclient: response-timeout: 120s按路由单独设置避免所有接口都放宽超时spring: cloud: gateway: routes: - id: sse-route uri: lb://task-service predicates: - Path/task/sse/** metadata: response-timeout: 3600000 connect-timeout: 3000这里的metadata里的response-timeout和connect-timeout是 SCG 原生支持的按路由超时配置单位是毫秒。把 SSE 路由的响应超时调到 1 小时甚至更长基本就绕开了这个坑。不过这只是第一关。很多项目里即使解决了超时SSE 还是有问题那就往下看。3.2 坑位二响应被聚合或改写SSE 瞬间变成普通 JSONSpring Cloud Gateway 中有一些过滤器会把上游响应整体读取到内存中处理完再一次性写回这类过滤器包括ModifyResponseBodyGatewayFilterFactory、自定义的GlobalFilter中对ServerHttpResponse做buffer操作等。只要你的过滤器里有“先把响应 body 读出来再处理再返回”这样的逻辑SSE 就废了。为什么因为 SSE 是边产生边推送的流式数据如果读完整再写回意味着必须等业务全部跑完才能拿到完整数据那前端就是在等待一个永远不结束的响应直到超时断连。而且把text/event-stream当字符串去解析重写还会因为事件边界无法识别而出各种乱码和错位。我见过一个项目为了在网关层统一给响应包一层{ code: 0, data: ... }结构在全局 Filter 里调用了ModifyResponseBody过滤器工厂。上线后普通接口好好的SSE 接口全线超时。排查了很久才意识到SSE 根本不能套普通响应的壳子。处理方案其实很粗暴SSE 路径的过滤器必须走字节直通不做任何响应体层面的解析与修改。3.3 坑位三Gzip 压缩把实时流变成了定时批处理如果网关或前置 Nginx 配了 Gzip 压缩而且Content-Type匹配范围包含了text/event-stream那就出大问题了。HTTP 压缩的工作原理是把一段输出缓存到一定大小后再统一压缩发送对于一次性响应这没毛病但对于 SSE 这种需要“逐条即时推送”的场景压缩层会积压数据直到攒够一批才向前端吐一次。结果是前端收到的数据像挤牙膏严重时几十秒都不动一次看起来和断连差不多。检查方法也简单用 curl 访问网关看响应头curl -N -H Accept: text/event-stream http://localhost:8080/task/sse/1001 -I如果响应头里出现Content-Encoding: gzip基本就是这个问题。解决办法之一是让网关或 Nginx 对 SSE 路径禁用压缩location /task/sse/ { proxy_pass http://backend; proxy_buffering off; proxy_cache off; proxy_set_header Accept-Encoding identity; gzip off; chunked_transfer_encoding on; proxy_read_timeout 3600s; }同时 Spring 侧如果启用了压缩响应也要把text/event-stream排除出去。我个人的经验是SSE 数据本身通常是些小型文本片段压缩收益不大但引入的延迟和缓冲问题却非常致命所以干脆全链路对 SSE 路径关掉压缩最省事。3.4 坑位四服务端心跳间隔与中间层空闲超时打架SSE 连接建立后如果业务在某些阶段没有事件产生连接就会处于“空闲”状态。很多中间件包括部分网关里的 Idle State Handler、Nginx 的proxy_read_timeout、云厂商的 LB都会清理空闲连接。这个清理动作本是防止资源浪费但对于 SSE 来说却像定时炸弹。服务端必须主动发送心跳注释行:\n\n或: heartbeat\n\n来维持连接活性。但这里又有个节奏匹配问题如果你的心跳间隔是 60 秒而某个中间层的空闲超时是 30 秒那照样被切。心跳间隔必须小于链路中所有空闲超时中的最小值。Spring Boot 中对 SSE 加心跳最简单的方式是启动一个定时任务向响应的SseEmitter发送注释消息SseEmitter emitter new SseEmitter(0L); // 0L 表示不超时 ScheduledExecutorService scheduler Executors.newScheduledThreadPool(1); scheduler.scheduleAtFixedRate(() - { try { emitter.send(SseEmitter.event().comment(heartbeat)); } catch (IOException e) { emitter.completeWithError(e); } }, 0, 15, TimeUnit.SECONDS);SseEmitter.event().comment(heartbeat)这种方式发送的注释行浏览器 EventSource 会忽略它但中间层会因为连接上有数据流动而保持连接存活。项目里我习惯把心跳间隔设为 15 秒因为云环境很多四层 LB 的连接空闲超时是 60 秒再叠加更严格的网关层也能兜住。3.5 坑位五在响应头上下黑手破坏了流式传输的前提有人为了“优化”响应头在网关 Filter 里统一执行了以下操作清理所有不确定的响应头、把Transfer-Encoding改掉、或者强行设置Content-Length。对 SSE 来说Content-Length是一个绝对不能设置的值因为 SSE 的响应体是无限增长的。如果网关在转发时给响应加了Content-Length客户端包括浏览器和 WebClient就会等够指定字节数再解析直接导致流式失效。还有Cache-Control虽然不致命但为了让 EventSource 每次重连都能拿到最新数据建议在网关层对 SSE 路径统一设置Cache-Control: no-cache, no-transform X-Accel-Buffering: noX-Accel-Buffering: no是给 Nginx 看的告诉它这个响应不能做缓冲这个头在生产环境排查“数据攒批”问题时有奇效。3.6 一份相对稳妥的 SSE 转发改造样板讲完坑位直接给一份经过线上验证的改造方案。核心思路是对 SSE 路径绕过绝大多数标准过滤器直接用 WebClient 建立到下游的连接拿到上游的响应流后用 DataBuffer 原样写回客户端。先建一个专门用于 SSE 的过滤器Component public class SseRelayGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request exchange.getRequest(); String path request.getURI().getPath(); if (!path.startsWith(/task/sse/)) { return chain.filter(exchange); } // SSE 请求直接交给专用转发逻辑 return relaySse(exchange, buildDownstreamUrl(request)); } private MonoVoid relaySse(ServerWebExchange exchange, String downstreamUrl) { ServerHttpResponse response exchange.getResponse(); response.getHeaders().setContentType(MediaType.TEXT_EVENT_STREAM); response.getHeaders().set(Cache-Control, no-cache, no-transform); response.getHeaders().set(X-Accel-Buffering, no); WebClient webClient WebClient.builder() .baseUrl(downstreamUrl) .codecs(configurer - configurer.defaultCodecs().maxInMemorySize(1024 * 1024)) .build(); return webClient.get() .uri(exchange.getRequest().getURI().getRawPath()) .headers(headers - headers.addAll(exchange.getRequest().getHeaders())) .accept(MediaType.TEXT_EVENT_STREAM) .exchangeToMono(clientResponse - { response.setStatusCode(clientResponse.statusCode()); return response.writeWith(clientResponse.bodyToFlux(DataBuffer.class)); }); } private String buildDownstreamUrl(ServerWebExchange exchange) { // 从路由配置中获取真正要转发的下游地址 // 也可以从 LoadBalancerClient 获取实例地址 return http://task-service; } Override public int getOrder() { return -100; // 优先级调高尽量提前执行减少后续过滤器的干扰 } }需要注意几点exchangeToMono拿到的是已经越过“等待完整响应”阶段的上游响应流可以逐块转发。response.writeWith(clientResponse.bodyToFlux(DataBuffer.class))是字节级透传不解析 SSE 内部结构所以不会破坏事件边界。下游地址建议直接用服务发现拿到具体实例避免走额外一层lb://的负载均衡过滤逻辑。这个过滤器只拦截 SSE 路径其他请求继续走标准网关链。如果你的 Gateway 是被 Nginx 再包了一层那还要在 Nginx 的 location 配置里关掉缓冲和压缩。做了这三层处理网关过滤器直通、Nginx 关缓冲、关压缩SSE 才算真正跑通了。4. 集群部署下 SSE 的连接亲和与断点续传4.1 网关集群本身没问题问题是后端服务多实例“Spring Cloud Gateway 能做集群吗”答案是肯定的。Gateway 本身是无状态的路由信息可以从配置中心拉取多个Gateway实例前面挂负载均衡器就能平滑扩展。但 SSE 场景下真正让人头疼的其实是后端服务实例的扩展。假如你的task-service部署了 3 个实例客户端 A 的 SSE 连接被网关负载均衡到了实例 1连接建立后这个连接上的数据只能由实例 1 推送。一旦发生网络抖动导致连接断开浏览器 EventSource 自动重连网关再次负载均衡时可能把请求路由到实例 2。如果实例 2 没有客户端 A 的任务上下文它根本不知道要推送什么直接返回 404 或者空数据。要解决这类问题一个直观的做法是让负载均衡带上会话亲和Session Affinity比如 Nginx 的ip_hash或按 Cookie 做哈希。但我强烈建议谨慎使用因为 SSE 连接持续时间很长如果按 IP 哈希某个办公网段下所有用户都会固定打到同一个后端实例上很容易造成单实例连接数爆炸。4.2 用事件游标实现真正可靠的断点续传更稳妥的方案是让每个 SSE 连接带上唯一的客户端 ID后端基于 Redis 记录每个客户端已经推送到了哪个事件 ID重连时读取Last-Event-ID从游标位置继续往下发。大致流程如下前端用EventSource(/task/sse/{clientId})建立连接断线重连时浏览器自动带上Last-Event-ID头。后端收到请求后先查 Rediskey sse:client:{clientId}:cursor拿到上次已发送的最后一条事件 ID。如果游标存在从游标之后的数据开始加载推送如果不存在则从当前实时数据开始推。每推送一条消息同步更新 Redis 中的游标。游标记录的粒度不用太细建议每推送 N 条或每 1 秒批量更新一次避免频繁写 Redis 造成性能瓶颈。另外SSE 重连要解决事件窗口期补偿这取决于你的数据是否能缓存一段时间。如果业务允许可以在 Redis 里维护一个最近 10 分钟的事件环形缓冲重连时优先从缓冲区读取补发比持久化到数据库要快得多。4.3 跨实例的事件广播别让推送逻辑绑定本地内存还有一个经常被忽视的问题如果触发事件的任务是在实例 1 上执行完的但事件需要通过实例 2 上建立的 SSE 连接推送给客户端 B怎么办SSE 连接是长连接它绑定了建立连接的那个实例事件产生的位置和连接所在的位置可能不在同一个节点上。解决方案很简单用 Redis Pub/Sub 或 Redis Stream 做事件广播。任意实例产生事件后把消息发布到特定的 channel所有实例都订阅这个 channel收到事件后判断“当前实例上是否有对应客户端的活跃连接”有就推送没有就忽略。这是经典的“本地推送全局订阅”模式也是我目前在生产环境用过最稳的方案。用 Spring Data Redis 接入广播并判断本地连接时要注意把连接上下文放到一个ConcurrentHashMap里同时做好连接关闭时的清理否则推送时遍历到一堆已失效的 SseEmitter会出现大量异常日志压过真正有效的推送日志。5. 前端 Vue3 接入时很容易误判的几个点5.1 EventSource 的天然限制只能 GET、不能自定义 Header浏览器原生 EventSource 有几个硬性限制只支持 GET 请求、不能自定义请求头、无法携带 Authorization Header。如果你的业务接口要求 POST 传参或者需要带上 token原生方案就卡壳了。现在的项目里我基本不用原生 EventSource而是用fetch配合ReadableStream手写一个通用的 SSE 客户端。这样既能 POST又能自由设置请求头还方便接入 AbortController 控制连接生命周期。核心代码大概这样async function connectSSE(url, body, { signal, onMessage }) { const response await fetch(url, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${localStorage.getItem(token)} }, body: JSON.stringify(body), signal }); if (!response.ok || !response.body) { throw new Error(SSE connect failed: ${response.status}); } const reader response.body.getReader(); const decoder new TextDecoder(utf-8); let buffer ; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const events buffer.split(\n\n); buffer events.pop() || ; for (const rawEvent of events) { const dataLine rawEvent.split(\n).find(line line.startsWith(data:)); if (dataLine) { const payload dataLine.slice(5).trim(); onMessage?.(parseSSEJson(payload)); } } } }5.2 高频推送下的进度条更新别把 Vue 的响应式系统搞崩进度条场景的特点是更新频率高、单次数据量小。有些后端每秒推送十几条进度消息前端如果每条消息都直接progress.value payload.precentVue 的响应式依赖更新和 DOM 重绘会被触发十几次。短时间内还好长时间跑下来页面可能明显卡顿。我的习惯是加一个简单的节流机制本质上是“最后一次数据覆盖前一次”例如使用requestAnimationFrame合并渲染周期let ticking false; let latestProgress {}; function onMessage(payload) { latestProgress payload; if (ticking) return; ticking true; requestAnimationFrame(() { progress.value latestProgress.precent; statusText.value latestProgress.message; ticking false; }); }用requestAnimationFrame把高频事件合并到浏览器渲染帧里进度条既平滑又省性能。5.3 线上接口的 CORS 与协议问题容易误报为后端异常本地联调时一切正常部署到线上后 EventSource 或者 fetch 直接挂掉这类问题见过太多次了。典型场景有两种一是页面属于https://example.com而 SSE 接口用的是http://api.example.com浏览器对“混合内容”Mixed Content有严格限制会直接拦截二是接口域名跨域时后端没返回正确的Access-Control-Allow-Origin响应头浏览器把跨域请求拦截了。处理混合内容问题方案只有一个把所有 SSE 接口统一升级成 HTTPS并且请求地址用和页面同协议、同域名的网关路径从根上规避。跨域问题则需要在网关或后端全局处理 CORS 响应头尤其要注意SSE 连接存活期间预检请求OPTIONS本身也需要走通网关的过滤器链别把 OPTIONS 请求在全局过滤器里提前拦截掉了。6. 一套可复用的 SSE 故障排查链路6.1 从 curl 到抓包的逐层排查顺序排查 SSE 类问题我有一套固定的执行顺序基本能定位 90% 的故障。第一步先绕过所有中间层直接请求后端接口curl -N -H Accept: text/event-stream http://127.0.0.1:8082/task/sse/1001如果这里数据正常说明后端没问题问题出在网关或前置代理。如果这里就不正常直接转后端排查别浪费时间看网关。第二步请求网关地址curl -N -H Accept: text/event-stream http://gateway:8080/task/sse/1001 -v加上-v后重点看响应头。如果Content-Type不是text/event-stream说明网关响应头被改写了如果出现Content-Length说明流式传输被截断如果半天没输出大概率是缓冲或超时问题。第三步如果加了 Nginx再在 Nginx 层试一次看看是不是 Nginx 把连接给缓冲了。这一步可以快速定位故障在哪一层。必要时用tcpdump抓包确认连接是客户端断开还是服务端断开tcpdump -i any port 8080 -A重点看断连时的 TCP 报文方向。如果是网关先发 FIN问题在网关如果是后端先发 FIN问题在下游服务。6.2 常见现象速查表下面这个表格是我整理出来分享给团队同学的遇到问题先对着查一遍能节省大量排查时间现象可能原因优先检查项连接建立后完全不推数据网关全局响应超时下游未发心跳且触发负载均衡空闲清理路由 metadata 的 response-timeout下游心跳间隔推了几条后断连响应被聚合/改写中间层空闲超时小于心跳间隔检查是否有 ModifyResponseBodynginx proxy_read_timeout前端数据一次来一大包不是逐条出现Gzip 压缩缓冲Nginx proxy_buffering 开启响应头是否带 Content-Encoding: gzipNginx 关缓冲每次刷新都能收到最新数据但缺中间事件重连后未基于 Last-Event-ID 续传后端是否读取 Last-Event-ID是否实现事件游标响应头带了 Content-Length过滤器或中间层修改了响应头检查自定义 GlobalFilterNginx 是否重写响应头数据频率低时页面几秒没反应频繁报错EventSource 自动重连掩盖了底层断连抓包确认断连方向检查网关 access log 中对应请求耗时6.3 打开日志开关看过滤器执行链的先后顺序Spring Cloud Gateway 的应用里日志在排查过滤器问题时很关键。尤其是当自定义过滤器太多、判断不出谁改写了响应时一定别靠猜直接把日志级别调低logging: level: org.springframework.cloud.gateway: DEBUG org.springframework.http.server.reactive: DEBUG reactor.netty.http.client: DEBUG看日志时会发现线程名里有reactor-http-nio-*这是 Netty 的 event loop 线程所有 I/O 操作都在这些线程上执行记得千万不要在过滤器里做Thread.sleep()或者.block()这类阻塞操作否则会直接拖垮整个网关的吞吐量。如果有自定义过滤器建议把它要处理的路径和顺序号打出来验证它是不是对 SSE 路径产生了副作用。最后一个实用建议围绕 SSE 转发的问题还有个值得留意的版本细节不同版本的 Spring Cloud Gateway 配置超时属性的位置有差异。比如spring.cloud.gateway.httpclient.response-timeout在 2020.0.x 和 2022.0.x 之间有过迁移调整某些版本里还会多出spring.cloud.gateway.httpclient.global.response-timeout这种新属性。升级网关版本后最好专门跑一遍 SSE 用例别默认配置文件能无缝迁移。个人经验是SSE 这类问题排查到最后往往不是隐藏很深的设计缺陷而是一个没改的默认超时参数、一个顺手加上的全局响应包装过滤器或者一台没有关缓冲的 Nginx。把这些“不起眼的默认值”都梳理清楚SSE 在网关层的稳定运行就没有想象中那么难了。
Spring Cloud Gateway转发SSE的实战指南：五大坑位与解决方案
1. 从一次线上事故引出进度条永远停在了 43%先说个真实场景。上个月某天凌晨客户运维群突然炸了说管理后台的“批量数据导出进度条”卡在 43% 再也不动。查了后端日志任务还在正常跑数据库里进度字段也在持续刷新但前端页面就像被按了暂停键。我第一反应是 WebSocket 断了结果一看页面控制台连接的是 SSE 接口错误码 503。再往后追发现了一个特别微妙的现象Spring Cloud Gateway 转发普通 HTTP 接口一切正常唯独转发 SSE 流式接口时要么连接建立后没数据要么推了几条就静默断开。那次事故从出现到定位折腾了半个晚上最后根源是网关层的响应超时配置。很多人以为 SSE 就是“后端开个长连接不停 write 数据”网关作为透传层应该天然支持。但实际上 Spring Cloud Gateway 是基于 Netty 的响应式网关它的很多默认设计都是面向“短平快”请求的。把 SSE 流式响应丢进去就像拿高速公路收费站去处理一支马拉松队伍——不是不能过但过了几道默认关卡就会被拦下来、限流甚至直接踢出去。这篇文章就把我在实际项目中踩过的坑、排查的思路、以及最终落地的转发方案完整拆开讲一遍。适合三类人看一是刚准备用 Gateway 转发 SSE 但还没上线的二是已经被线上 SSE 不稳定折磨到焦头烂额的三是想彻底搞懂网关与长连接之间底层逻辑的同学。2. 先搞清楚 SSE 在网关这一层到底发生了什么2.1 SSE 与普通 HTTP 请求的本质差异SSE 全称 Server-Sent Events服务端单向推送技术数据格式是text/event-stream。它的工作方式很朴素客户端发起一个普通 GET 请求服务端不结束响应而是持续往同一个连接里写数据块。每个数据块以data:开头、空行结尾浏览器原生EventSource对象负责解析和触发事件。这里有一个很关键的点SSE 本质上仍然是一次 HTTP 响应但这个响应永远不会正常结束直到业务结束或连接被切断。对比一下普通请求与 SSE 的差异维度普通 REST 请求SSE 长连接响应结束时机业务处理完即结束业务全程保持连接持续推送响应头 Content-Typeapplication/json 等text/event-stream数据到达方式一次性返回完整 body分多次、逐步写入 body连接持续时间毫秒到秒级秒到小时级对中间层的要求短连接超时即可不能有缓冲、不能全局短超时、不能压缩缓冲网关在中间扮演的角色不是简单把请求转发过去就完事。它需要对上游响应做字节级透传每一个写回客户端的DataBuffer都应该尽可能快地 flush。但现实是网关默认会做很多“对普通请求友好、对 SSE 致命”的处理。2.2 浏览器 EventSource 自带的重连机制掩盖了真正的故障这一点特别容易误导排查方向。浏览器的 EventSource 在连接断开后会自动重连而且默认间隔只有 1~3 秒。如果网关因为超时或缓冲把连接掐断了前端用户看到的不是“报错”而是页面卡住不动或者过了几秒突然又收到几条旧数据接着又卡住。这种“时断时续”的现象表面上像后端推送逻辑有 Bug实际上链路根本没通。更坑的是重连时浏览器会自动携带Last-Event-ID头服务端如果没有针对这个头实现“续传”那重连后推给前端的就是最新数据中间空档期的数据就丢了。进度条一会儿 43%重连后直接跳到 51%然后再也不动用户会以为程序算错数了实际上只是缺了中间一批事件。理解了这两点再看 Spring Cloud Gateway就能明白它默认配置下会踩多少个坑了。3. 五大坑位逐个拆解超时、缓冲、压缩、心跳与响应改写3.1 坑位一默认响应超时就是一个定时炸弹Spring Cloud Gateway 底层用的是 Reactor Netty 的HttpClient这个客户端的response-timeout默认值是5 秒。注意这不是“连接超时”而是“从发送请求到收到完整响应所允许的时间”。普通接口 5 秒内返回完全够用但 SSE 接口如果服务端前几秒不推数据或者推送节奏比较慢网关会直接判死主动断开连接后端连接顺手被掐掉。这个坑最恶心的地方在于它不像普通超时那样稳定复现。假如你的 SSE 接口启动后立即推送一批数据比如初始化进度 0% 到 10%网关收到这些数据后超时计时器是在“收到第一个字节”时重置还是在整个响应未完成时就一刀切实际上 Reactor Netty 的 response-timeout 计算的是“整个响应是否在指定时间内完成”。但 SSE 这种永远不会“完成”的响应只要有一次数据到达间隔超过阈值就可能被掐断。解决这个问题的第一步很简单把这个超时时间调到足够大或者针对 SSE 路由单独设置。全局配置方式spring: cloud: gateway: httpclient: response-timeout: 120s按路由单独设置避免所有接口都放宽超时spring: cloud: gateway: routes: - id: sse-route uri: lb://task-service predicates: - Path/task/sse/** metadata: response-timeout: 3600000 connect-timeout: 3000这里的metadata里的response-timeout和connect-timeout是 SCG 原生支持的按路由超时配置单位是毫秒。把 SSE 路由的响应超时调到 1 小时甚至更长基本就绕开了这个坑。不过这只是第一关。很多项目里即使解决了超时SSE 还是有问题那就往下看。3.2 坑位二响应被聚合或改写SSE 瞬间变成普通 JSONSpring Cloud Gateway 中有一些过滤器会把上游响应整体读取到内存中处理完再一次性写回这类过滤器包括ModifyResponseBodyGatewayFilterFactory、自定义的GlobalFilter中对ServerHttpResponse做buffer操作等。只要你的过滤器里有“先把响应 body 读出来再处理再返回”这样的逻辑SSE 就废了。为什么因为 SSE 是边产生边推送的流式数据如果读完整再写回意味着必须等业务全部跑完才能拿到完整数据那前端就是在等待一个永远不结束的响应直到超时断连。而且把text/event-stream当字符串去解析重写还会因为事件边界无法识别而出各种乱码和错位。我见过一个项目为了在网关层统一给响应包一层{ code: 0, data: ... }结构在全局 Filter 里调用了ModifyResponseBody过滤器工厂。上线后普通接口好好的SSE 接口全线超时。排查了很久才意识到SSE 根本不能套普通响应的壳子。处理方案其实很粗暴SSE 路径的过滤器必须走字节直通不做任何响应体层面的解析与修改。3.3 坑位三Gzip 压缩把实时流变成了定时批处理如果网关或前置 Nginx 配了 Gzip 压缩而且Content-Type匹配范围包含了text/event-stream那就出大问题了。HTTP 压缩的工作原理是把一段输出缓存到一定大小后再统一压缩发送对于一次性响应这没毛病但对于 SSE 这种需要“逐条即时推送”的场景压缩层会积压数据直到攒够一批才向前端吐一次。结果是前端收到的数据像挤牙膏严重时几十秒都不动一次看起来和断连差不多。检查方法也简单用 curl 访问网关看响应头curl -N -H Accept: text/event-stream http://localhost:8080/task/sse/1001 -I如果响应头里出现Content-Encoding: gzip基本就是这个问题。解决办法之一是让网关或 Nginx 对 SSE 路径禁用压缩location /task/sse/ { proxy_pass http://backend; proxy_buffering off; proxy_cache off; proxy_set_header Accept-Encoding identity; gzip off; chunked_transfer_encoding on; proxy_read_timeout 3600s; }同时 Spring 侧如果启用了压缩响应也要把text/event-stream排除出去。我个人的经验是SSE 数据本身通常是些小型文本片段压缩收益不大但引入的延迟和缓冲问题却非常致命所以干脆全链路对 SSE 路径关掉压缩最省事。3.4 坑位四服务端心跳间隔与中间层空闲超时打架SSE 连接建立后如果业务在某些阶段没有事件产生连接就会处于“空闲”状态。很多中间件包括部分网关里的 Idle State Handler、Nginx 的proxy_read_timeout、云厂商的 LB都会清理空闲连接。这个清理动作本是防止资源浪费但对于 SSE 来说却像定时炸弹。服务端必须主动发送心跳注释行:\n\n或: heartbeat\n\n来维持连接活性。但这里又有个节奏匹配问题如果你的心跳间隔是 60 秒而某个中间层的空闲超时是 30 秒那照样被切。心跳间隔必须小于链路中所有空闲超时中的最小值。Spring Boot 中对 SSE 加心跳最简单的方式是启动一个定时任务向响应的SseEmitter发送注释消息SseEmitter emitter new SseEmitter(0L); // 0L 表示不超时 ScheduledExecutorService scheduler Executors.newScheduledThreadPool(1); scheduler.scheduleAtFixedRate(() - { try { emitter.send(SseEmitter.event().comment(heartbeat)); } catch (IOException e) { emitter.completeWithError(e); } }, 0, 15, TimeUnit.SECONDS);SseEmitter.event().comment(heartbeat)这种方式发送的注释行浏览器 EventSource 会忽略它但中间层会因为连接上有数据流动而保持连接存活。项目里我习惯把心跳间隔设为 15 秒因为云环境很多四层 LB 的连接空闲超时是 60 秒再叠加更严格的网关层也能兜住。3.5 坑位五在响应头上下黑手破坏了流式传输的前提有人为了“优化”响应头在网关 Filter 里统一执行了以下操作清理所有不确定的响应头、把Transfer-Encoding改掉、或者强行设置Content-Length。对 SSE 来说Content-Length是一个绝对不能设置的值因为 SSE 的响应体是无限增长的。如果网关在转发时给响应加了Content-Length客户端包括浏览器和 WebClient就会等够指定字节数再解析直接导致流式失效。还有Cache-Control虽然不致命但为了让 EventSource 每次重连都能拿到最新数据建议在网关层对 SSE 路径统一设置Cache-Control: no-cache, no-transform X-Accel-Buffering: noX-Accel-Buffering: no是给 Nginx 看的告诉它这个响应不能做缓冲这个头在生产环境排查“数据攒批”问题时有奇效。3.6 一份相对稳妥的 SSE 转发改造样板讲完坑位直接给一份经过线上验证的改造方案。核心思路是对 SSE 路径绕过绝大多数标准过滤器直接用 WebClient 建立到下游的连接拿到上游的响应流后用 DataBuffer 原样写回客户端。先建一个专门用于 SSE 的过滤器Component public class SseRelayGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request exchange.getRequest(); String path request.getURI().getPath(); if (!path.startsWith(/task/sse/)) { return chain.filter(exchange); } // SSE 请求直接交给专用转发逻辑 return relaySse(exchange, buildDownstreamUrl(request)); } private MonoVoid relaySse(ServerWebExchange exchange, String downstreamUrl) { ServerHttpResponse response exchange.getResponse(); response.getHeaders().setContentType(MediaType.TEXT_EVENT_STREAM); response.getHeaders().set(Cache-Control, no-cache, no-transform); response.getHeaders().set(X-Accel-Buffering, no); WebClient webClient WebClient.builder() .baseUrl(downstreamUrl) .codecs(configurer - configurer.defaultCodecs().maxInMemorySize(1024 * 1024)) .build(); return webClient.get() .uri(exchange.getRequest().getURI().getRawPath()) .headers(headers - headers.addAll(exchange.getRequest().getHeaders())) .accept(MediaType.TEXT_EVENT_STREAM) .exchangeToMono(clientResponse - { response.setStatusCode(clientResponse.statusCode()); return response.writeWith(clientResponse.bodyToFlux(DataBuffer.class)); }); } private String buildDownstreamUrl(ServerWebExchange exchange) { // 从路由配置中获取真正要转发的下游地址 // 也可以从 LoadBalancerClient 获取实例地址 return http://task-service; } Override public int getOrder() { return -100; // 优先级调高尽量提前执行减少后续过滤器的干扰 } }需要注意几点exchangeToMono拿到的是已经越过“等待完整响应”阶段的上游响应流可以逐块转发。response.writeWith(clientResponse.bodyToFlux(DataBuffer.class))是字节级透传不解析 SSE 内部结构所以不会破坏事件边界。下游地址建议直接用服务发现拿到具体实例避免走额外一层lb://的负载均衡过滤逻辑。这个过滤器只拦截 SSE 路径其他请求继续走标准网关链。如果你的 Gateway 是被 Nginx 再包了一层那还要在 Nginx 的 location 配置里关掉缓冲和压缩。做了这三层处理网关过滤器直通、Nginx 关缓冲、关压缩SSE 才算真正跑通了。4. 集群部署下 SSE 的连接亲和与断点续传4.1 网关集群本身没问题问题是后端服务多实例“Spring Cloud Gateway 能做集群吗”答案是肯定的。Gateway 本身是无状态的路由信息可以从配置中心拉取多个Gateway实例前面挂负载均衡器就能平滑扩展。但 SSE 场景下真正让人头疼的其实是后端服务实例的扩展。假如你的task-service部署了 3 个实例客户端 A 的 SSE 连接被网关负载均衡到了实例 1连接建立后这个连接上的数据只能由实例 1 推送。一旦发生网络抖动导致连接断开浏览器 EventSource 自动重连网关再次负载均衡时可能把请求路由到实例 2。如果实例 2 没有客户端 A 的任务上下文它根本不知道要推送什么直接返回 404 或者空数据。要解决这类问题一个直观的做法是让负载均衡带上会话亲和Session Affinity比如 Nginx 的ip_hash或按 Cookie 做哈希。但我强烈建议谨慎使用因为 SSE 连接持续时间很长如果按 IP 哈希某个办公网段下所有用户都会固定打到同一个后端实例上很容易造成单实例连接数爆炸。4.2 用事件游标实现真正可靠的断点续传更稳妥的方案是让每个 SSE 连接带上唯一的客户端 ID后端基于 Redis 记录每个客户端已经推送到了哪个事件 ID重连时读取Last-Event-ID从游标位置继续往下发。大致流程如下前端用EventSource(/task/sse/{clientId})建立连接断线重连时浏览器自动带上Last-Event-ID头。后端收到请求后先查 Rediskey sse:client:{clientId}:cursor拿到上次已发送的最后一条事件 ID。如果游标存在从游标之后的数据开始加载推送如果不存在则从当前实时数据开始推。每推送一条消息同步更新 Redis 中的游标。游标记录的粒度不用太细建议每推送 N 条或每 1 秒批量更新一次避免频繁写 Redis 造成性能瓶颈。另外SSE 重连要解决事件窗口期补偿这取决于你的数据是否能缓存一段时间。如果业务允许可以在 Redis 里维护一个最近 10 分钟的事件环形缓冲重连时优先从缓冲区读取补发比持久化到数据库要快得多。4.3 跨实例的事件广播别让推送逻辑绑定本地内存还有一个经常被忽视的问题如果触发事件的任务是在实例 1 上执行完的但事件需要通过实例 2 上建立的 SSE 连接推送给客户端 B怎么办SSE 连接是长连接它绑定了建立连接的那个实例事件产生的位置和连接所在的位置可能不在同一个节点上。解决方案很简单用 Redis Pub/Sub 或 Redis Stream 做事件广播。任意实例产生事件后把消息发布到特定的 channel所有实例都订阅这个 channel收到事件后判断“当前实例上是否有对应客户端的活跃连接”有就推送没有就忽略。这是经典的“本地推送全局订阅”模式也是我目前在生产环境用过最稳的方案。用 Spring Data Redis 接入广播并判断本地连接时要注意把连接上下文放到一个ConcurrentHashMap里同时做好连接关闭时的清理否则推送时遍历到一堆已失效的 SseEmitter会出现大量异常日志压过真正有效的推送日志。5. 前端 Vue3 接入时很容易误判的几个点5.1 EventSource 的天然限制只能 GET、不能自定义 Header浏览器原生 EventSource 有几个硬性限制只支持 GET 请求、不能自定义请求头、无法携带 Authorization Header。如果你的业务接口要求 POST 传参或者需要带上 token原生方案就卡壳了。现在的项目里我基本不用原生 EventSource而是用fetch配合ReadableStream手写一个通用的 SSE 客户端。这样既能 POST又能自由设置请求头还方便接入 AbortController 控制连接生命周期。核心代码大概这样async function connectSSE(url, body, { signal, onMessage }) { const response await fetch(url, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${localStorage.getItem(token)} }, body: JSON.stringify(body), signal }); if (!response.ok || !response.body) { throw new Error(SSE connect failed: ${response.status}); } const reader response.body.getReader(); const decoder new TextDecoder(utf-8); let buffer ; while (true) { const { done, value } await reader.read(); if (done) break; buffer decoder.decode(value, { stream: true }); const events buffer.split(\n\n); buffer events.pop() || ; for (const rawEvent of events) { const dataLine rawEvent.split(\n).find(line line.startsWith(data:)); if (dataLine) { const payload dataLine.slice(5).trim(); onMessage?.(parseSSEJson(payload)); } } } }5.2 高频推送下的进度条更新别把 Vue 的响应式系统搞崩进度条场景的特点是更新频率高、单次数据量小。有些后端每秒推送十几条进度消息前端如果每条消息都直接progress.value payload.precentVue 的响应式依赖更新和 DOM 重绘会被触发十几次。短时间内还好长时间跑下来页面可能明显卡顿。我的习惯是加一个简单的节流机制本质上是“最后一次数据覆盖前一次”例如使用requestAnimationFrame合并渲染周期let ticking false; let latestProgress {}; function onMessage(payload) { latestProgress payload; if (ticking) return; ticking true; requestAnimationFrame(() { progress.value latestProgress.precent; statusText.value latestProgress.message; ticking false; }); }用requestAnimationFrame把高频事件合并到浏览器渲染帧里进度条既平滑又省性能。5.3 线上接口的 CORS 与协议问题容易误报为后端异常本地联调时一切正常部署到线上后 EventSource 或者 fetch 直接挂掉这类问题见过太多次了。典型场景有两种一是页面属于https://example.com而 SSE 接口用的是http://api.example.com浏览器对“混合内容”Mixed Content有严格限制会直接拦截二是接口域名跨域时后端没返回正确的Access-Control-Allow-Origin响应头浏览器把跨域请求拦截了。处理混合内容问题方案只有一个把所有 SSE 接口统一升级成 HTTPS并且请求地址用和页面同协议、同域名的网关路径从根上规避。跨域问题则需要在网关或后端全局处理 CORS 响应头尤其要注意SSE 连接存活期间预检请求OPTIONS本身也需要走通网关的过滤器链别把 OPTIONS 请求在全局过滤器里提前拦截掉了。6. 一套可复用的 SSE 故障排查链路6.1 从 curl 到抓包的逐层排查顺序排查 SSE 类问题我有一套固定的执行顺序基本能定位 90% 的故障。第一步先绕过所有中间层直接请求后端接口curl -N -H Accept: text/event-stream http://127.0.0.1:8082/task/sse/1001如果这里数据正常说明后端没问题问题出在网关或前置代理。如果这里就不正常直接转后端排查别浪费时间看网关。第二步请求网关地址curl -N -H Accept: text/event-stream http://gateway:8080/task/sse/1001 -v加上-v后重点看响应头。如果Content-Type不是text/event-stream说明网关响应头被改写了如果出现Content-Length说明流式传输被截断如果半天没输出大概率是缓冲或超时问题。第三步如果加了 Nginx再在 Nginx 层试一次看看是不是 Nginx 把连接给缓冲了。这一步可以快速定位故障在哪一层。必要时用tcpdump抓包确认连接是客户端断开还是服务端断开tcpdump -i any port 8080 -A重点看断连时的 TCP 报文方向。如果是网关先发 FIN问题在网关如果是后端先发 FIN问题在下游服务。6.2 常见现象速查表下面这个表格是我整理出来分享给团队同学的遇到问题先对着查一遍能节省大量排查时间现象可能原因优先检查项连接建立后完全不推数据网关全局响应超时下游未发心跳且触发负载均衡空闲清理路由 metadata 的 response-timeout下游心跳间隔推了几条后断连响应被聚合/改写中间层空闲超时小于心跳间隔检查是否有 ModifyResponseBodynginx proxy_read_timeout前端数据一次来一大包不是逐条出现Gzip 压缩缓冲Nginx proxy_buffering 开启响应头是否带 Content-Encoding: gzipNginx 关缓冲每次刷新都能收到最新数据但缺中间事件重连后未基于 Last-Event-ID 续传后端是否读取 Last-Event-ID是否实现事件游标响应头带了 Content-Length过滤器或中间层修改了响应头检查自定义 GlobalFilterNginx 是否重写响应头数据频率低时页面几秒没反应频繁报错EventSource 自动重连掩盖了底层断连抓包确认断连方向检查网关 access log 中对应请求耗时6.3 打开日志开关看过滤器执行链的先后顺序Spring Cloud Gateway 的应用里日志在排查过滤器问题时很关键。尤其是当自定义过滤器太多、判断不出谁改写了响应时一定别靠猜直接把日志级别调低logging: level: org.springframework.cloud.gateway: DEBUG org.springframework.http.server.reactive: DEBUG reactor.netty.http.client: DEBUG看日志时会发现线程名里有reactor-http-nio-*这是 Netty 的 event loop 线程所有 I/O 操作都在这些线程上执行记得千万不要在过滤器里做Thread.sleep()或者.block()这类阻塞操作否则会直接拖垮整个网关的吞吐量。如果有自定义过滤器建议把它要处理的路径和顺序号打出来验证它是不是对 SSE 路径产生了副作用。最后一个实用建议围绕 SSE 转发的问题还有个值得留意的版本细节不同版本的 Spring Cloud Gateway 配置超时属性的位置有差异。比如spring.cloud.gateway.httpclient.response-timeout在 2020.0.x 和 2022.0.x 之间有过迁移调整某些版本里还会多出spring.cloud.gateway.httpclient.global.response-timeout这种新属性。升级网关版本后最好专门跑一遍 SSE 用例别默认配置文件能无缝迁移。个人经验是SSE 这类问题排查到最后往往不是隐藏很深的设计缺陷而是一个没改的默认超时参数、一个顺手加上的全局响应包装过滤器或者一台没有关缓冲的 Nginx。把这些“不起眼的默认值”都梳理清楚SSE 在网关层的稳定运行就没有想象中那么难了。
