SSE流式接口一次性返回:检查代理缓冲与心跳

适用范围:基于HTTP的Server-Sent Events;不是WebSocket,也不是一般文件下载。

应用日志显示一直在生成内容,网页却等到结束才全部出现,重点是找到“哪一层攒住了数据”。把所有超时都调大,不能解决缓冲;改WebSocket升级头也不能代替SSE设置。

先证明应用确实分批输出

在允许的服务器本机,用同一个无敏感数据的测试接口对照应用直连和反向代理入口:

curl -N -i --max-time 20 'http://127.0.0.1:8000/events'
curl -N -i --max-time 20 'https://example.com/events'

端口和路径按实际替换。-N 关闭curl自身输出缓冲。持续流被20秒测试上限结束时出现超时退出,不应单凭这个退出码判定服务故障。[1]

如果直连也要等很久才出现第一批内容,先检查应用是否及时发送并刷新输出,以及框架中间件是否缓存响应。如果只有代理入口延迟,继续看代理。

确认SSE响应格式

浏览器事件流使用 text/event-stream。每个事件要以空行结束;只写一行 data: 却不结束事件,浏览器可能继续等待,哪怕网络已经收到字节。测试消息可以是:

data: first

data: second

这里展示的是数据格式,不是终端命令。注释行可用于心跳,但心跳间隔要短于路径中最小的空闲超时;不要只盯Nginx一个节点。[2]

在对应location处理代理缓冲

对确认由 proxy_pass 代理的流式路径,评估以下局部设置,不要覆盖整个站点:

location /events {
    proxy_pass http://127.0.0.1:8000;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 75s;
}

75秒只是演示值,不是推荐的统一阈值。该读取超时衡量相邻读取之间的等待,不是限制整个请求只能运行75秒。应用也可用 X-Accel-Buffering: no 通知Nginx,但需核对是否被忽略;PHP-FPM等转发链应检查对应协议的缓冲配置,不能照搬proxy指令。[3]

对照验收而不是只看请求成功

配置检查通过后重载对应实例,比较首个事件出现时间和连续事件间隔。再测试空闲心跳、主动断线和客户端重连。关闭Nginx缓冲仍可能受到应用压缩、中间代理或前端读取方式影响;用相同请求逐层缩小范围。

持续连接会占用连接资源。只给需要的路径设置流式策略,并限制并发、记录错误;不能用无限超时掩盖已断开的客户端。

继续排查

Nginx反向代理本地Web应用;Nginx转发WebSocket:握手与掉线排查。

技术依据:[1] curl手册:no-buffer与max-time;[2] HTML标准:Server-sent events;[3] Nginx proxy模块:缓冲、缓存和读取超时。适用版本见本文说明。