proxy_buffer_size用于设置nginx反向代理时缓存后端响应头的缓冲区大小，仅处理headers（如set-cookie、jwt token等），不涉及响应体；默认4kb，超长header会触发“upstream sent too big header”错误，建议按8k→16k→32k逐步调优。
proxy_buffer_size 用于设置 Nginx 作为反向代理时，专门用来缓存后端服务器响应头（response headers）的缓冲区大小。它不处理响应体（body），只管 headers 部分——比如 Content-Type、Location、Set-Cookie、Authorization 等字段。如果后端返回的响应头过大（例如带很长的 JWT Token 或多段 Cookie），而该值太小，Nginx 会报错 upstream sent too big header while reading response header from upstream。
什么时候需要调大 proxy_buffer_size
常见于以下情况：
- 后端服务返回超长的
Set-Cookie（如多个 domain + Secure + HttpOnly + SameSite 的组合） - OAuth2/JWT 场景中，后端在响应头里写入了 base64 编码的长 token
- 使用了某些网关或认证中间件，自动注入大量自定义 header 字段
- 调试阶段开启详细 trace-id、debug-header 导致 header 总长度超过默认 4k
如何配置 proxy_buffer_size
该指令只能在 http、server 或 location 块中使用，且必须配合 proxy_buffering on（默认开启）才生效。典型配置如下：
location /api/ {
proxy_pass https://backend;
proxy_buffering on;
proxy_buffer_size 16k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;
}
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
说明：
-
proxy_buffer_size 16k：单独为响应头分配 16KB 缓冲区（建议从 8k → 16k → 32k 逐步尝试） -
proxy_buffers 8 16k：为响应体分配 8 个 16KB 缓冲区（共 128KB），不影响 header -
proxy_busy_buffers_size 32k：控制忙时可使用的缓冲区上限，一般设为proxy_buffer_size + proxy_buffer的单块大小之和
验证与排错方法
调整后需验证是否生效：
- 检查 Nginx 配置语法：
nginx -t - 重载配置：
nginx -s reload - 触发一次带长 header 的请求，观察 error.log 是否还有
too big header报错 - 用
curl -I或浏览器开发者工具确认响应头实际长度（注意：HTTP/2 下 header 压缩会影响传输体积，但 Nginx 解压后仍按原始文本长度判断）
注意事项
不要盲目设得过大：
- 每个连接都会独占一份
proxy_buffer_size缓存，高并发下内存开销明显 - 超过 64k 通常说明后端 header 设计不合理，应优先优化后端而非调参
- 若同时启用
proxy_cache，该参数对缓存对象的 header 存储也起作用
