proxy_buffer_size 直接决定 Nginx 能否完整接收后端响应头，设小触发502错误，设大则万级并发时额外消耗数百MB内存；它仅缓存状态行、响应头字段及CRLF换行符，与响应体无关，必须根据实测值（含\r\n）向上取整至最近2的幂次设置，且小于proxy_buffers单块大小、在proxy_buffering on时生效。
proxy_buffer_size 直接决定 Nginx 能否完整接收后端返回的响应头。设小了会触发 upstream sent too big header 错误，返回 502；设大了则每个活跃连接多占内存，万级并发时可能额外消耗数百 MB 内存。
它只管响应头，和响应体无关
这个参数专用于缓存状态行、所有响应头字段及末尾 CRLF 换行符（各占 1 字节），完全不参与响应体（body）的缓冲。JWT、长 Cookie、链路追踪 ID、重复 Set-Cookie 等都会推高响应头体积，但 body 大小（如文件下载、报表导出）对它毫无影响。
大小必须匹配实测值，不是越大越好
默认值通常为 4k 或 8k，在现代微服务或网关场景中极易不足。正确做法是：
aperture: the L402 aware reverse proxy
下载
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。
- 用
curl -v https://your-api/ 2>&1 | grep '^ 抓原始响应头，手动统计所有字符 + 每行末尾 \r\n 字节数 - 或临时开启 debug 日志：
error_log /var/log/nginx/error.log debug;，日志中会明确提示类似header: 13782 bytes - 按实测最大值向上取整到最近的 2 的幂次：5212 字节 → 设
proxy_buffer_size 8k；12345 字节 → 设16k；28900 字节 → 设32k - 避免设成 64k 或更大，除非确认存在多个超长单字段（如 OAuth2 多签名头）
必须和 proxy_buffers 协同配置
proxy_buffer_size 和 proxy_buffers 是两套独立机制：
- 前者只装 header，后者才管 body 缓冲区数量与大小
- proxy_buffer_size 必须小于单块 proxy_buffers 的大小（例如
proxy_buffers 8 128k，则 proxy_buffer_size 最大只能设 128k，但通常 16k 就够） - 若后端同时返回大 header 和大 body，需同步调大 proxy_buffers（如
proxy_buffers 8 128k）和 proxy_busy_buffers_size（建议设为单 buffer 大小的 1/2～1/4，且不低于单 buffer）
仅在 proxy_buffering on 时生效
该参数只在 proxy_buffering on;（默认开启）时起作用。若关闭（如 SSE、gRPC-Web、LLM 流式响应等场景），Nginx 直接透传 header，不校验长度，proxy_buffer_size 完全被忽略。
HTTP/2 下还需兼顾 http2_max_field_size
HTTP/2 使用 HPACK 压缩，http2_max_field_size（默认 4k）独立限制解码后的单个字段长度。即使 proxy_buffer_size 足够，该值过小仍可能导致单字段（如超长 Authorization 或 traceparent）截断，引发 502。需一并检查并按需调大。
