如何通过 limit_req_zone 结合自定义头实现基于 API Key 的缓存多租户限速-Nginx-PHP中文网

可通过 limit_req_zone 结合 X-API-Key 实现多租户限速，限速仅作用于缓存未命中请求，需用 map 预处理 key、proxy_cache_key 包含 $api_key 保证缓存隔离，并辅以鉴权、日志与配额响应头增强健壮性。

如何通过 limit_req_zone 结合自定义头实现基于 api key 的缓存多租户限速

可以通过 limit_req_zone 指令结合自定义请求头（如 X-API-Key）实现按 API Key 区分的多租户限速，但需注意：Nginx 原生不支持直接对缓存命中请求做限速，所谓“缓存多租户限速”本质是「对携带有效 API Key 的原始请求进行限速，同时允许缓存响应绕过限速逻辑」——即限速发生在缓存未命中时的上游处理环节，而非缓存层本身。

1. 定义基于 API Key 的限速区域

使用 $http_x_api_key 变量提取客户端传入的 API Key，并作为限速键（key）。确保 Key 非空且去空格，避免空值或空白键导致所有请求被归入同一桶：

# 在 http 块中定义
limit_req_zone $api_key zone=api_per_key:10m rate=10r/s;
<p>map $http_x_api_key $api_key {
""          "";           # 空头跳过限速
default     $http_x_api_key;
}</p>

必须用 map 预处理：防止未带头或空值被哈希为相同 key（如全映射到空字符串），导致租户间互相干扰
zone 大小按租户量预估：10MB 约支持 16 万个独立 key（每个 key 占约 64 字节），超量会触发 LRU 踢出，可能误放行
rate 值按租户等级配置：可配合多个 zone（如 free_tier、pro_tier）+ 多个 map 分流

2. 在 location 中应用限速并区分缓存路径

限速应放在 proxy_pass 之前，且仅作用于非缓存命中的请求。利用 $upstream_cache_status 变量判断是否命中缓存：

location /api/ {
    # 先尝试匹配缓存（需已配置 proxy_cache）
    proxy_cache my_cache;
    proxy_cache_valid 200 5m;
<pre class="brush:php;toolbar:false;"># 仅对未命中缓存的请求执行限速
limit_req zone=api_per_key burst=20 nodelay if=$cache_bypass;

# 设置 cache_bypass：缓存未命中（MISS/MISSING/BYPASS）或无 key 时为 1
set $cache_bypass 0;
if ($upstream_cache_status = "MISS") { set $cache_bypass 1; }
if ($upstream_cache_status = "BYPASS") { set $cache_bypass 1; }
if ($api_key = "") { set $cache_bypass 0; } # 无 key 不限速，但可返回 400

proxy_pass http://backend;

}

if 是必要妥协：Nginx 不支持在 limit_req 中直接写条件表达式，只能靠变量间接控制
burst 和 nodelay 谨慎使用：burst=20 允许突发 20 请求，但若租户恶意刷爆 burst，仍会触发 503；nodelay 避免延迟排队，适合计费敏感场景
缓存状态判断要完整：除 MISS 外，BYPASS（如 no-cache 头）、EXPIRED（过期但后台更新中）也应触发限速

3. 配合缓存策略隔离租户内容

限速有效前提：不同 API Key 的响应必须缓存为不同实体，否则一个租户刷缓存会污染其他租户视图：

# 在 location 或 upstream 中添加
proxy_cache_key "$scheme$request_method$host$uri$is_args$args$api_key";
proxy_cache_bypass $http_x_api_key; # 有 key 才考虑缓存

cache_key 必须含 $api_key：否则所有租户共享同一缓存项，失去多租户意义
避免缓存 4xx/5xx 响应：加 proxy_cache_valid 400 401 403 429 0;，防止限速拒绝页被缓存
敏感字段不缓存：如含用户 PII 的响应，应在 upstream 响应头中设 Cache-Control: private, no-store

4. 补充安全与可观测性措施

单纯限速易被绕过，需配套机制增强健壮性：

校验 API Key 合法性：在限速前用 auth_request 模块调用鉴权服务，拒绝非法 key（此时限速 zone 不计入）
记录限速日志：用 log_format 记录 $api_key 和 $limit（触发限速时为 zone 名），便于审计
暴露租户配额信息：在响应头中返回 X-RateLimit-Limit、X-RateLimit-Remaining，需用 Lua 或 OpenResty 实现动态计算
降级处理：当限速触发时，返回 429 并附带 Retry-After，避免客户端盲目重试