应将 proxy_headers_hash_bucket_size 设为最长 header 名字节数加1后向上取最近的2的幂（如128），并同步设置 proxy_headers_hash_max_size ≥ bucket_size × 唯一头数量，且两指令须置于 http{} 块顶层。
要完整容纳超长自定义路径鉴权头部（如 X-Auth-Path-Scope-V2, X-Routing-Key-JWS-Signature, X-Tenant-Context-Path-Encoded 等含路径语义的长名 Header），关键不是盲目增大 proxy_headers_hash_bucket_size，而是让它精准匹配最长 Header 名的实际字节长度 + 1（空终止符）。这类头部常因嵌入 Base64、URI 编码路径段或多级签名字段而突破常规长度，极易触发哈希桶溢出警告甚至解析失败。
明确 proxy_headers_hash_bucket_size 的真实作用
它不控制能存多少个 Header，只决定单个哈希桶能容纳的 Header 名最大字节数（含结尾 \0）。
- 默认值
64：够用X-Forwarded-For（17 字节）、Content-Type（12 字节）等标准头； - 但
X-Auth-Path-Scope-V2-Encrypted-Path-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX实测可达 83 字节——此时64就会溢出，Nginx 启动报[emerg] could not build the proxy_headers_hash, you should increase proxy_headers_hash_bucket_size。
如何精准设置 bucket_size
先测量你最长的自定义 Header 名（不含值，仅 key）：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 在配置中临时加一条测试头：
proxy_set_header X-Test-Longest-Header-Name-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX "";
- 运行
nginx -t，若报错，说明当前bucket_size不足； - 用
echo -n "X-Test-Longest-Header-Name-..." | wc -c得到字节数，再加 1； - 结果向上取最近的 2 的幂（必须是 64/128/256/512）：
- ≤64 字节 →
64（默认，无需改） - 65–128 字节 →
128（最常用，兼顾安全与内存） - 129–256 字节 →
256（适用于含 JWT 或长编码路径的场景） - 超过 256 字节 → 检查是否设计过度复杂，优先精简命名
- ≤64 字节 →
必须同步调整 proxy_headers_hash_max_size
bucket_size 单独调大无效，必须配对设置：
-
proxy_headers_hash_max_size控制整个哈希表最多分配多少字节（不是桶数）； - 它需满足：
max_size ≥ bucket_size × 预估唯一 Header 名数量； - 示例（假设你有 60 个不同鉴权路径头，最长名 92 字节）：
-
proxy_headers_hash_bucket_size 128; -
proxy_headers_hash_max_size 8192;（128 × 64 = 8192，取 2 的幂）
-
放置位置与生效方式
- 两项指令必须放在
http{}块顶层，不可在server或location内； - 修改后执行：
nginx -t && nginx -s reload
- 启动无
[emerg]、日志无hash bucket size too small提示，即表示生效。
配套必须检查的细节
- 关闭隐式透传：
proxy_pass_request_headers off;，再显式proxy_set_header所需鉴权头，避免冗余键污染哈希表； - 若 Header 名含下划线（如
X_auth_path），需开启underscores_in_headers on;，否则被直接忽略； - 确保
large_client_header_buffers足够接收完整请求（如large_client_header_buffers 4 64k;），否则长 Header 还没进哈希流程就被截断； - 避免在多个
location中重复定义同一鉴权头，统一收敛到upstream或http块。
不复杂但容易忽略
