必须关闭proxy_request_buffering以实现大文件流式上传，因其默认开启会导致串行等待、内存/磁盘耗尽、超时中断及与分片逻辑冲突；需在location块中配置proxy_request_buffering off，并协同调整client_max_body_size、超时参数等。
proxy_request_buffering 是 Nginx 1.12.0+ 引入的指令，控制是否将客户端上传的请求体（如 POST/PUT 的 body）在转发给上游前先完整缓存到内存或临时文件中。它不直接处理上传逻辑，而是决定 Nginx 如何“对待”请求体——缓冲 or 流式透传。配置不当会导致大文件上传失败、重复读取错误，或与后端流式处理冲突。
它解决什么问题？
默认 proxy_request_buffering on，Nginx 会把整个请求体收全再发给后端。好处是：
- 支持重试（
proxy_next_upstream对 502/504 等错误可自动切节点） - 允许在 proxy 层做 body 检查（如配合
if ($request_body ...)） - 避免后端因网络抖动接收不全
但代价是：
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 大文件上传时吃内存（默认最多用
client_max_body_size指定大小的内存） - 若后端是流式处理（如分块解析 XML、实时校验大 JSON），Nginx 缓存完才转发，破坏流式语义
- 与某些后端框架（如 Spring WebFlux、Node.js Stream）配合时出现
400 Bad Request或connection reset
关键配置项与建议
1. 开关控制：proxy_request_buffering on | off
-
设为
off的典型场景：- 大文件上传（>10MB），且后端支持 chunked 或分块接收
- 后端需实时处理请求体（如音视频转码、AI 推理输入流）
- 使用 WebSocket 升级或 SSE 接口（虽非上传，但 body 可能含初始化数据）
-
保持
on的场景：- 普通表单提交、小 JSON API
- 需要
proxy_next_upstream error timeout自动重试 - 后端无流式能力，必须收到完整 body 才开始处理
2. 必须配套调整的参数
仅改 proxy_request_buffering 不够，需同步检查：
client_max_body_size：
控制客户端能发多大的 body。若设0表示不限，但proxy_request_buffering on时仍受限于可用内存和client_body_buffer_size。
✅ 建议显式设值，如client_max_body_size 2G;client_body_buffer_size：
决定内存缓冲区大小。超过则写临时文件（由client_body_temp_path指定）。
✅ 大上传建议调高（如client_body_buffer_size 16k;），避免频繁落盘client_body_temp_path：
临时文件路径，需确保磁盘有足够空间和写权限。
✅ 生产环境务必指定独立路径，如client_body_temp_path /var/tmp/nginx/body 1 2;proxy_buffering：
注意别混淆——这是控制 Nginx 接收后端响应体 的行为，与 request 无关。上传场景下通常无需动它，除非后端返回大响应也需流式吐出。
3. location 级别隔离更安全
不要全局关 buffering，只对上传路径关闭：
location ^~ /api/upload/ {
proxy_pass http://backend;
proxy_request_buffering off; # 关键：允许流式上传
client_max_body_size 2G;
client_body_buffer_size 16k;
client_body_temp_path /var/tmp/nginx/body 1 2;
}
而普通 API 保持默认：
location ^~ /api/ {
proxy_pass http://backend;
# 不写 proxy_request_buffering → 继承默认 on
}
常见问题与排查
现象：上传大文件卡住、超时、返回 499 或 502
→ 检查proxy_request_buffering off是否生效（nginx -t+ reload）；确认client_max_body_size足够；查看error.log是否有* * * client intended to send too large body现象：后端收不到 body，或报
invalid chunk
→ 后端可能期望 chunked 编码，但 Nginxproxy_request_buffering on时会去掉 transfer-encoding，改用Content-Length。关 buffering 后自动透传原始编码。现象：开启
off后重试失效
→ 正确。proxy_request_buffering off时proxy_next_upstream对 body 相关错误（如 upstream timeout）不再重试，因为 body 已部分发送，无法重放。此时应靠后端自身幂等性或前端重试。
不复杂但容易忽略
