1. 项目概述为什么“流式输出”不是调个超时就完事的你有没有遇到过这样的场景前端页面上大模型的回答像打字机一样逐字蹦出来看着很酷但突然卡住、断连、报错——stream disconnected before completion: idle timeout waiting for sse。这时候团队里有人立刻去改timeout30000有人翻出 Spring Boot 的server.tomcat.connection-timeout还有人跑去查 Nginx 的proxy_read_timeout……结果改了一圈问题照旧甚至更糟超时设太短回答截断设太长连接堆积线程池爆满整个服务雪崩。这恰恰就是标题里说的“90%只知道调超时的人”——把流式输出当成一个 HTTP 接口调用只盯着“等多久”却完全忽略了它本质是一条持续数秒至数十秒、承载数百到数千个事件帧event: message, data: {...}的双向生命线。SSEServer-Sent Events不是 REST它不遵循请求-响应的瞬时契约而是一次握手、长期维系、按需推送的“管道协议”。Java 生态里从 Controller 层的SseEmitter到 Web 容器Tomcat/Undertow的连接管理再到反向代理Nginx/Alb的保活策略最后到前端 EventSource 的重连逻辑中间横跨至少 5 层技术栈。任何一层的配置失配、资源争抢或异常兜底缺失都会在用户侧表现为“回答一半就没了”。我做过 7 个不同规模的大模型应用上线其中 4 个在流式输出环节栽过跟头。最典型的一次是金融问答系统上线首日20% 的用户反馈“回答卡在‘根据’两个字就停了”。排查发现不是模型慢而是 Tomcat 默认的keepAliveTimeout60000与 Nginx 的proxy_read_timeout60形成微妙的时间差当模型生成耗时 58 秒时Tomcat 认为连接健康Nginx 却已提前关闭 socket导致后端还在发data:前端早已收不到。这种问题根本不会出现在单元测试里只会在真实流量下暴露。所以“全链路排查方案”的核心不是找一个开关去拧而是建立一套可观察、可度量、可干预的流式通道健康视图。它要能告诉你当前活跃 SSE 连接有多少平均生命周期多长在哪一层被主动断开是后端主动 close还是代理强制 kill抑或是前端主动 abort每个环节的耗时分布如何这才是真正“领先”的起点——把玄学问题变成数据问题。2. 全链路架构拆解五层漏斗模型与关键决策点我把大模型流式输出的完整通路抽象为一个“五层漏斗模型”每一层都像一个过滤网既承担功能也埋藏风险。理解每层的职责边界和协作逻辑是设计排查方案的前提。2.1 第一层应用层Java/Spring Boot这是开发者最熟悉的战场核心是SseEmitter的创建、事件推送和异常处理。Spring Framework 5.2 原生支持 SSE但默认行为极具迷惑性SseEmitter构造时若不传参默认超时时间为 30 秒SseEmitter.DEFAULT_TIMEOUT且超时后 emitter 会自动调用complete()但不会抛出异常。这意味着你的业务代码可能根本不知道连接已死还在往一个已关闭的 emitter 写数据最终触发IllegalStateException: SseEmitter is already completed。SseEmitter.send()是异步非阻塞的它把事件放入内部队列就返回。如果队列满了默认容量 1024后续send()会直接抛出IllegalStateException。而这个队列满往往是因为下游某层比如 Tomcat 的 socket 缓冲区写不出去形成背压。提示不要依赖SseEmitter的默认超时。务必在构造时显式设置new SseEmitter(0L)0 表示永不超时把超时控制权交给更上层的业务逻辑或反向代理。我见过最坑的实践是在 Controller 里捕获IOException就emitter.complete()看似优雅实则掩盖了真实原因——这个IOException很可能是 Tomcat 因连接空闲被关闭而抛出的而非网络中断。真正的做法是在SseEmitter的onCompletion和onError回调里记录日志并关联唯一 traceId让后续排查能追溯到具体哪条连接、在哪个时刻、因何原因终止。2.2 第二层Web 容器层Tomcat/Undertow这是 Java 应用与操作系统 TCP 栈的桥梁也是超时配置最混乱的一层。以 Tomcat 为例有 4 个关键参数相互影响参数名默认值作用域与 SSE 的关系connectionTimeout20000msSocket 连接建立阶段影响首次握手SSE 不涉及keepAliveTimeout60000msKeep-Alive 连接空闲期核心SSE 连接在此期间无数据即被关闭maxKeepAliveRequests100单连接最大请求数SSE 是单请求长连接此值应设为-1不限制socketBuffer9000BSocket 发送缓冲区大小影响data:消息能否及时写出关键矛盾在于keepAliveTimeout必须严格大于你预期的最长模型响应时间比如 120 秒否则容器会主动断开。但设得过大又会导致大量空闲连接占用线程和内存。我的经验是将keepAliveTimeout设为模型 P95 响应时间的 1.5 倍并配合连接池监控。例如若模型 P95 是 80 秒则设keepAliveTimeout120000。注意Undertow 的配置逻辑完全不同。它用worker.io-threads和buffer-pool控制连接idle-timeout对应 Tomcat 的keepAliveTimeout。切勿套用 Tomcat 经验。2.3 第三层反向代理层Nginx/ALB这是生产环境最常被忽视的“隐形杀手”。Nginx 默认配置对 SSE 极其不友好proxy_read_timeout上游服务器发送两个响应之间的时间间隔。SSE 的data:帧之间可能间隔数秒此值必须大于最大帧间隔如设为 120s。proxy_send_timeoutNginx 向客户端发送响应的超时。SSE 是单向推送此值影响不大但建议设为同proxy_read_timeout。proxy_buffering off必须关闭否则 Nginx 会缓存所有data:帧直到整个流结束才推给前端彻底破坏流式体验。keepalive_timeoutNginx 与上游Java 应用的 keep-alive 超时。必须小于或等于 Tomcat 的keepAliveTimeout否则 Nginx 会先于 Tomcat 关闭连接。一次线上事故中我们发现 Nginx 的proxy_read_timeout60而模型在生成长文本时两个data:帧间隔偶尔达 65 秒Nginx 直接断连并返回 504。将proxy_read_timeout改为 120 后问题消失。但更深层的问题是Nginx 日志默认不记录 upstream 的连接关闭原因。你需要开启log_format并添加$upstream_http_content_type和$upstream_addr才能在日志里看到 “upstream prematurely closed connection while reading response header from upstream”。2.4 第四层网络传输层TCP/IP 与防火墙这一层通常由云厂商或 IDC 管理但它的影响是底层的。关键点有两个TCP Keepalive操作系统级的心跳机制。Linux 默认net.ipv4.tcp_keepalive_time72002 小时远大于 SSE 场景需求。若中间存在 NAT 设备如某些云负载均衡器它可能有自己的连接空闲超时常见 300-600 秒。当 NAT 超时而两端 TCP keepalive 未触发时连接会静默断开。解决方案是在 Java 应用层主动发送心跳帧event: heartbeat\ndata: {}\n\n间隔设为 NAT 超时的 1/3如 120 秒。MTU 与分片SSE 的data:帧是纯文本单帧过大1400 字节可能触发 IP 分片。若中间设备丢弃分片包会导致前端收到不完整的 JSON解析失败。我的实践是限制单帧data:长度 ≤ 1000 字符并在后端做简单分块如按 UTF-8 字符数切分避免在中文字符中间切断。2.5 第五层客户端层浏览器 EventSource前端不是被动接收者它的行为直接影响链路稳定性EventSource默认重连间隔为 3 秒且重连时会带上Last-Event-ID。但很多后端实现并未正确处理该 header导致重连后重复推送或丢失事件。浏览器对同一域名的 EventSource 连接数有限制Chrome 为 6 个。若用户打开多个标签页或页面内创建多个EventSource实例会触发DOMException: Failed to construct EventSource。EventSource的onerror回调非常笼统无法区分是网络错误、HTTP 错误还是连接被关闭。必须结合readyState变化和自定义心跳来判断真实状态。我推荐的前端健壮性方案是封装一个SseClient类内部维护一个retryCount每次重连指数退避1s, 2s, 4s...并在onmessage中解析data:为 JSON检查id字段是否递增若发现乱序或重复主动close()并重新初始化连接。3. 核心排查工具链与实操步骤从现象定位到根因有了架构认知下一步是建立一套可落地的排查流水线。我把它分为“三阶九步”第一阶看现象What第二阶查路径Where第三阶析根因Why。每一步都对应一个具体命令或工具确保你能亲手操作。3.1 第一阶现象诊断——确认问题类型与范围Step 1前端抓包锁定断连时刻与状态码打开 Chrome DevTools → Network → Filtereventsource→ 找到失败的 SSE 请求 → 点击查看。重点看Response Headers中的Content-Type: text/event-stream是否存在Status Code是200 OK后端主动关闭504 Gateway TimeoutNginx 断连0网络中断Preview或Response标签页最后收到的data:是什么是否完整是否有event: close实操心得若Status Code为0说明连接被浏览器或本地网络强制终止优先查客户端网络或防火墙若为504直奔 Nginx 配置若为200且Preview里有data:但没结束说明后端SseEmitter被complete()需查 Java 日志。Step 2服务端日志提取 traceId 与异常堆栈在 Java 应用的application.log中搜索关键词sse、emitter、IOException。关键日志模式// 正常完成 INFO c.e.c.SseController - [traceId:abc123] SSE connection completed successfully // 异常中断注意 stack trace ERROR c.e.c.SseController - [traceId:xyz789] Failed to send SSE event java.io.IOException: Broken pipe at sun.nio.ch.FileDispatcherImpl.write0(Native Method) ...Broken pipe通常意味着客户端已关闭 socketConnection reset则多为中间代理Nginx主动 reset。Step 3统计维度量化问题严重性不要只看单个 case。用 ELK 或 Grafana构建以下指标看板sse_connection_duration_seconds_bucketSSE 连接生命周期直方图P50/P90/P95sse_emitter_complete_total{reasontimeout}因超时关闭的连接数sse_emitter_error_total{errorioexception}IO 异常次数nginx_upstream_response_time_seconds_bucket{upstreamjava-app}Nginx 到 Java 的响应时间。若发现sse_connection_duration的 P95 与nginx_upstream_response_time的 P95 高度吻合说明瓶颈在 Nginx 层若前者远大于后者问题在 Java 应用或模型本身。3.2 第二阶路径追踪——逐层验证连接健康度Step 4绕过 Nginx直连 Java 应用用curl模拟 SSE 请求排除代理干扰curl -N -H Accept: text/event-stream http://localhost:8080/api/chat/stream?prompthello-N禁用 curl 的 buffering若此命令能稳定输出data:帧说明 Java 应用层正常问题在 Nginx 或网络若也中断检查 Tomcat 配置和 Java 日志。Step 5检查 Tomcat 连接状态进入 Tomcat 的manager/status页面需配置 manager 用户或用 JMX 查看Catalina:typeThreadPool,namehttp-nio-8080的currentThreadCount和keepAliveCount。若keepAliveCount持续高位100且currentThreadCount接近maxThreads说明连接积压需调大maxThreads或优化keepAliveTimeout。Step 6Nginx 实时连接监控在 Nginx 服务器上执行# 查看当前活跃连接数 ss -tnp | grep :80 | wc -l # 查看 upstream 连接状态需开启 stub_status echo get nginx status | nc localhost 80 | grep Active同时检查 Nginx error logtail -f /var/log/nginx/error.log | grep -i upstream.*prematurely出现此日志基本可断定是proxy_read_timeout不足。3.3 第三阶根因深挖——模拟与注入测试Step 7注入可控延迟复现超时场景在 Java Controller 中临时加入人工延迟模拟慢模型GetMapping(/api/chat/stream) public SseEmitter stream(RequestParam String prompt) { SseEmitter emitter new SseEmitter(0L); // 模拟模型生成前 3 秒发 3 帧然后停顿 70 秒再发最后一帧 CompletableFuture.runAsync(() - { try { emitter.send(SseEmitter.event().name(message).data(Hello)); Thread.sleep(1000); emitter.send(SseEmitter.event().name(message).data(World)); Thread.sleep(1000); emitter.send(SseEmitter.event().name(message).data(!)); Thread.sleep(70000); // 关键制造长空闲 emitter.send(SseEmitter.event().name(close).data(done)); } catch (Exception e) { emitter.completeWithError(e); } }); return emitter; }然后用curl测试观察在哪一层断开。这是最有效的“压力探针”。Step 8抓包分析 TCP 层行为在 Java 服务器上用tcpdump抓取 SSE 流量tcpdump -i any -w sse.pcap port 8080 and host client-ip用 Wireshark 打开sse.pcap过滤tcp.stream eq 0查看Server 是否在空闲期发送了ACK包TCP keepaliveClient 是否在某个时刻发送了FIN包Server 是否回应RST最后一个data:帧发出后Server 是否还有PSH包若看到 Server 发送PSH后Client 长时间无ACK说明 Client 网络或浏览器已断开。Step 9前端调试验证 EventSource 行为在浏览器 Console 中运行const es new EventSource(/api/chat/stream?prompttest); es.onopen () console.log(Connected); es.onmessage e console.log(Received:, e.data); es.onerror e console.log(Error:, e, es.readyState); es.addEventListener(close, e console.log(Close event:, e));观察es.readyState变化0(connecting) →1(open) →0(reconnecting)。若频繁在1和0间跳变且onerror无具体信息大概率是proxy_read_timeout触发了 Nginx 的 504。4. 全链路加固方案从配置到代码的七项实操准则排查是为了修复。基于上述分析我总结出七项必须落地的加固准则每一条都来自血泪教训。4.1 准则一Java 层——SseEmitter 的“三不原则”不依赖默认超时永远new SseEmitter(0L)超时由业务逻辑或外部组件控制。不忽略 onCompletion/onError在这两个回调里必须记录traceId、emitterId、System.currentTimeMillis()和reason如timeout、ioexception、complete并发送到统一日志中心。不裸写 send()封装一个safeSend()方法捕获IllegalStateException并检查emitter.isCompleted()若已完成则直接 return避免日志刷屏。private void safeSend(SseEmitter emitter, SseEmitter.SseEventBuilder event) { if (emitter null || emitter.isCompleted()) return; try { emitter.send(event); } catch (IllegalStateException e) { log.warn([SSE] Emitter already completed, skip send. traceId:{}, MDC.get(traceId)); } catch (IOException e) { log.error([SSE] IO error on send. traceId:{}, MDC.get(traceId), e); emitter.completeWithError(e); } }4.2 准则二Tomcat 层——keepAlive 的精准计算keepAliveTimeout不是拍脑袋的数字。计算公式keepAliveTimeout max(模型 P95 响应时间 × 1.5, 30000) 5000其中5000是预留 buffer。P95 时间从 APM 工具如 SkyWalking获取或用 Prometheus 的histogram_quantile(0.95, rate(http_server_requests_seconds_bucket[1h]))查询。同时必须设置Connector port8080 protocolHTTP/1.1 connectionTimeout20000 keepAliveTimeout120000 !-- 示例P9580s → 120s -- maxKeepAliveRequests-1 socketBuffer65536 /4.3 准则三Nginx 层——SSE 专用配置模板以下是我在线上环境验证过的最小可行配置upstream java-app { server 127.0.0.1:8080; keepalive 32; # 与 upstream 的 keepalive 连接数 } server { listen 80; location /api/chat/stream { proxy_pass http://java-app; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; # SSE 关键配置 proxy_buffering off; # 必须关闭 proxy_read_timeout 120; # 必须 ≥ keepAliveTimeout proxy_send_timeout 120; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 心跳保活可选但推荐 add_header Cache-Control no-cache; add_header X-Accel-Buffering no; } }4.4 准则四网络层——主动心跳与分帧策略在 Java 后端每 30 秒发送一次心跳帧// 在 SSE 推送循环中 long lastHeartbeat System.currentTimeMillis(); while (hasMoreTokens()) { String token nextToken(); safeSend(emitter, SseEmitter.event().name(message).data(token)); // 发送心跳 long now System.currentTimeMillis(); if (now - lastHeartbeat 30_000) { safeSend(emitter, SseEmitter.event().name(heartbeat).data({})); lastHeartbeat now; } }前端EventSource监听heartbeat事件重置自己的超时计时器。同时对长 token 做分帧public ListString splitToken(String token, int maxLength) { ListString chunks new ArrayList(); int start 0; while (start token.length()) { int end Math.min(start maxLength, token.length()); // 确保不在 UTF-8 多字节字符中间切断 while (end start (token.charAt(end - 1) 0xC0) 0x80) { end--; } chunks.add(token.substring(start, end)); start end; } return chunks; }4.5 准则五客户端层——健壮的 EventSource 封装class SseClient { constructor(url, options {}) { this.url url; this.options { ...options, retryDelay: 1000 }; this.emitter null; this.retryCount 0; this.lastEventId null; } connect() { this.emitter new EventSource(this.url (this.lastEventId ? last-event-id${this.lastEventId} : ), { withCredentials: true }); this.emitter.onopen () { this.retryCount 0; console.log(SSE connected); }; this.emitter.onmessage (e) { try { const data JSON.parse(e.data); this.lastEventId e.lastEventId || Date.now().toString(); // 处理业务数据 this.onMessage?.(data); } catch (err) { console.error(Parse SSE data error, err, e.data); } }; this.emitter.addEventListener(heartbeat, () { // 心跳重置超时 }); this.emitter.onerror (e) { console.error(SSE error, e, this.emitter.readyState); if (this.emitter.readyState EventSource.CLOSED) { this.reconnect(); } }; } reconnect() { if (this.emitter) this.emitter.close(); this.retryCount; const delay Math.min(this.options.retryDelay * Math.pow(2, this.retryCount), 30000); setTimeout(() this.connect(), delay); } }4.6 准则六监控告警——建立 SSE 健康水位线在 Prometheus 中定义以下告警规则- alert: SSE_Connection_Duration_P95_High expr: histogram_quantile(0.95, rate(sse_connection_duration_seconds_bucket[1h])) 120 for: 5m labels: severity: warning annotations: summary: SSE connection duration P95 120s - alert: SSE_Emitter_Complete_By_Timeout expr: rate(sse_emitter_complete_total{reasontimeout}[1h]) 0.1 for: 10m labels: severity: critical annotations: summary: More than 10% SSE connections timeout4.7 准则七发布流程——SSE 的灰度与回滚SSE 配置变更必须走灰度第一阶段仅对 1% 的流量开启新配置Nginx 的split_clients第二阶段监控新旧配置的sse_connection_duration和sse_emitter_error_total差异 5% 方可全量回滚预案若新配置导致504错误率上升 1%立即nginx -s reload切回旧配置。5. 常见问题速查表与独家避坑技巧最后整理一份高频问题速查表附上我踩过的坑和独门技巧。问题现象可能根因快速验证命令我的独家技巧前端 EventSource 频繁重连但无错误日志Nginxproxy_read_timeout 模型帧间隔curl -N http://nginx/sse观察是否在固定时间后断开在 Nginx 配置中加add_header X-SSE-Debug true;前端读取该 header 判断是否走代理Java 日志大量IllegalStateException: SseEmitter is already completed多线程并发调用send()或onComplete后仍有推送grep SseEmitter is already completed application.log | head -20在SseEmitter创建时用AtomicBoolean标记状态safeSend()中双重检查SSE 连接数暴涨Tomcat 线程池耗尽前端未正确close()EventSource或页面未销毁实例jstack pid | grep SseEmitter | wc -l在 Controller 的ExceptionHandler中对SseEmitter异常统一complete()并记录emitterId部分用户能用部分用户 504客户端网络存在 NAT 超时且未发心跳用不同运营商网络移动/联通/电信测试后端心跳帧event: heartbeat的data字段填入当前时间戳前端对比判断是否丢帧data:帧内容乱码或解析失败单帧过大触发 IP 分片或 UTF-8 截断tcpdump抓包看data:是否完整后端data字段用 Base64 编码前端atob()解码彻底规避编码问题Nginx error log 出现upstream sent too big header后端返回了过大的Set-Cookie或其他 headercurl -I http://localhost:8080/sse查看 header 大小在 Nginx 中加proxy_buffer_size 128k; proxy_buffers 4 256k;避坑技巧一用curl -v看清协议细节curl -v -N -H Accept: text/event-stream http://your-api会显示完整的 HTTP 交互包括HTTP/1.1 200 OK、Content-Type: text/event-stream、Connection: keep-alive以及最后的* transfer closed with outstanding read data remaining—— 这句就告诉你是服务端提前关闭了连接。避坑技巧二Tomcat 的maxThreads不是越大越好我曾将maxThreads从 200 调到 1000结果 GC 频率暴增。因为每个线程至少占用 1MB 栈空间1000 线程就是 1GB 内存。合理值 (预期并发 SSE 连接数) × 1.2。SSE 连接是 I/O 密集型不是 CPU 密集型线程数过多反而降低吞吐。避坑技巧三前端EventSource的withCredentials若你的 SSE 接口需要 Cookie 认证必须new EventSource(url, {withCredentials: true})否则浏览器不会发送 Cookie。但此时后端Access-Control-Allow-Origin不能是*必须指定具体域名否则 CORS 失败。避坑技巧四模型输出的data:必须是合法 JSON大模型输出的 token 可能包含换行符\n、双引号直接塞进data: {...}会破坏 SSE 格式。必须对data字段做 JSON.stringify()再替换掉\n和\rString safeData jsonStr.replace(\n, \\n).replace(\r, \\r); emitter.send(SseEmitter.event().name(message).data(safeData));避坑技巧五SSE 不是万能的该用 WebSocket 时别硬扛如果业务需要双向实时通信如用户中途取消、调整参数SSE 的单向性就是硬伤。这时果断用 WebSocket哪怕多写 200 行代码。我在一个实时协作编辑场景中强行用 SSE 模拟双向最后发现EventSource的重连机制与业务逻辑冲突不得不推倒重来。记住技术选型的第一原则是匹配业务本质而不是炫技。我在实际使用中发现最有效的排查方式永远是“从客户端发起逆向追踪”。先看浏览器 Network 里的失败请求再查 Nginx access log接着看 Tomcat 的 active connection最后翻 Java 日志。这个顺序比任何理论都管用。而且每一次成功的排查都应该沉淀为一条自动化检查脚本比如一个check-sse-health.sh它能自动执行curl、ss、jstat并输出健康报告。这样下次问题来时你只需要敲一行命令而不是手忙脚乱地翻文档。 
长河君 · 2026/9/17 6:17:40 · 阅读 1.2k 大模型流式输出全链路排查与加固指南
1. 项目概述为什么“流式输出”不是调个超时就完事的你有没有遇到过这样的场景前端页面上大模型的回答像打字机一样逐字蹦出来看着很酷但突然卡住、断连、报错——stream disconnected before completion: idle timeout waiting for sse。这时候团队里有人立刻去改timeout30000有人翻出 Spring Boot 的server.tomcat.connection-timeout还有人跑去查 Nginx 的proxy_read_timeout……结果改了一圈问题照旧甚至更糟超时设太短回答截断设太长连接堆积线程池爆满整个服务雪崩。这恰恰就是标题里说的“90%只知道调超时的人”——把流式输出当成一个 HTTP 接口调用只盯着“等多久”却完全忽略了它本质是一条持续数秒至数十秒、承载数百到数千个事件帧event: message, data: {...}的双向生命线。SSEServer-Sent Events不是 REST它不遵循请求-响应的瞬时契约而是一次握手、长期维系、按需推送的“管道协议”。Java 生态里从 Controller 层的SseEmitter到 Web 容器Tomcat/Undertow的连接管理再到反向代理Nginx/Alb的保活策略最后到前端 EventSource 的重连逻辑中间横跨至少 5 层技术栈。任何一层的配置失配、资源争抢或异常兜底缺失都会在用户侧表现为“回答一半就没了”。我做过 7 个不同规模的大模型应用上线其中 4 个在流式输出环节栽过跟头。最典型的一次是金融问答系统上线首日20% 的用户反馈“回答卡在‘根据’两个字就停了”。排查发现不是模型慢而是 Tomcat 默认的keepAliveTimeout60000与 Nginx 的proxy_read_timeout60形成微妙的时间差当模型生成耗时 58 秒时Tomcat 认为连接健康Nginx 却已提前关闭 socket导致后端还在发data:前端早已收不到。这种问题根本不会出现在单元测试里只会在真实流量下暴露。所以“全链路排查方案”的核心不是找一个开关去拧而是建立一套可观察、可度量、可干预的流式通道健康视图。它要能告诉你当前活跃 SSE 连接有多少平均生命周期多长在哪一层被主动断开是后端主动 close还是代理强制 kill抑或是前端主动 abort每个环节的耗时分布如何这才是真正“领先”的起点——把玄学问题变成数据问题。2. 全链路架构拆解五层漏斗模型与关键决策点我把大模型流式输出的完整通路抽象为一个“五层漏斗模型”每一层都像一个过滤网既承担功能也埋藏风险。理解每层的职责边界和协作逻辑是设计排查方案的前提。2.1 第一层应用层Java/Spring Boot这是开发者最熟悉的战场核心是SseEmitter的创建、事件推送和异常处理。Spring Framework 5.2 原生支持 SSE但默认行为极具迷惑性SseEmitter构造时若不传参默认超时时间为 30 秒SseEmitter.DEFAULT_TIMEOUT且超时后 emitter 会自动调用complete()但不会抛出异常。这意味着你的业务代码可能根本不知道连接已死还在往一个已关闭的 emitter 写数据最终触发IllegalStateException: SseEmitter is already completed。SseEmitter.send()是异步非阻塞的它把事件放入内部队列就返回。如果队列满了默认容量 1024后续send()会直接抛出IllegalStateException。而这个队列满往往是因为下游某层比如 Tomcat 的 socket 缓冲区写不出去形成背压。提示不要依赖SseEmitter的默认超时。务必在构造时显式设置new SseEmitter(0L)0 表示永不超时把超时控制权交给更上层的业务逻辑或反向代理。我见过最坑的实践是在 Controller 里捕获IOException就emitter.complete()看似优雅实则掩盖了真实原因——这个IOException很可能是 Tomcat 因连接空闲被关闭而抛出的而非网络中断。真正的做法是在SseEmitter的onCompletion和onError回调里记录日志并关联唯一 traceId让后续排查能追溯到具体哪条连接、在哪个时刻、因何原因终止。2.2 第二层Web 容器层Tomcat/Undertow这是 Java 应用与操作系统 TCP 栈的桥梁也是超时配置最混乱的一层。以 Tomcat 为例有 4 个关键参数相互影响参数名默认值作用域与 SSE 的关系connectionTimeout20000msSocket 连接建立阶段影响首次握手SSE 不涉及keepAliveTimeout60000msKeep-Alive 连接空闲期核心SSE 连接在此期间无数据即被关闭maxKeepAliveRequests100单连接最大请求数SSE 是单请求长连接此值应设为-1不限制socketBuffer9000BSocket 发送缓冲区大小影响data:消息能否及时写出关键矛盾在于keepAliveTimeout必须严格大于你预期的最长模型响应时间比如 120 秒否则容器会主动断开。但设得过大又会导致大量空闲连接占用线程和内存。我的经验是将keepAliveTimeout设为模型 P95 响应时间的 1.5 倍并配合连接池监控。例如若模型 P95 是 80 秒则设keepAliveTimeout120000。注意Undertow 的配置逻辑完全不同。它用worker.io-threads和buffer-pool控制连接idle-timeout对应 Tomcat 的keepAliveTimeout。切勿套用 Tomcat 经验。2.3 第三层反向代理层Nginx/ALB这是生产环境最常被忽视的“隐形杀手”。Nginx 默认配置对 SSE 极其不友好proxy_read_timeout上游服务器发送两个响应之间的时间间隔。SSE 的data:帧之间可能间隔数秒此值必须大于最大帧间隔如设为 120s。proxy_send_timeoutNginx 向客户端发送响应的超时。SSE 是单向推送此值影响不大但建议设为同proxy_read_timeout。proxy_buffering off必须关闭否则 Nginx 会缓存所有data:帧直到整个流结束才推给前端彻底破坏流式体验。keepalive_timeoutNginx 与上游Java 应用的 keep-alive 超时。必须小于或等于 Tomcat 的keepAliveTimeout否则 Nginx 会先于 Tomcat 关闭连接。一次线上事故中我们发现 Nginx 的proxy_read_timeout60而模型在生成长文本时两个data:帧间隔偶尔达 65 秒Nginx 直接断连并返回 504。将proxy_read_timeout改为 120 后问题消失。但更深层的问题是Nginx 日志默认不记录 upstream 的连接关闭原因。你需要开启log_format并添加$upstream_http_content_type和$upstream_addr才能在日志里看到 “upstream prematurely closed connection while reading response header from upstream”。2.4 第四层网络传输层TCP/IP 与防火墙这一层通常由云厂商或 IDC 管理但它的影响是底层的。关键点有两个TCP Keepalive操作系统级的心跳机制。Linux 默认net.ipv4.tcp_keepalive_time72002 小时远大于 SSE 场景需求。若中间存在 NAT 设备如某些云负载均衡器它可能有自己的连接空闲超时常见 300-600 秒。当 NAT 超时而两端 TCP keepalive 未触发时连接会静默断开。解决方案是在 Java 应用层主动发送心跳帧event: heartbeat\ndata: {}\n\n间隔设为 NAT 超时的 1/3如 120 秒。MTU 与分片SSE 的data:帧是纯文本单帧过大1400 字节可能触发 IP 分片。若中间设备丢弃分片包会导致前端收到不完整的 JSON解析失败。我的实践是限制单帧data:长度 ≤ 1000 字符并在后端做简单分块如按 UTF-8 字符数切分避免在中文字符中间切断。2.5 第五层客户端层浏览器 EventSource前端不是被动接收者它的行为直接影响链路稳定性EventSource默认重连间隔为 3 秒且重连时会带上Last-Event-ID。但很多后端实现并未正确处理该 header导致重连后重复推送或丢失事件。浏览器对同一域名的 EventSource 连接数有限制Chrome 为 6 个。若用户打开多个标签页或页面内创建多个EventSource实例会触发DOMException: Failed to construct EventSource。EventSource的onerror回调非常笼统无法区分是网络错误、HTTP 错误还是连接被关闭。必须结合readyState变化和自定义心跳来判断真实状态。我推荐的前端健壮性方案是封装一个SseClient类内部维护一个retryCount每次重连指数退避1s, 2s, 4s...并在onmessage中解析data:为 JSON检查id字段是否递增若发现乱序或重复主动close()并重新初始化连接。3. 核心排查工具链与实操步骤从现象定位到根因有了架构认知下一步是建立一套可落地的排查流水线。我把它分为“三阶九步”第一阶看现象What第二阶查路径Where第三阶析根因Why。每一步都对应一个具体命令或工具确保你能亲手操作。3.1 第一阶现象诊断——确认问题类型与范围Step 1前端抓包锁定断连时刻与状态码打开 Chrome DevTools → Network → Filtereventsource→ 找到失败的 SSE 请求 → 点击查看。重点看Response Headers中的Content-Type: text/event-stream是否存在Status Code是200 OK后端主动关闭504 Gateway TimeoutNginx 断连0网络中断Preview或Response标签页最后收到的data:是什么是否完整是否有event: close实操心得若Status Code为0说明连接被浏览器或本地网络强制终止优先查客户端网络或防火墙若为504直奔 Nginx 配置若为200且Preview里有data:但没结束说明后端SseEmitter被complete()需查 Java 日志。Step 2服务端日志提取 traceId 与异常堆栈在 Java 应用的application.log中搜索关键词sse、emitter、IOException。关键日志模式// 正常完成 INFO c.e.c.SseController - [traceId:abc123] SSE connection completed successfully // 异常中断注意 stack trace ERROR c.e.c.SseController - [traceId:xyz789] Failed to send SSE event java.io.IOException: Broken pipe at sun.nio.ch.FileDispatcherImpl.write0(Native Method) ...Broken pipe通常意味着客户端已关闭 socketConnection reset则多为中间代理Nginx主动 reset。Step 3统计维度量化问题严重性不要只看单个 case。用 ELK 或 Grafana构建以下指标看板sse_connection_duration_seconds_bucketSSE 连接生命周期直方图P50/P90/P95sse_emitter_complete_total{reasontimeout}因超时关闭的连接数sse_emitter_error_total{errorioexception}IO 异常次数nginx_upstream_response_time_seconds_bucket{upstreamjava-app}Nginx 到 Java 的响应时间。若发现sse_connection_duration的 P95 与nginx_upstream_response_time的 P95 高度吻合说明瓶颈在 Nginx 层若前者远大于后者问题在 Java 应用或模型本身。3.2 第二阶路径追踪——逐层验证连接健康度Step 4绕过 Nginx直连 Java 应用用curl模拟 SSE 请求排除代理干扰curl -N -H Accept: text/event-stream http://localhost:8080/api/chat/stream?prompthello-N禁用 curl 的 buffering若此命令能稳定输出data:帧说明 Java 应用层正常问题在 Nginx 或网络若也中断检查 Tomcat 配置和 Java 日志。Step 5检查 Tomcat 连接状态进入 Tomcat 的manager/status页面需配置 manager 用户或用 JMX 查看Catalina:typeThreadPool,namehttp-nio-8080的currentThreadCount和keepAliveCount。若keepAliveCount持续高位100且currentThreadCount接近maxThreads说明连接积压需调大maxThreads或优化keepAliveTimeout。Step 6Nginx 实时连接监控在 Nginx 服务器上执行# 查看当前活跃连接数 ss -tnp | grep :80 | wc -l # 查看 upstream 连接状态需开启 stub_status echo get nginx status | nc localhost 80 | grep Active同时检查 Nginx error logtail -f /var/log/nginx/error.log | grep -i upstream.*prematurely出现此日志基本可断定是proxy_read_timeout不足。3.3 第三阶根因深挖——模拟与注入测试Step 7注入可控延迟复现超时场景在 Java Controller 中临时加入人工延迟模拟慢模型GetMapping(/api/chat/stream) public SseEmitter stream(RequestParam String prompt) { SseEmitter emitter new SseEmitter(0L); // 模拟模型生成前 3 秒发 3 帧然后停顿 70 秒再发最后一帧 CompletableFuture.runAsync(() - { try { emitter.send(SseEmitter.event().name(message).data(Hello)); Thread.sleep(1000); emitter.send(SseEmitter.event().name(message).data(World)); Thread.sleep(1000); emitter.send(SseEmitter.event().name(message).data(!)); Thread.sleep(70000); // 关键制造长空闲 emitter.send(SseEmitter.event().name(close).data(done)); } catch (Exception e) { emitter.completeWithError(e); } }); return emitter; }然后用curl测试观察在哪一层断开。这是最有效的“压力探针”。Step 8抓包分析 TCP 层行为在 Java 服务器上用tcpdump抓取 SSE 流量tcpdump -i any -w sse.pcap port 8080 and host client-ip用 Wireshark 打开sse.pcap过滤tcp.stream eq 0查看Server 是否在空闲期发送了ACK包TCP keepaliveClient 是否在某个时刻发送了FIN包Server 是否回应RST最后一个data:帧发出后Server 是否还有PSH包若看到 Server 发送PSH后Client 长时间无ACK说明 Client 网络或浏览器已断开。Step 9前端调试验证 EventSource 行为在浏览器 Console 中运行const es new EventSource(/api/chat/stream?prompttest); es.onopen () console.log(Connected); es.onmessage e console.log(Received:, e.data); es.onerror e console.log(Error:, e, es.readyState); es.addEventListener(close, e console.log(Close event:, e));观察es.readyState变化0(connecting) →1(open) →0(reconnecting)。若频繁在1和0间跳变且onerror无具体信息大概率是proxy_read_timeout触发了 Nginx 的 504。4. 全链路加固方案从配置到代码的七项实操准则排查是为了修复。基于上述分析我总结出七项必须落地的加固准则每一条都来自血泪教训。4.1 准则一Java 层——SseEmitter 的“三不原则”不依赖默认超时永远new SseEmitter(0L)超时由业务逻辑或外部组件控制。不忽略 onCompletion/onError在这两个回调里必须记录traceId、emitterId、System.currentTimeMillis()和reason如timeout、ioexception、complete并发送到统一日志中心。不裸写 send()封装一个safeSend()方法捕获IllegalStateException并检查emitter.isCompleted()若已完成则直接 return避免日志刷屏。private void safeSend(SseEmitter emitter, SseEmitter.SseEventBuilder event) { if (emitter null || emitter.isCompleted()) return; try { emitter.send(event); } catch (IllegalStateException e) { log.warn([SSE] Emitter already completed, skip send. traceId:{}, MDC.get(traceId)); } catch (IOException e) { log.error([SSE] IO error on send. traceId:{}, MDC.get(traceId), e); emitter.completeWithError(e); } }4.2 准则二Tomcat 层——keepAlive 的精准计算keepAliveTimeout不是拍脑袋的数字。计算公式keepAliveTimeout max(模型 P95 响应时间 × 1.5, 30000) 5000其中5000是预留 buffer。P95 时间从 APM 工具如 SkyWalking获取或用 Prometheus 的histogram_quantile(0.95, rate(http_server_requests_seconds_bucket[1h]))查询。同时必须设置Connector port8080 protocolHTTP/1.1 connectionTimeout20000 keepAliveTimeout120000 !-- 示例P9580s → 120s -- maxKeepAliveRequests-1 socketBuffer65536 /4.3 准则三Nginx 层——SSE 专用配置模板以下是我在线上环境验证过的最小可行配置upstream java-app { server 127.0.0.1:8080; keepalive 32; # 与 upstream 的 keepalive 连接数 } server { listen 80; location /api/chat/stream { proxy_pass http://java-app; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; # SSE 关键配置 proxy_buffering off; # 必须关闭 proxy_read_timeout 120; # 必须 ≥ keepAliveTimeout proxy_send_timeout 120; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # 心跳保活可选但推荐 add_header Cache-Control no-cache; add_header X-Accel-Buffering no; } }4.4 准则四网络层——主动心跳与分帧策略在 Java 后端每 30 秒发送一次心跳帧// 在 SSE 推送循环中 long lastHeartbeat System.currentTimeMillis(); while (hasMoreTokens()) { String token nextToken(); safeSend(emitter, SseEmitter.event().name(message).data(token)); // 发送心跳 long now System.currentTimeMillis(); if (now - lastHeartbeat 30_000) { safeSend(emitter, SseEmitter.event().name(heartbeat).data({})); lastHeartbeat now; } }前端EventSource监听heartbeat事件重置自己的超时计时器。同时对长 token 做分帧public ListString splitToken(String token, int maxLength) { ListString chunks new ArrayList(); int start 0; while (start token.length()) { int end Math.min(start maxLength, token.length()); // 确保不在 UTF-8 多字节字符中间切断 while (end start (token.charAt(end - 1) 0xC0) 0x80) { end--; } chunks.add(token.substring(start, end)); start end; } return chunks; }4.5 准则五客户端层——健壮的 EventSource 封装class SseClient { constructor(url, options {}) { this.url url; this.options { ...options, retryDelay: 1000 }; this.emitter null; this.retryCount 0; this.lastEventId null; } connect() { this.emitter new EventSource(this.url (this.lastEventId ? last-event-id${this.lastEventId} : ), { withCredentials: true }); this.emitter.onopen () { this.retryCount 0; console.log(SSE connected); }; this.emitter.onmessage (e) { try { const data JSON.parse(e.data); this.lastEventId e.lastEventId || Date.now().toString(); // 处理业务数据 this.onMessage?.(data); } catch (err) { console.error(Parse SSE data error, err, e.data); } }; this.emitter.addEventListener(heartbeat, () { // 心跳重置超时 }); this.emitter.onerror (e) { console.error(SSE error, e, this.emitter.readyState); if (this.emitter.readyState EventSource.CLOSED) { this.reconnect(); } }; } reconnect() { if (this.emitter) this.emitter.close(); this.retryCount; const delay Math.min(this.options.retryDelay * Math.pow(2, this.retryCount), 30000); setTimeout(() this.connect(), delay); } }4.6 准则六监控告警——建立 SSE 健康水位线在 Prometheus 中定义以下告警规则- alert: SSE_Connection_Duration_P95_High expr: histogram_quantile(0.95, rate(sse_connection_duration_seconds_bucket[1h])) 120 for: 5m labels: severity: warning annotations: summary: SSE connection duration P95 120s - alert: SSE_Emitter_Complete_By_Timeout expr: rate(sse_emitter_complete_total{reasontimeout}[1h]) 0.1 for: 10m labels: severity: critical annotations: summary: More than 10% SSE connections timeout4.7 准则七发布流程——SSE 的灰度与回滚SSE 配置变更必须走灰度第一阶段仅对 1% 的流量开启新配置Nginx 的split_clients第二阶段监控新旧配置的sse_connection_duration和sse_emitter_error_total差异 5% 方可全量回滚预案若新配置导致504错误率上升 1%立即nginx -s reload切回旧配置。5. 常见问题速查表与独家避坑技巧最后整理一份高频问题速查表附上我踩过的坑和独门技巧。问题现象可能根因快速验证命令我的独家技巧前端 EventSource 频繁重连但无错误日志Nginxproxy_read_timeout 模型帧间隔curl -N http://nginx/sse观察是否在固定时间后断开在 Nginx 配置中加add_header X-SSE-Debug true;前端读取该 header 判断是否走代理Java 日志大量IllegalStateException: SseEmitter is already completed多线程并发调用send()或onComplete后仍有推送grep SseEmitter is already completed application.log | head -20在SseEmitter创建时用AtomicBoolean标记状态safeSend()中双重检查SSE 连接数暴涨Tomcat 线程池耗尽前端未正确close()EventSource或页面未销毁实例jstack pid | grep SseEmitter | wc -l在 Controller 的ExceptionHandler中对SseEmitter异常统一complete()并记录emitterId部分用户能用部分用户 504客户端网络存在 NAT 超时且未发心跳用不同运营商网络移动/联通/电信测试后端心跳帧event: heartbeat的data字段填入当前时间戳前端对比判断是否丢帧data:帧内容乱码或解析失败单帧过大触发 IP 分片或 UTF-8 截断tcpdump抓包看data:是否完整后端data字段用 Base64 编码前端atob()解码彻底规避编码问题Nginx error log 出现upstream sent too big header后端返回了过大的Set-Cookie或其他 headercurl -I http://localhost:8080/sse查看 header 大小在 Nginx 中加proxy_buffer_size 128k; proxy_buffers 4 256k;避坑技巧一用curl -v看清协议细节curl -v -N -H Accept: text/event-stream http://your-api会显示完整的 HTTP 交互包括HTTP/1.1 200 OK、Content-Type: text/event-stream、Connection: keep-alive以及最后的* transfer closed with outstanding read data remaining—— 这句就告诉你是服务端提前关闭了连接。避坑技巧二Tomcat 的maxThreads不是越大越好我曾将maxThreads从 200 调到 1000结果 GC 频率暴增。因为每个线程至少占用 1MB 栈空间1000 线程就是 1GB 内存。合理值 (预期并发 SSE 连接数) × 1.2。SSE 连接是 I/O 密集型不是 CPU 密集型线程数过多反而降低吞吐。避坑技巧三前端EventSource的withCredentials若你的 SSE 接口需要 Cookie 认证必须new EventSource(url, {withCredentials: true})否则浏览器不会发送 Cookie。但此时后端Access-Control-Allow-Origin不能是*必须指定具体域名否则 CORS 失败。避坑技巧四模型输出的data:必须是合法 JSON大模型输出的 token 可能包含换行符\n、双引号直接塞进data: {...}会破坏 SSE 格式。必须对data字段做 JSON.stringify()再替换掉\n和\rString safeData jsonStr.replace(\n, \\n).replace(\r, \\r); emitter.send(SseEmitter.event().name(message).data(safeData));避坑技巧五SSE 不是万能的该用 WebSocket 时别硬扛如果业务需要双向实时通信如用户中途取消、调整参数SSE 的单向性就是硬伤。这时果断用 WebSocket哪怕多写 200 行代码。我在一个实时协作编辑场景中强行用 SSE 模拟双向最后发现EventSource的重连机制与业务逻辑冲突不得不推倒重来。记住技术选型的第一原则是匹配业务本质而不是炫技。我在实际使用中发现最有效的排查方式永远是“从客户端发起逆向追踪”。先看浏览器 Network 里的失败请求再查 Nginx access log接着看 Tomcat 的 active connection最后翻 Java 日志。这个顺序比任何理论都管用。而且每一次成功的排查都应该沉淀为一条自动化检查脚本比如一个check-sse-health.sh它能自动执行curl、ss、jstat并输出健康报告。这样下次问题来时你只需要敲一行命令而不是手忙脚乱地翻文档。