502 Bad Gateway 错误中，一类常见原因是上游服务器响应头过长，超出 Nginx 默认 proxy_buffer_size 限制（通常4k/8k），导致 Nginx 无法完整接收 header 而中断连接并返回502；可通过错误日志中“upstream sent too big header”确认，并需同步调大 proxy_buffer_size、proxy_buffers 和 proxy_busy_buffers_size 参数协同生效。
502 Bad Gateway 报错中，有一类常见但容易被忽略的原因是：上游服务器返回的响应头（Header）过长，超出了 Nginx 作为反向代理时默认的缓冲区限制。这时即使后端服务（如 PHP-FPM、Tomcat 或 Node.js）本身运行正常，Nginx 也会因无法完整接收响应头而中断连接，最终返回 502。
为什么 proxy_buffer_size 会影响 Header 处理
Nginx 在反向代理模式下，会用 proxy_buffer_size 参数指定用于存储响应头（response header）的单块缓冲区大小。它只负责存 header，不存 body。默认值通常是 4k 或 8k——而现代应用（尤其带大量 Cookie、JWT Token、自定义追踪头、CORS 头或调试信息的系统）很容易让响应头突破这个上限。
一旦响应头长度超过 proxy_buffer_size，Nginx 就会直接报 502，日志中常伴随 "upstream sent too big header" 或 "upstream prematurely closed connection" 等提示。
如何确认是 Header 过长引发的 502
检查 Nginx 错误日志（通常在 /var/log/nginx/error.log），搜索关键词：
WebChat Voice Proxy
下载
⚠️ 已弃用 — 该技能已拆分为两个独立技能，以提升模块化程度：**webchat-https-proxy**（HTTPS/WSS 反向代理）和 **webchat-voi...**
- "upstream sent too big header"
- "upstream prematurely closed connection while reading response header"
- "client intended to send too large chunked body"（注意：这是请求体问题，非本例）
若匹配前两项，基本可锁定为响应头超限。还可临时用 curl 检查实际响应头大小：
curl -I https://your-domain.com | wc -c调整 proxy_buffer_size 的正确做法
仅调大 proxy_buffer_size 不够，需配合其他缓冲参数协同生效：
- 把 proxy_buffer_size 设为足够容纳最大响应头的值，例如 16k 或 32k
- 同步增大 proxy_buffers（如
4 16k），它控制响应体的缓冲区数量和大小，避免 header 和 body 缓冲争抢 - 确保 proxy_busy_buffers_size ≥ proxy_buffer_size × 2（例如设为
32k），否则繁忙时缓冲会被强制释放，导致截断
配置示例（放在 location 或 server 块中）：
proxy_buffers 4 32k;
proxy_busy_buffers_size 64k;
更稳妥的补充建议
单纯扩大缓冲不是万能解法，还需排查源头：
- 检查后端是否无意写入了超长 Cookie（如未压缩的 session 数据、重复 Set-Cookie）
- 确认是否启用了冗余调试头（如
X-Debug-Info、X-Powered-By、全量 Trace-ID） - 若使用 CDN 或 WAF（如 Cloudflare、阿里云 WAF），它们也可能添加长头，需一并评估
- 对静态资源或 API 接口，可考虑用
proxy_buffering off;关闭缓冲（慎用，仅适用于小响应且低并发场景）
