502 Bad Gateway 因 proxy_buffer_size 过小无法接收后端响应头，需通过 debug 日志或 curl 抓包获取真实 header 字节数，据此设置略大于实测值的 proxy_buffer_size（如12486字节设为16k），并同步调优 proxy_buffers、proxy_busy_buffers_size 和 proxy_buffering。
遇到 502 Bad Gateway 且日志中明确出现 upstream sent too big header while reading response header from upstream，基本可锁定是 Nginx 的 proxy_buffer_size 不足以接收后端返回的完整响应头。这不是后端挂了，而是代理层“读到一半就读不下去了”。调优的关键不是盲目放大参数，而是从日志出发，精准匹配实际头部体积。
从错误日志里提取真实 Header 大小
Nginx 错误日志本身常含关键线索：
- 开启 debug 级日志（临时）：
error_log /var/log/nginx/error.log debug;，重载配置后复现请求 - 在日志中搜索
header size is larger than buffer size或类似提示，部分版本会直接打印实测字节数，例如：header: 12486 bytes - 若无具体数字，结合
curl -v抓包验证：运行curl -v http://backend-url 2>&1 | grep '^<' | wc -c，结果包含所有响应头行及 CRLF 换行符，最接近真实占用
根据实测值设置合理的 proxy_buffer_size
该参数只管响应头，单位为字节（支持 k/m），必须略大于实测最大头长度：
FastAPI Flask Proxy
下载
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
- 实测 5212 字节 → 设为
proxy_buffer_size 8k;（留约 50% 余量，且取 2 的幂次） - 实测 12486 字节 → 设为
proxy_buffer_size 16k;（不建议直接跳到 32k，避免单连接内存浪费） - 若业务确定长期含超长头（如 SSO 回调带多段签名），再考虑
32k或64k，但需同步评估并发连接内存压力 - 该值不能超过
proxy_buffers中单个缓冲区大小，否则 Nginx 启动报错
仅调大 proxy_buffer_size 不够，必须协同三处配置
Header 和 Body 的缓冲是分阶段处理的，缺一不可：
-
proxy_buffers 8 16k;：为响应体分配缓冲区，建议单块大小 ≥proxy_buffer_size，数量按平均响应体大小预估 -
proxy_busy_buffers_size 32k;：设为单块大小的 2 倍左右（如上例中 16k × 2 = 32k），保证边收边发不卡死 -
proxy_buffering on;：确保缓冲机制生效；若临时禁用（off），proxy_buffer_size将完全失效
别跳过源头排查：后端是否在悄悄塞进冗余 Header
调参是兜底手段，高频出现大 Header 往往暴露后端问题：
- 检查是否重复设置
Set-Cookie（如登录后多次写入 token、session、csrf） - 确认调试头是否泄漏到生产环境（
X-Debug-Info、X-RateLimit-Detail、未清理的链路追踪 ID） - 排查是否存在循环重定向（302→302→…），导致
Cookie或Authorization层层叠加 - JWT 等长 Token 尽量不反射回响应头，改用短 ID + 后端查表方式
