中转站流式输出中途断开时SSE心跳超时参数在Nginx层的调整方案

文章导读
流式输出中途断开,通常不是后端应用主动断连,而是Nginx在等待上游数据时触发了超时。SSE连接的特点是一旦建立就长时间占用,消息之间可能只有心跳或注释行。Nginx默认的proxy_read_timeout通常是60秒,意味着上游如果60秒内没有发送任何字节,Nginx就会关闭连接。调整方向很明确:要么让上游心跳足够频繁,要么在Nginx层把这个超时参数增大或禁用。
📋 目录
  1. 壹 先判断断开发生在哪一段
  2. 贰 Nginx层调整的关键参数
  3. 叁 按现象分支排查清单
  4. 肆 验证调整是否生效
A A

流式输出中途断开,通常不是后端应用主动断连,而是Nginx在等待上游数据时触发了超时。SSE连接的特点是一旦建立就长时间占用,消息之间可能只有心跳或注释行。Nginx默认的proxy_read_timeout通常是60秒,意味着上游如果60秒内没有发送任何字节,Nginx就会关闭连接。调整方向很明确:要么让上游心跳足够频繁,要么在Nginx层把这个超时参数增大或禁用。

先判断断开发生在哪一段

不要直接改Nginx。先用curl直连上游服务,观察是否同样中途断开。如果直连稳定,说明问题在Nginx与上游之间;如果直连也断,则优先排查应用层心跳和连接保活。

  • curl -N `--max-time` 120 http://127.0.0.1:8080/events,观察输出是否持续。
  • 在Nginx服务器上执行同样命令,但改为访问上游内网地址。
  • 对比两端断开时间,若均在60秒左右,大概率是proxy_read_timeout。

Nginx层调整的关键参数

关闭缓冲,让数据即时转发

SSE依赖逐步推送,若Nginx开启proxy_buffering,上游数据会先被缓冲,前端收不到增量数据,可能触发前端超时误判。建议在location中设置proxy_buffering off;,同时可设置proxy_cache off;避免缓存影响。

中转站流式输出中途断开时SSE心跳超时参数在Nginx层的调整方案
location /events {
    proxy_pass http://backend_sse;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
}

proxy_http_version 1.1和空Connection头是为了避免上游复用HTTP/1.0默认的close行为。proxy_read_timeout是两次读取之间的空闲超时,不是总时长;SSE心跳之间如果没有数据,这个值必须大于心跳间隔。

心跳超时参数的取舍

如果上游心跳间隔是30秒,那么proxy_read_timeout设为60秒或更大即可。如果心跳本身不稳定,或者业务允许长静默,需要设成比业务最大静默时间更长的值。设0可以完全禁用读超时,但会让Nginx连接长时间保持,需要同时注意worker连接数和文件描述符上限。

中转站流式输出中途断开时SSE心跳超时参数在Nginx层的调整方案

按现象分支排查清单

  1. 现象:断开时间正好在60秒左右。检查proxy_read_timeout,将其调整到大于心跳间隔。
  2. 现象:前端收到部分数据,随后停住,Nginx日志出现“上游超时”。同样优先检查读超时,同时确认proxy_buffering是否关闭。
  3. 现象:断开时间不固定,且与应用日志中的异常堆栈对应。优先排查后端进程、连接池和心跳逻辑,不要只改Nginx。
  4. 现象:只有公网转发时断开,内网直连正常。检查Nginx到上游之间的防火墙、负载均衡设备是否有空闲连接老化设置。

验证调整是否生效

修改配置后先执行nginx -t,确认无误再reload。验证时不要只看连接能保持多少分钟,要看实际断开前的行为是否改变。

  • 用curl -N持续观察,记录从开始到第一个断开的时长。
  • 同时观察Nginx error.log,若不再有“upstream timed out”类记录,说明读超时调整生效。
  • 在测试环境把心跳间隔调大或暂停,确认连接能在预期时间内保持,再逐步调回正常配置。

需要明确:Nginx层调整只是解决“因读超时被切断”这一类问题。如果后端本身在心跳间隔内没有发送任何数据,且心跳机制依赖Nginx透传,那么仅调大超时并不能替代心跳缺失的问题。建议同步检查上游SSE实现,让心跳包独立于业务消息发送。