Spring Boot SSE 上线后不实时、频繁断线?Nginx 缓冲、心跳与连接回收实战

技术栈: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 多实例部署需要回答的四个问题

  1. 连接落在 A 实例,业务事件在 B 实例产生,如何路由?可通过共享消息总线分发,但要评估重复、乱序与背压。
  2. 滚动发布时旧实例的连接如何退出?需要给客户端明确重连机会,不能把内存连接当作持久订阅。
  3. 重连携带旧游标时,历史事件已清理怎么办?定义最大重放窗口和快照恢复接口。
  4. 用户权限变化后旧连接怎么办?不能只在首次建立连接时鉴权而永久放行敏感事件。

五、按顺序复现并定位故障

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 与重放。示例未在本次创作中实际部署或压测,以上验证输出均为预期行为。

官方参考

相关推荐
锋行天下35 分钟前
langgraph 全栈项目(三)
前端·人工智能·后端
金銀銅鐵1 小时前
用 Swing 重做操作数栈演示
java·jvm·后端
锋行天下1 小时前
langgraph 全栈项目(二)
前端·人工智能·后端
锋行天下2 小时前
langgraph全栈项目(一)
前端·人工智能·后端
学长毕设2 小时前
基于SpringBoot的游戏攻略社区交流系统-附源码
spring boot·后端·游戏
程序员cxuan2 小时前
不得了,Google 造反了,Opus 5.5 又被干了
人工智能·后端·程序员
Csvn3 小时前
Nginx 缓存体系:三层 key、七态 X-Cache-Status 与锁/stale 策略
后端·nginx
时间海8715 小时前
前端表单如何防止重复提交
后端
稀土蚯蚓5 小时前
OLAP 分析引擎:StarRocks、Doris、ES、ClickHouse,存算分离、列式存储 Parquet
后端