如何通过 limit_req_zone 结合自定义头实现基于 API 账户的精细化多租户限流-Nginx-PHP中文网

可通过limit_req_zone配合map指令提取X-API-Key等自定义请求头，实现多租户独立限流；需规范变量值、设默认占位符、加前缀防冲突，并注意header大小写、内存占用及未授权请求处理。

如何通过 limit_req_zone 结合自定义头实现基于 api 账户的精细化多租户限流

可以通过 limit_req_zone 指令配合自定义请求头（如 X-API-Key 或 X-Tenant-ID），为每个 API 账户或租户独立设置请求速率限制，实现真正意义上的多租户精细化限流。

1. 定义基于自定义头的限流区域

Nginx 不支持直接对任意 header 值做哈希，但可通过 map 指令将请求头映射为变量，再用于 limit_req_zone。关键在于确保变量值稳定、非空、有区分度：

用 map 提取并规范化租户标识，例如从 $http_x_api_key 或 $http_x_tenant_id 中获取；
对空值、非法值设默认占位符（如 "anonymous"），避免 zone key 为空导致限流失效；
建议加前缀（如 "tenant_XXX"）防止与其他 key 冲突。

示例配置：

map $http_x_api_key $tenant_key {
    ""                  "anonymous";
    default             "tenant_$http_x_api_key";
}

limit_req_zone $tenant_key zone=api_per_tenant:10m rate=100r/s;

2. 在 location 中启用限流并配置行为

在对应 API 路由中引用该 zone，并控制突发请求和拒绝逻辑：

使用 limit_req 绑定 zone，设置 burst 缓冲突发流量，nodelay 或 delay= 控制排队策略；
搭配 limit_req_status 429 统一返回限流状态码；
可选：用 limit_req_log_level warn 记录被限流请求，便于审计。

示例：

location /api/ {
    limit_req zone=api_per_tenant burst=50 nodelay;
    limit_req_status 429;
    limit_req_log_level warn;

    proxy_pass http://backend;
}

3. 支持分级租户策略（按账户等级差异化限流）

单一 rate 不足以满足 SaaS 场景下免费版、专业版、企业版的差异需求。可通过额外 header（如 X-Plan）或后端注入变量，动态生成不同限流参数：

用 map 根据 $http_x_plan 映射不同 rate 值（如 "free: 10r/s", "pro: 100r/s"）；
结合 split_clients 或 Lua（OpenResty）实现更复杂策略，例如按 key 哈希分组限流；
注意：Nginx 原生不支持 per-key 动态 rate，需用 limit_req_zone + 多 zone + 条件匹配模拟，或引入外部决策服务（如 auth_request）。

4. 注意事项与常见陷阱

实际部署中容易忽略的关键点：

Header 大小写敏感：Nginx 中 $http_x_api_key 对应请求头 X-Api-Key（自动转为小写下划线），确保客户端发送的 header 名与 map 中一致；
Key 长度与内存占用：tenant_ 前缀 + 长 API Key 可能快速撑满 zone 内存（10m ≈ 16 万个 key），建议对 key 做哈希截断（需 Lua）或使用短租户 ID；
未授权请求的处理：若 API Key 无效或缺失，$tenant_key 会落入 "anonymous"，应单独限制该组速率（如 rate=5r/s），防暴力探测；
缓存与代理干扰：CDN 或反向代理可能剥离或修改自定义 header，需确认 header 端到端透传。