配置 proxy_buffering 关键在于按 location 精准分级控制：普通 api 保持 on，sse/llm/ws 等流式路径必须设 off，并同步配置 proxy_http_version 1.1、proxy_set_header connection '' 和 proxy_read_timeout。
配置 proxy_buffering 不是写在某个固定位置就行，关键在于**按请求路径精准控制开关位置和配套参数**。它默认开启（on），但不能全局关、也不能盲目开——必须结合业务响应类型，在 location 块里做差异化配置。
只在 location 块中开关，不碰 http/server 级
全局关闭（比如在 http 或 server 块里写 proxy_buffering off;）会破坏所有非流式请求的优化，导致 gzip 失效、临时文件不可用、后端连接无法及时释放。
- 对普通 API、HTML 页面等：保持默认
on，或显式写proxy_buffering on; - 对 SSE（如
/events）、LLM 流（如/chat）、WebSocket 升级（如/ws）、大文件下载（如/download）：在对应location中写proxy_buffering off; - 确保
proxy_pass在同一location内，且proxy_buffering指令放在proxy_pass之前
关闭时必须同步补全三项关键配置
proxy_buffering off 单独存在是无效的，数据会因协议降级或超时被截断。以下三者需成对出现：
-
proxy_http_version 1.1;：防止 Nginx 用 HTTP/1.0 转发，丢掉Connection: keep-alive和Upgrade头 -
proxy_set_header Connection '';：清空 Connection 头，避免代理层误改 WebSocket 升级流程 -
proxy_read_timeout 3600;：设为足够长（如 1 小时），防止空闲期被 Nginx 主动断连；SSE 场景可设为86400
开启时要调大 proxy_buffer_size 防 502
即使 proxy_buffering on，如果后端返回的响应头过大（比如含长 JWT、多个 Cookie、调试字段），仍会触发 upstream sent too big header 导致 502 错误。
-
proxy_buffer_size必须 ≥ 实际响应头大小（含 CRLF），建议从16k起步 - 该指令始终生效，无论
proxy_buffering开关状态如何 - 若启用 HTTP/2，还需同步检查并调大
http2_max_field_size（默认也是 4k）
配套缓冲参数按需调整，不堆数值
proxy_buffers 和 proxy_busy_buffers_size 只在 proxy_buffering on 时起作用，它们管的是响应体，不是响应头：
-
proxy_buffers 8 16k;→ 总内存缓冲约 128KB；若后端常返回 300KB+ 数据，可调为16 32k -
proxy_busy_buffers_size 32k;→ 建议设为单 buffer 大小的 2 倍，确保边读边发有空间 -
proxy_max_temp_file_size 1024m;→ 大文件或高并发场景下，避免因磁盘缓冲不足直接失败
