nginx响应头缓冲区不足导致502错误，日志提示“upstream sent too big header”，需先通过错误日志和curl -v验证响应头大小再调整proxy_buffer_size等配置。
这个问题核心是 Nginx 读取后端响应头时缓冲区不够用，不是后端挂了，也不是网络断了，而是“头太长、桶太小”。错误日志里那句 upstream sent too big header while reading response header from upstream 就是明确提示——Nginx 还没读完响应头就卡住了，直接返回 502。
先确认是不是 Header 真的大
别急着改配置，先看证据：
- 查 Nginx 错误日志（如 /var/log/nginx/error.log），搜索 upstream sent too big header 或 prematurely closed connection while reading response header
- 用 curl -v http://your-api/ 2>&1 | grep '^ 统计原始响应头总字节数（含状态行和所有 CRLF）
- 如果实测值接近或超过当前 proxy_buffer_size（默认通常是 4k 或 8k），基本可锁定
合理设置 proxy_buffer_size
这个参数只管响应头，不处理响应体，必须略大于你实测的最大响应头长度：
- 根据实测字节数向上取最接近的 2 的幂次：比如测出是 11KB，设为 16k；若达 28KB，可设为 32k
- 常见稳妥值是 16k 或 32k；OAuth2、SSO 等场景下可设为 64k
- 加在 location、server 或 http 块中，且必须写在 proxy_pass 之前
- 避免设成 1m 这类过大值——浪费内存，还可能被用于缓冲区耗尽类攻击
必须同步配置 proxy_buffers 和 proxy_busy_buffers_size
这三个参数是流水线协作关系，单调大 proxy_buffer_size 很难彻底解决问题：
- proxy_buffers 8 32k：分配 8 个缓冲区，每个 32KB，专存响应体（Body）
- proxy_busy_buffers_size 64k：划出最多 64KB 边收边发；该值必须 ≥ 单个 proxy_buffer 大小，且 ≤ (数量 − 1) × 单个大小（即 ≤ 7×32k=224k）
- 三者分工清晰：先用 proxy_buffer_size 存 Header，再用 proxy_buffers 接 Body，proxy_busy_buffers_size 控制转发节奏
别忘了排查后端是否异常冗余
调大缓冲区只是临时绕过，未必是根本解法：
- 检查后端是否重复写入 Set-Cookie、未清理的 X-Trace-ID、中间件注入的调试头
- 确认是否因循环重定向、认证逻辑缺陷导致 Header 指数级膨胀
- 若使用 HTTP/2，还要额外检查 http2_max_field_size（默认 4k），它独立限制 HPACK 解码后的单个 Header 字段长度
