跳到主要内容

HTTP Header Max Size Adjustment

本指南提供了有关如何修改与Kong Gateway和Kubernetes上的NGINX Ingress环境中的HTTP请求相关的缓冲区和主体大小限制的详细说明。这些配置有助于防止由于大头部或有效负载导致的请求失败。

概述​

Kong使用嵌入式NGINX引擎来处理HTTP流量。默认情况下，NGINX对请求头和主体应用保守的大小限制。在生产环境中，特别是在处理：大请求头（例如，JWT令牌、Cookie、用户代理）、大请求主体（例如，文件上传）或高并发请求转换时，…

这些限制必须增加，以避免出现以下错误：

  • 400 错误请求 – 请求头或Cookie过大
  • 413 请求实体过大

本指南解释了如何通过三种不同方式调整这些限制：

  1. 通过Kong部署或Kong配置JSON
  2. 通过NGINX Ingress控制器ConfigMap
  3. 通过Ingress资源注释（每个服务）

关键配置参数（详细分解）​

nginx_http_client_header_buffer_size​

  • 描述：设置在读取客户端请求头时使用的单个缓冲区的大小。
  • 默认：1k
  • 何时修改：如果请求头如Authorization、Cookie、User-Agent变得过长（例如，SSO令牌或多Cookie头）。
  • 推荐：增加到4k或8k以确保稳定性。
  • 注意：设置过大可能会在高并发下增加内存使用。

nginx_http_large_client_header_buffers​

  • 描述：配置用于大请求头的缓冲区的数量和大小（例如，多接收者Cookie）。
  • 默认：4 8k（4个8k的缓冲区）
  • 修改时机：如果遇到 400 Bad Request – 请求头或 Cookie 太大。
  • 推荐：增加到 4 16k 或 8 16k。
  • 注意：仅在需要时扩展，以避免不必要的内存开销。

nginx_http_client_max_body_size​

  • 描述：定义 Kong 根据 Content-Length 接受的请求体的最大大小。
  • 默认：0（无限制）
  • 修改时机：为了防止超大请求体（例如，大文件上传）导致 413 错误。
  • 推荐：根据预期使用设置，例如 10m、50m。
  • 注意：超过此大小的请求将触发 Kong 的 413 响应。

nginx_admin_client_max_body_size​

  • 描述：设置 Admin API 接受的最大请求体大小。
  • 默认：10m
  • 修改时机：在向 Admin API 发送大配置负载时（例如，批量路由注册）。
  • 推荐：如有需要，设置为 20m 到 50m。
  • 注意：由于 Admin API 敏感，过多增加可能会引入安全风险。

nginx_http_client_body_buffer_size​

  • 描述：将请求体读取到内存中的缓冲区大小。如果请求体超过此大小，则写入磁盘。
  • 默认：8k
  • 修改时机：在使用请求转换、速率限制等请求体处理插件时，以避免写入磁盘。
  • 推荐：与 client_max_body_size 匹配，例如 50m。
  • 注意：较大的值会增加内存消耗（设置时考虑请求并发）。

nginx_admin_client_body_buffer_size​

  • 描述：与上述相同，但适用于 Admin API 请求体。
  • 默认：10m
  • 推荐：根据 Admin API 工作负载进行扩展。

配置方法​

方法 1：Kong 部署或 APIM 控制台配置​

仅适用于在 Kong Gateway Pod 内部运行的内部 NGINX。

选项 A – 修改 Kong 部署环境变量

- name: KONG_NGINX_HTTP_CLIENT_HEADER_BUFFER_SIZE
  value: "4k"
- name: KONG_NGINX_HTTP_LARGE_CLIENT_HEADER_BUFFERS
  value: "4 16k"
- name: KONG_NGINX_HTTP_CLIENT_MAX_BODY_SIZE
  value: "50m"
- name: KONG_NGINX_ADMIN_CLIENT_MAX_BODY_SIZE
  value: "20m"
- name: KONG_NGINX_HTTP_CLIENT_BODY_BUFFER_SIZE
  value: "50m"

选项 B – 通过 APIM 控制台中的 Kong 配置 JSON 进行修改

{
  "nginx_http_client_body_buffer_size": "8k",
  "nginx_proxy_buffer_size": "16k",
  "nginx_proxy_buffers": "10 16k",
  "nginx_proxy_busy_buffers_size": "64k"
}

更改后，重启 Kong Pods：

kubectl rollout restart deployment kong -n <namespace>

方法 2: NGINX Ingress Controller ConfigMap​

适用于所有通过 NGINX Ingress Controller 路由的流量。

示例：

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-configuration
  namespace: ingress-nginx
data:
  proxy-body-size: "50m"
  client-header-buffer-size: "4k"
  large-client-header-buffers: "4 16k"
  client-body-buffer-size: "50m"

在应用更改后重启 Ingress Controller：

kubectl rollout restart deployment ingress-nginx-controller -n ingress-nginx

方法 3: Ingress 资源注释​

仅适用于通过 Ingress 清单中的注释针对特定服务。

示例：

apiVersion: [networking.k8s.io/v1](http://networking.k8s.io/v1)
kind: Ingress
metadata:
  name: my-ingress
  namespace: your-namespace
  annotations:
    [nginx.ingress.kubernetes.io/proxy-body-size:](http://nginx.ingress.kubernetes.io/proxy-body-size:) "50m"

nginx.ingress.kubernetes.io/client-body-buffer-size: "50m" spec: ingressClassName: nginx rules:

  • host: your.example.com http: paths:
    • path: / pathType: Prefix backend: service: name: your-service port: number: 80
这是最细粒度的控制级别，并且优先级高于全局设置。

![](/img/apim/advanced-guide/20fb7135-d33b-8028-bfbf-c290d6cef6c0.png)

### 应用的优先顺序 \{#priority-order-of-application}


当多个设置共存时，系统按照以下优先顺序进行解析：

1. Ingress 资源注释（特定服务级别的覆盖）
1. NGINX Ingress ConfigMap（全局适用于所有 Ingress 资源）
1. Kong Gateway 部署 / Kong 配置（仅限于 Kong 代理内部）
## 摘要表 \{#summary-table}

| <b>Use Case</b> | <b>Relevant Parameters</b> |
| --- | --- |
| 大型头部 | nginx_http_client_header_buffer_size, nginx_http_large_client_header_buffers |
| 大型主体（客户端） | nginx_http_client_max_body_size, nginx_http_client_body_buffer_size |
| 大型主体（管理 API） | nginx_admin_client_max_body_size, nginx_admin_client_body_buffer_size |
| Ingress 范围的限制 | 使用 ConfigMap 设置 proxy-body-size, client-body-buffer-size 等。 |
| 每服务覆盖 | 使用 Ingress 注释（例如，proxy-body-size, client-body-buffer-size） |