网站流式响应总是攒成一整段?SSE、Nginx 缓冲与 CDN 转发排查

流式接口返回 200,内容却要等结束才一起出现,可以从应用直连、源站 Nginx 和公网入口逐层比较。本文说明 SSE 事件分隔、proxy_buffering、上游读取超时、压缩和 CDN 转发的检查方法,并补充 PHP-FPM、前端读流、鉴权、心跳及变更回滚注意事项,帮助定位数据在哪一层被积攒。
网站流式响应总是攒成一整段?SSE、Nginx 缓冲与 CDN 转发排查

聊天内容等到回答结束才一次出现,任务进度长时间不动后突然跳满,日志订阅连接正常却迟迟没有新行。这类现象常见于流式接口经过代理之后。HTTP 返回 200,只能证明请求收到了响应,不能证明每一段数据都及时送到了浏览器。

排查时需要分别观察应用直连、源站反向代理和公网入口。应用没有及时写出数据,修改 Nginx 无法补救;源站已经逐段输出,经过 CDN 后才成批出现,就应检查边缘转发规则。本文以 Linux、Nginx HTTP 反向代理和 SSE 为例。配置是说明用的局部示例,路径、端口和超时值需要按业务替换,未在读者生产环境执行。

先区分 SSE、普通下载与 WebSocket

SSE 使用持续打开的 HTTP 响应,常见响应类型是 text/event-stream。服务端发送符合事件流格式的文本,浏览器可以通过 EventSource 接收。一次事件以空行结束,例如:

data: {"progress": 10}

这里最后需要两个换行符。服务端只写出 data: 而没有事件结束的空行,浏览器可能已经收到字节,却还没有分发消息。[1]

WebSocket 使用另一套协议处理流程,本文不需要配置 Upgrade。普通 JSON 接口即使内部逐步计算,只要服务端最后才写响应,浏览器拿到的仍然是一次性结果。使用 fetch 读取流时,还要检查前端是否调用了等待完整响应的 response.text() 或 response.json();这两种读法不会提供逐段展示效果。

用同一个接口比较三条访问路径

以下命令在有权限的诊断机器上执行。example.com、/events/、127.0.0.1:3000 和示例 IP 都要替换。接口应为允许安全重复访问的测试订阅接口,不要对会触发付费任务或写入业务数据的地址反复测试。

# 应用直连:在源站执行,必要时补充应用所需的 Host 和鉴权
curl -N -i --max-time 30 http://127.0.0.1:3000/events/

# 指向源站的 HTTPS 入口,保留域名、Host 与 TLS SNI
curl -N -i --max-time 30 \
  --resolve example.com:443:203.0.113.10 \
  https://example.com/events/

# 正常 DNS 路径,可能经过 CDN 或负载均衡
curl -N -i --max-time 30 https://example.com/events/

-N 关闭 curl 自身的输出缓冲,不会改变服务器行为。长连接在 30 秒后被诊断命令主动结束,可能得到退出码 28,应与服务端提前中断区分。私有源站或只接收 CDN 回源的地址可能不允许直连,不要为测试而向公网放开源站。

观察内容是否随服务端生成逐次出现,同时记录每条路径的响应头。只比较总耗时或首字节时间不够:响应头很早返回,正文仍可能一直被积攒。

观察结果 接下来检查
应用直连就一次性返回 应用写出、框架缓冲、事件分隔、压缩中间件
直连逐段,源站 HTTPS 成批返回 Nginx 对应 location、代理缓冲和响应过滤
源站逐段,公网入口成批返回 CDN、负载均衡与额外网关的流式支持
curl 逐段,浏览器页面最后才更新 前端读流方式、SSE 格式、渲染节流

鉴权方式也应一致。命令行测试缺少 Cookie 或令牌时,可能拿到登录页或错误 JSON,不能据此比较流式行为。日志和截图需要遮盖令牌、Cookie 与私人消息。

检查应用有没有把事件真正写出

应用至少要满足三个条件:使用合适的响应类型、按 SSE 格式结束事件、及时把数据交给底层连接。部分框架存在响应缓冲,压缩中间件也可能改变小块数据的交付时机。具体的 flush 方法应以所用运行时和框架文档为准。

可以检查这些响应头:

Content-Type: text/event-stream
Cache-Control: no-cache
X-Accel-Buffering: no

Cache-Control: no-cache 表示复用缓存前需要验证,不等于完全禁止存储;私密事件还需按业务评估 no-store 和缓存绕过。X-Accel-Buffering: no 是应用通知 Nginx 关闭响应缓冲的一种方式;管理员如果配置了忽略该头,应用的设置不会生效。[2]

Nginx 默认会隐藏部分 X-Accel-* 响应头,因此外部 curl 看不到这个头,不能直接断定应用没发。应结合应用直连响应和 Nginx 配置判断。

SSE 可以用冒号开头的注释作为心跳:

: ping

心跳同样要及时写出。注释不会触发普通消息回调,但有助于保持连接活跃。[1] 心跳间隔应短于链路中最短的空闲超时,并留出调度延迟;固定每隔多少秒才正确,没有统一答案。

只为流式接口关闭 Nginx 代理缓冲

Nginx 的 proxy_buffering 默认开启。[2] 对小段连续输出,缓冲可能使客户端看到的数据呈批次出现。先定位实际处理请求的 location,再调整接口范围,避免把整个网站的静态资源和普通接口一并改掉。

下面示例放在正确的 server 中,适用于由 HTTP 应用提供的 /events/ 路径。上线前还要合并现有鉴权、访问控制与可信代理规则,不能用示例整体覆盖原配置。

location /events/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Connection "";

    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 120s;

    # 诊断压缩影响时仅针对该接口关闭
    gzip off;
    proxy_set_header Accept-Encoding "";
}

此处 proxy_pass 的地址末尾没有 URI 部分,会保留原始请求路径;不要随手加斜杠导致后端路由改变。若现有站点已经设定了 proxy_set_header,需注意它的层级继承规则:当前层新增此类指令后,要核对原先依赖的 Host、转发地址和协议等设置是否仍然存在。

proxy_read_timeout 120s 控制两次从上游读取之间的等待时间,不是整个 SSE 会话的总寿命。[2] 120 秒仅作示例;如果应用在这段时间内没有任何输出,连接仍可能结束。应用定期写出心跳,也无法绕过某些 CDN 的最大连接时长限制。

gzip off 和清空上游 Accept-Encoding 用于隔离压缩影响,不保证禁用所有第三方过滤模块。问题解决后可以单独验证压缩是否安全,避免长期保留不必要的性能取舍。对于 POST 请求体,proxy_request_buffering 控制的是另一方向的请求缓冲,与 SSE 响应缓冲不同,不必跟着一起关闭。

如果 Nginx 后面连接的是 PHP-FPM,需检查 fastcgi_buffering,proxy_buffering 对 FastCGI 链路无效。[3] 同时排查 PHP、框架和应用的输出缓冲;只修改一项代理参数,未必能够让整个链路逐段交付。

源站正常后,再检查 CDN 和浏览器

CDN 面板中能否开启缓存,与节点是否及时转发流式响应,是两项不同能力。对 SSE 路径配置缓存绕过后,还需要核对产品文档中的流式响应支持、响应体缓冲、压缩、空闲超时和最大连接时长。边缘函数、WAF、API 网关也可能参与处理,不能只看最外层 CDN。

不要用随机查询参数代替正式的缓存绕过规则。规则发布后,重新比较源站与公网入口的连续输出;对已有连接,配置变更未必立即生效,应建立新连接验证。

浏览器侧可以在 Network 面板观察事件流,配合控制台核对消息回调。跨域时还要检查 CORS;携带凭据的请求需要正确的允许来源和凭据响应头。原生 EventSource 不能像普通 fetch 一样任意设置自定义请求头,需要按接口鉴权设计选择 Cookie、合适的客户端库或 fetch 读流。不要把长期访问令牌直接放进 URL,以免进入日志和历史记录。

HTTP/1.x 下浏览器对同源 SSE 连接数量有限制,多标签页可能影响新连接;HTTP/2 的并发能力取决于协商。[1] 当只有第几个标签页无法开始接收时,连接数问题也值得检查。

修改前留备份,验证到消息到达这一层

备份实际修改的配置文件,注意保留权限。检查 Nginx 配置时可使用 nginx -t;多实例或自定义安装目录需要使用对应的二进制和配置参数。检查通过后,使用与部署方式匹配的 reload,例如 systemd 管理的实例可用 sudo systemctl reload nginx。容器和面板管理的实例应走各自的变更入口。

若测试未改善或出现路由、鉴权异常,恢复刚才备份的文件,再次检查语法并 reload。不要通过重启应用、放开源站防火墙、关闭证书校验来掩盖故障。

验收应覆盖实际业务的一段完整会话:首条事件是否及时到达,后续事件是否按生成节奏出现,空闲期间心跳是否继续传输,客户端断开后服务端是否释放资源,断线重连是否出现重复或丢失。需要恢复事件时,应用还要实现事件 ID 和重放策略,自动重连本身不保证消息可靠送达。

当三条路径都能逐段收到数据,浏览器也按事件更新,再逐项恢复为诊断临时关闭的功能。保留专用测试接口和路径级配置,下次升级代理或切换 CDN 时,就能复用同一套验收方法。

官方参考资料

资料核验日期:2026 年 11 月 17 日。

  1. MDN:Using server-sent events——事件格式、心跳、连接与浏览器行为。
  2. Nginx:HTTP proxy module——响应缓冲、X-Accel-Buffering、超时与请求头设置。
  3. Nginx:HTTP FastCGI module——PHP-FPM 链路的 FastCGI 缓冲控制。
Web服务与建站

网站 WebSocket 连接总在空闲后断开?心跳、代理超时与 CDN 限制排查

2026-11-6 12:01:29

知识库

过度配置:被忽视的“架构债务”,如何通过智能感知进行成本狩猎

2025-12-24 12:13:42