proxy_busy_buffers_size控制“已从后端读完、正在发给客户端但尚未收完”的缓冲区内存上限，仅在proxy_buffering on时生效，应设为proxy_buffers总量的1/4至1/2且不低于单块大小，设错会引发上游读取阻塞。

proxy_busy_buffers_size 不控制“缓冲区阻塞”，而是控制“已发送给客户端但尚未确认接收”的那部分缓冲区上限。它本质是一个背压闸门，防止因客户端慢速接收导致内存无限堆积；设得不合理才会引发上游读取阻塞——这不是它的目的，而是配置失当的副作用。

它真正管什么

这个参数只在 proxy_buffering on 时生效，作用范围非常明确：

• 限制 Nginx 缓冲区中处于“已从后端读完、正在发给客户端、但对方还没收完”状态的数据最大内存占用
• 不是总缓存容量（那是 proxy_buffers 的事）
• 不处理响应头（那是 proxy_buffer_size 的职责）
• 不决定是否落盘（那是 proxy_max_temp_file_size 和 proxy_temp_path 的逻辑）

为什么会出现“阻塞”现象

所谓“阻塞”，其实是 Nginx 主动暂停从 upstream 读取数据的结果，触发条件是 busy 区域被占满。常见原因有：

CPA Update - Secure CLI Proxy API Maintenance

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

下载

• 设得太小：比如 proxy_buffers 16 256k（总量 4MB），却仍用默认 8k，刚发几 KB 就停读，后端 write() 可能阻塞或超时
• 设得太大：如设为 3m 配合 4MB 总量，空闲 buffer 不足，多连接并发时抢不到缓冲空间，反而降低吞吐
• proxy_buffering 被意外关闭：location 块里写了 off，整个缓冲逻辑失效，busy 参数不起作用

怎么设才不引发阻塞

核心是比例 + 下限双约束，必须结合 proxy_buffers 设置：

• 取 proxy_buffers 总大小的 1/4 至 1/2
• 且 不低于单块 buffer 大小（例如单块是 128k，就不能设成 64k）
• 绝对不能超过 proxy_buffers 总大小，否则 nginx -t 直接报错

示例：

• proxy_buffers 8 128k → 总量 1MB → 推荐 proxy_busy_buffers_size 128k–256k
• proxy_buffers 16 256k → 总量 4MB → 推荐 1m–2m

哪些情况根本不用调它

该参数对以下场景完全无效，强行调整无意义：

• proxy_buffering off：Nginx 边收边转，不走内存缓冲队列
• 流式响应（SSE、日志 tail、gRPC streaming）：建议关缓冲，靠 proxy_buffer_size 控制 header 即可
• 大响应头（JWT、长 Cookie）：应调高 proxy_buffer_size，与 busy 值无关
• 超大文件下载（≥10MB）：直接关 buffering 更稳妥，避免内存压力