Nginx 反向代理中配置 proxy_headers_hash_max

proxy_headers_hash_max_size 并非 nginx 官方指令，标准版本中不存在；真实可用的是 proxy_headers_hash_bucket_size，用于调节 proxy_set_header 内部哈希桶大小，需设为2的幂且不小于最长请求头名长度。

nginx 反向代理中配置 proxy_headers_hash_max_size 参数

proxy_headers_hash_max_size 并不是 Nginx 官方配置指令，它不存在于标准 Nginx（开源版）的任何模块中，包括 ngx_http_proxy_module、ngx_http_upstream_module 或核心模块。

你在配置中看到或搜索到这个参数，通常源于以下几种情况：

Nginx 中与请求头/响应头处理相关的真实哈希配置项只有两个，且作用对象明确：

proxy_headers_hash_bucket_size
用于 proxy_set_header 指令中自定义请求头（如 proxy_set_header X-Real-IP $remote_addr;）时，内部哈希表桶（bucket）的初始大小。
默认值是 64，当自定义头名过长或数量较多导致哈希冲突时，需同步调大 proxy_headers_hash_max_size —— 但注意：这个 max_size 是另一个真实指令，名字是 proxy_headers_hash_max_size？不，错了。

✅ 正确指令是：
- proxy_headers_hash_bucket_size（必须是 2 的幂，如 64、128）
- proxy_headers_hash_max_size？❌ 官方文档中无此指令。
? 实际上，Nginx 文档只定义了：

proxy_headers_hash_bucket_size — Sets the bucket size for hash tables used by the proxy_set_header directive.
proxy_headers_hash_max_size — This directive does not exist.

⚠️ 常见误传来源：部分中文博客或旧版第三方编译包（如某些定制 Nginx + Lua 或商业版 patch）可能自行添加了类似命名的私有参数，但非标准、不可移植、不被上游支持。

aperture: the L402 aware reverse proxy
安装并运行 Aperture（Lightning Labs 的 L402 闪电反向代理），用于创建 L402 付费墙、配置付费 API 端点、为其他代理托管付费内容或测试 L402 认证流程。

下载

Nginx 确实有类似命名的全局哈希控制参数，但它们作用域完全不同：

map_hash_bucket_size / map_hash_max_size → 控制 map 指令构建的变量映射哈希表
server_names_hash_bucket_size / server_names_hash_max_size → 控制 server_name 匹配的哈希表
types_hash_bucket_size / types_hash_max_size → 控制 types 块中 MIME 类型匹配

这些和 proxy header 处理完全无关，强行修改不会影响 proxy_set_header 行为。

当你遇到如下报错时，才需干预哈希配置：

could not build server_names_hash, you should increase server_names_hash_bucket_size

或

could not build map hash table, you should increase map_hash_bucket_size

但如果你在 location 或 upstream 块里写了几十条 proxy_set_header，且出现类似错误（极罕见），说明头名太长或太多 → 实际应：

检查是否冗余设置（例如重复覆盖同一 header）
合并逻辑（如用 map 预计算再 proxy_set_header）
若真因哈希冲突失败（日志提示 hash max size exceeded），唯一有效方式是增大 proxy_headers_hash_bucket_size，并确保其值 ≥ 最长 header 名长度（字节）+ 1，且为 2 的幂：

http {
    proxy_headers_hash_bucket_size 128;
    # 注意：无需、也不能写 proxy_headers_hash_max_size
    ...
}

? 提示：该指令必须放在 http 块顶层，不能在 server 或 location 内；修改后需 nginx -t && nginx -s reload。

尽量减少 proxy_set_header 条数，优先用 $http_* 变量透传必要头
不要动态拼接长 header 名（如 proxy_set_header X-Custom-Trace-ID "$host-$request_id-$time_iso8601"; 易超长）
如需复杂头逻辑，改用 lua 模块（set_by_lua*）或 njs 脚本，在内存中构造后再 set，绕过哈希表限制

不复杂但容易忽略。