Nginx 解决 upstream sent too big header 错误

catoop2026-02-21 9:11

当 Nginx 作为反向代理时，经常会遇到 upstream sent too big header while reading response header from upstream 这个错误（这里是我在 nginx 日志中看到的原始错误内容）。

问题根源

Nginx 默认为上游响应头分配的缓冲区较小（默认通常是 4k/8k），当响应头超过这个大小时就会报错。常见原因包括 JWT Token 过长、Set-Cookie 头部包含大量数据等（响应的 Header 太大）。

一般出现在登录成功或刷新Token时向客户端写入很多Cookie等等返回很多 Header 的场景。

解决方案：proxy_buffer_size

Nginx 使用该大小申请 read_buf，即大小指定了 upstream header 最大长度，如果响应头超过了这个长度，Nginx会报 upstream sent too big header 错误，然后 client 收到的是 502。

配置示例

bash 复制代码

server {
    listen 80;
    server_name example.com;
    
    location /api/ {
        proxy_buffer_size 16k;     # 关键配置：增大缓冲区
        proxy_pass http://backend;
    }
}

在 Kubernetes Nginx Ingress 中的配置

yaml 复制代码

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  annotations:
    nginx.ingress.kubernetes.io/proxy-buffer-size: "16k"
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        backend:
          service:
            name: app-service
            port:
              number: 80

最佳实践

按需配置：只在必要时调整缓冲区大小
渐进调整：从 8k → 16k → 32k 逐步尝试
精准定位：只为需要的 location 增加缓冲区。

通过合理配置 proxy_buffer_size，可以快速解决响应头过大的问题。

（END）