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