调优proxy_buffering的核心是根据响应特征动态权衡内存与效率：大文件下载、流式响应等低延迟场景必须关闭，常规html/api等需稳定吞吐场景应开启，并协同设置proxy_buffers、proxy_busy_buffers_size等参数控制内存占用与磁盘落盘。

调优 proxy_buffering 的核心，是让 Nginx 在内存可控的前提下，尽量减少磁盘落盘，同时避免因缓冲策略不当导致后端写入阻塞或客户端卡顿。它不是“开或关”的二选一，而是根据响应特征（大小、流式与否、是否需改写）动态权衡内存占用与传输效率。

明确场景：什么情况下必须关、什么情况下必须开

关闭 proxy_buffering off 适用于真正需要低延迟、边收边传的场景：

• 大文件下载（≥10MB），尤其是 CDN 回源或直传终端时
• 流式响应（SSE、gRPC-Web、Chunked API），下游消费速度不可控
• 后端已做分块且依赖实时性（如日志推送、监控指标流）

开启 proxy_buffering on 更适合需要稳定吞吐与响应控制的场景：

• 常规 HTML/API 响应，需统一添加 Header、压缩或缓存校验
• CDN 回源要求完整响应体（如计算 ETag、补全 Content-Length）
• 后端网络不稳定，需解耦上下游速率，防止源站连接长时间挂起

开启时：协同设置 proxy_buffers 和 proxy_busy_buffers_size

仅设 on 不够，必须匹配缓冲区容量与“忙”状态上限：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

• proxy_buffers 16 256k; → 总缓冲内存 4MB，适合百 MB 级响应
• proxy_busy_buffers_size 2m; → 允许最多 2MB 处于“已接收但未发完”状态，取总量的 1/2，既防阻塞又留出空闲缓冲复用
• proxy_buffer_size 16k; → 单独保障响应头空间，避免因 Cookie 或重定向头过大触发 502

若设得过小（如 proxy_buffers 4 4k），小响应尚可，但大响应会频繁刷盘；若设得过大（如 proxy_buffers 32 4m），单 worker 可能吃掉数百 MB 内存，增加 OOM 风险。

控制磁盘落盘：禁用或约束临时文件行为

当响应超出内存缓冲，Nginx 默认写临时文件——这是大文件卡顿的常见源头：

• 完全禁用：proxy_max_temp_file_size 0;，强制超限即报错（502/503），便于暴露瓶颈而非掩盖问题
• 允许落盘但优化 I/O：proxy_temp_file_write_size 256k; + proxy_temp_path /ssd/nginx/temp;，减少小块写入，挂载 SSD 路径提升吞吐
• 注意：proxy_buffering off 时，上述临时文件参数不生效，可忽略

配套关键超时与协议设置

缓冲区调优必须配合连接生命周期管理，否则仍会卡在等待阶段：

• proxy_read_timeout 300;：延长从后端读响应的等待时间，尤其跨公网回源或大文件传输
• proxy_http_version 1.1; + proxy_set_header Connection '';：启用长连接，减少 TCP 握手开销
• client_body_timeout 3600; 和 proxy_send_timeout 3600;：避免大文件转发中途被误判超时断连