技术栈:JDK 17、Spring Boot 3.5.x、Spring MVC、Nginx;示例使用 Servlet 模式,不依赖 WebFlux。
本地通过 curl -N 能逐条收到消息,上线经过 Nginx 后却攒成一批才显示;浏览器切换页面后服务端还在推送;空闲一段时间连接又莫名断开。这三个现象经常同时出现,但分别涉及代理缓冲、连接存活检测、资源生命周期。本文从一个可复现的 SSE 通知接口出发,把这些问题逐层拆开。
一、先分清 SSE 的三个故障层次
1.1 SSE 并不是普通 JSON 响应
SSE 是服务端沿同一个 HTTP 响应持续发送 text/event-stream 数据,浏览器 EventSource 会按事件边界解析:
text
id: 42
event: notice
data: {"message":"订单状态变化"}
: heartbeat
每条事件以空行结束;以冒号开头的是注释,适合心跳。SSE 是单向推送,客户端要提交业务指令仍使用普通 HTTP 请求。它不保证消息可靠送达,也不是消息队列。
1.2 为什么 curl 正常,浏览器却延迟?
排查时分四层:应用是否实际调用 send、Servlet 是否写出响应、Nginx 是否缓存上游响应、浏览器是否按完整事件解析。不要看到"前端没有数据"就先改线程池。
| 现象 | 优先检查 | 常见原因 |
|---|---|---|
| 本机实时、经过代理延迟 | Nginx 响应缓冲 | proxy_buffering |
| 一段时间后断开 | 空闲超时链路 | 代理读超时、负载均衡器 |
| 关闭页面后连接仍占用 | 断开感知与回收 | 没有周期写入、回调遗漏 |
| 浏览器自动重连但丢事件 | 事件游标 | 没有持久化事件和重放 |
| 连接数上升导致资源紧张 | 并发连接容量 | 无上限连接、定时任务泄漏 |
二、实现一个能正确回收资源的 SSE 接口
2.1 最小 Maven 依赖
使用 Spring Initializr 创建 Spring Boot 3.5.x / Java 17 的 Maven 项目,选择 Spring Web。以下依赖放入生成的 pom.xml 的 dependencies:
xml
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
不要把下面示例的 ScheduledExecutorService 当成生产默认方案:它为演示单连接的生命周期而设计,生产中应由共享调度器管理心跳,避免每个连接创建线程。
2.2 可直接复制的控制器
java
package demo.sse;
import java.io.IOException;
import java.time.Instant;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicBoolean;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.mvc.method.annotation.SseEmitter;
@RestController
public class EventController {
private final ScheduledExecutorService scheduler =
Executors.newScheduledThreadPool(2);
@GetMapping(path = "/api/events", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter events() {
// 演示用 2 分钟超时,实际应结合代理与业务重连策略设置
SseEmitter emitter = new SseEmitter(120_000L);
AtomicBoolean closed = new AtomicBoolean(false);
final ScheduledFuture<?>[] heartbeat = new ScheduledFuture<?>[1];
Runnable cleanup = () -> {
if (closed.compareAndSet(false, true) && heartbeat[0] != null) {
heartbeat[0].cancel(false);
}
};
emitter.onCompletion(cleanup);
emitter.onTimeout(cleanup);
emitter.onError(error -> cleanup.run());
try {
emitter.send(SseEmitter.event()
.name("ready")
.id(Long.toString(System.currentTimeMillis()))
.data("connected"));
} catch (IOException ex) {
cleanup.run();
// Spring MVC 对 IOException 会进行异步错误分派,
// 不在此调用 completeWithError。
return emitter;
}
heartbeat[0] = scheduler.scheduleAtFixedRate(() -> {
if (closed.get()) {
return;
}
try {
emitter.send(SseEmitter.event()
.comment("heartbeat " + Instant.now()));
} catch (IOException ex) {
// 写入失败通常表示客户端已经离开。
// 由容器处理异步错误;这里只停止后续定时写入。
cleanup.run();
} catch (IllegalStateException ex) {
cleanup.run();
}
}, 15, 15, TimeUnit.SECONDS);
if (closed.get()) {
heartbeat[0].cancel(false);
}
return emitter;
}
}
这段代码是教学演示,不是可直接承载大量在线用户的连接管理器。 每个连接有一个定时任务,虽然共享线程池,但任务总数仍随连接数增加;实际应用还应限制连接数量、为不同用户隔离事件、在应用关闭时停止调度器。示例只发送 ready 与心跳,不会凭空生成业务通知。
2.3 断开时为什么不能只依赖 onCompletion?
Spring 官方明确指出 Servlet API 没有"客户端断开"的主动通知 。应用可能要等下一次写响应失败才知道连接已经断开。因此需要周期写入心跳;onCompletion、onTimeout、onError 负责统一清理,避免重复释放。
特别注意:send 抛出 IOException 时,Spring MVC 文档要求由容器完成错误通知流程,应用不应再次调用 complete 或 completeWithError。这与"业务线程主动终止正常连接"不是同一场景。
三、Nginx 代理配置:真正让事件实时到达
3.1 关闭 SSE 路由的响应缓冲
nginx
location /api/events {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Connection "";
proxy_buffering off;
proxy_read_timeout 75s;
}
proxy_buffering off 表示 Nginx 不再尽可能提前读取并缓存上游响应,而是同步转发。也可由应用在 SSE 响应中返回 X-Accel-Buffering: no,但是否生效取决于代理是否忽略该响应头;路由级配置更容易核查。
proxy_read_timeout 是两次上游读取操作之间的空闲超时,不是 SSE 连接的最大总寿命。示例每 15 秒心跳、75 秒读超时只是一个待验证的配置组合,实际还要检查 CDN、Ingress、负载均衡器与客户端网络。
3.2 不要把 request buffering 和 response buffering 混淆
proxy_request_buffering 控制客户端请求体 的缓冲;SSE 是服务端持续输出,核心是 proxy_buffering。盲目关闭全站缓存会影响普通接口性能,建议只对 SSE 路由处理。
四、浏览器重连与消息可靠性是两个问题
4.1 最小客户端
javascript
const source = new EventSource("/api/events");
source.addEventListener("ready", (event) => {
console.log("connected", event.data, event.lastEventId);
});
source.onerror = () => {
console.warn("SSE interrupted; browser may reconnect");
};
// 页面卸载或组件销毁时主动关闭
window.addEventListener("pagehide", () => source.close());
EventSource 默认有自动重连行为,但重连不等于 补发丢失的事件。若要实现断点续传,服务端需要给业务事件稳定递增或可排序的 ID,客户端重连时可能携带 Last-Event-ID,服务端还必须实现事件持久化、游标校验、权限检查与重放。
4.2 多实例部署需要回答的四个问题
- 连接落在 A 实例,业务事件在 B 实例产生,如何路由?可通过共享消息总线分发,但要评估重复、乱序与背压。
- 滚动发布时旧实例的连接如何退出?需要给客户端明确重连机会,不能把内存连接当作持久订阅。
- 重连携带旧游标时,历史事件已清理怎么办?定义最大重放窗口和快照恢复接口。
- 用户权限变化后旧连接怎么办?不能只在首次建立连接时鉴权而永久放行敏感事件。
五、按顺序复现并定位故障
5.1 不经过代理测试
bash
curl -N -i http://127.0.0.1:8080/api/events
预期首先看到 HTTP/1.1 200、Content-Type: text/event-stream 与 ready 事件,之后约每 15 秒收到注释心跳。具体头字段和输出格式取决于 Servlet 容器。
5.2 经过 Nginx 再测
bash
curl -N -i http://localhost/api/events
nginx -t
比较两条链路的每条事件到达时间 。如果直连实时、代理延迟,先检查生效的 location 与 proxy_buffering,再逐级排查外部网关。不要只看状态码 200。
5.3 主动断开测试
在终端运行 curl -N,收到两次心跳后按 Ctrl+C。应用通常要到下一次写入时才感知断开。观察连接注册表、定时任务数是否下降;不要把"控制器方法返回"当成连接结束。
5.4 建议记录的指标
| 指标 | 目的 |
|---|---|
| 当前 SSE 连接数 | 容量与泄漏预警 |
| 新建、正常结束、超时、错误计数 | 识别异常断开趋势 |
| 心跳发送失败数 | 代理或网络异常线索 |
| 消息生产到客户端接收延迟 | 区分生成慢与传输慢 |
| 重连率、重放数量 | 识别网络波动与数据缺口 |
不能只用服务端 send 成功证明浏览器已消费。端到端延迟需要客户端上报或业务确认机制。
六、生产环境常见误区
误区一:心跳越频繁越好。 心跳频率与连接数量相乘就是写入负载;应根据最短空闲超时、代理层级和容量确定。
误区二:一个连接一个线程。 Spring MVC SSE 异步响应并不意味着每条长连接始终独占 Servlet 工作线程,但阻塞写出和定时任务仍消耗资源,需压测确认容量。
误区三:EventSource 会自动保证消息不丢。 自动重连只恢复传输通道,业务可靠性依赖事件存储与重放。
误区四:所有 502/504 都是应用报错。 代理上游超时、连接重置、部署摘流同样可能造成错误,应关联 Nginx access/error log 与应用日志。
七、结论
SSE 故障要分清数据生成、应用写出、代理转发、客户端重连四层。最小可靠基线是:专用 SSE 路由关闭响应缓冲、设置可解释的心跳与超时、使用统一回收回调、对连接数设限;涉及业务通知可靠性时再补持久化事件 ID 与重放。示例未在本次创作中实际部署或压测,以上验证输出均为预期行为。
官方参考