proxy_headers_hash_bucket_size 是 nginx 反向代理中控制 header 名称哈希桶大小的参数，必须为2的整数次幂（如64、128），且不小于最长 header 名字节数加1，需置于 http 块顶层并与 proxy_headers_hash_max_size 配合使用。

proxy_headers_hash_bucket_size 是 Nginx 用于管理反向代理中请求头名称（如 X-Request-ID、X-Tenant-ID 等）哈希索引的关键参数。它不控制能收多少个 header，而是决定单个哈希桶能容纳的 header 名称最大字节数（含结尾 \0）。

这个值必须设对，否则 Nginx 启动或重载时会报错，比如：

could not build the proxy_headers_hash, you should increase proxy_headers_hash_bucket_size

这类错误和并发量无关，只和你在配置里写的 proxy_set_header 或 proxy_hide_header 的 header 名长度有关。

FastAPI Flask Proxy

FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。

下载

---

怎么设才合适

• 必须是 2 的整数次幂：只能填 32、64、128、256、512，不能填 100、192、200 等非对齐值。
• 值要 ≥ 最长 header 名字节数 + 1（+1 是为了容纳结尾空字符 \0）
  例如：
  X-Internal-Auth-Signature-JWS-V2 实测长度为 38 字节 → 至少设为 64；
  X-Tenant-Context-Trace-ID-Base64-Payload-SHA256 长 52 字节 → 至少设为 64；
  若最长达到 72 字节 → 必须设为 128。
• 不是越大越好：设成 512 却只存 30 字节的 header，纯属浪费内存，每个 worker 进程都会多分配这部分空间。

你可以用这条命令快速测长度：

echo -n "X-Your-Header-Name" | wc -c

---

必须写在哪儿

• 只能放在 http{} 块顶层，不能写在 server、location 或 upstream 里，否则会报语法错误。
• 必须和 proxy_headers_hash_max_size 一起配置，单独改一个无效。

示例正确写法：

http {
    proxy_headers_hash_bucket_size 128;
    proxy_headers_hash_max_size 2048;

    server {
        location / {
            proxy_pass http://backend;
            proxy_set_header X-Request-ID $request_id;
            proxy_set_header X-Tenant-ID $tenant_id;
            # ……其他 header
        }
    }
}

---

常见误区提醒

• 它和 client_header_buffer_size、large_client_header_buffers 无关——那两个管的是客户端发来的原始请求头能否被接收，而 proxy_headers_hash_bucket_size 管的是你配置里“声明了哪些 header 要转发”。
• 它也不影响 header 的值（value）长度，只管 key（名称）长度。
• 如果你没定义长 header 名，或者总共就几个 proxy_set_header，默认 64 完全够用，不用动。

不复杂但容易忽略。