Node.js 流式调用为什么在 Nginx 后面变成“一次性输出”

模型明明逐字输出，经过 Nginx 后却等几十秒一次性返回，最常见原因是代理缓冲。普通网页适合 buffering，但 SSE/流式文本通常需要关闭缓冲并延长 read timeout。

一、为什么会出现这个问题

• 错误可能由 Nginx、Cloudflare、应用网关、第三方平台或真正的模型上游任意一层返回。
• 代理 read timeout、buffering、连接复用等默认值并不适合 AI 长请求。
• 流式 SSE 在中间层被缓存、提前关闭或事件格式被改写。
• 只看客户端最后一行错误，无法判断真正的故障来源。

二、推荐的排查顺序

1. 确认错误来自哪一层

保留响应头、request id、Cloudflare Ray ID、Nginx access/error log 和应用日志，同一时间点对齐分析。

2. AI 路由单独配置

SSE、长文本、Agent、视频任务不要直接套普通网站的 timeout 和 buffering。对 /v1/ 等接口单独设置更容易维护。

3. 只对暂时性错误重试

502/503 等可以有限重试；401、403、参数错误等确定性问题不应该盲目重试。

三、可以直接复制的排查示例

location /v1/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_cache off;
    gzip off;
    proxy_read_timeout 600s;
}

四、使用建议

不要全站关闭 buffering。只对真正需要流式的 API 路由单独配置。