proxy_buffering off是明确的物理缓冲开关，关则边收边发实现流式透传，开则攒齐再发用于缓冲中转；必须按location精准配置（如/events、/llm/chat等），并同步关闭gzip、proxy_cache，调优超时及协议参数。
proxy_buffering off 是 Nginx 的行为开关，不是优化选项——关了就边收边发，开了就攒齐再发。它直接决定响应是流式透传还是缓冲中转，适用于对首字节延迟、时间戳精度或传输节奏有硬性要求的业务。
适合关闭 proxy_buffering 的典型业务路径
不建议全局关闭，应按 location 精准启用：
- /events 或 /stream 路径：SSE（text/event-stream）服务，每条 event 需实时抵达前端，缓冲会导致事件堆积、客户端感知卡顿
- /llm/chat 或 /api/generate：大模型 token 流式输出（如 chunked JSON），前端需立即渲染首个字符，缓冲会显著拉高 TTFB（Time to First Byte）
- /__webpack_hmr 或 /hot：前端开发热更新接口，依赖毫秒级 event 推送，缓冲易触发连接重连或事件丢失
- /api/upload/chunk：后端支持流式接收分片时，配合 proxy_request_buffering off 可实现端到端零缓冲上传+响应流
必须同步关闭的关键配套项
单独设 proxy_buffering off 极易导致 502、截断或连接中断：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- gzip off;：流式响应无法满足 gzip 所需的完整响应体，开启会直接失败
- proxy_cache off;：防止 Nginx 尝试缓存未结束的 chunked 响应，引发状态混乱
- proxy_http_version 1.1; + proxy_set_header Connection "";：确保长连接不被中间设备（如 CDN、WAF）降级或关闭
- proxy_read_timeout 300;（SSE 场景可设为 86400）：避免空闲期被超时中断，保持连接活跃
- tcp_nodelay on;：禁用 Nagle 算法，让每个 HTTP chunk 立即发出，不等待合并
proxy_buffering off 下仍有效的唯一缓冲参数
关闭后，proxy_buffers、proxy_busy_buffers_size 等全部失效，唯独 proxy_buffer_size 依然起作用——它只用于暂存响应头（通常 1k–4k 足够），不影响主体流式逻辑。建议显式设为 proxy_buffer_size 4k;，避免 header 写不全导致 502。
实际部署中的常见误区
很多问题并非配置遗漏，而是理解偏差：
- 误以为“关了就一定更快”：弱网下客户端接收慢，后端可能被阻塞，反而触发 proxy_read_timeout 中断
- 忽略内核 socket 缓冲区压力：高并发流式连接会使 net.core.rmem_max 成为瓶颈，必要时需调大
- 在 Ingress 中写成
nginx.ingress.kubernetes.io/proxy-buffering: false：K8s 注解值必须是字符串"off"，布尔值会被忽略 - 未区分请求与响应缓冲：proxy_request_buffering 和 proxy_buffering 必须协同关闭，否则上传快、响应卡，体验割裂
