Nginx原生不支持返回剩余配额，需通过OpenResty+lua-resty-limit-traffic实现动态限流与响应头注入；纯Nginx仅能借助日志+外部服务间接估算，无法实时精确返回。
Nginx 本身不直接支持“客户端感知限流”和“返回剩余配额”的完整逻辑，但可以通过 limit_req 模块配合 Lua（OpenResty）或自定义变量 + 日志 + 外部服务协同实现。纯 Nginx 静态配置无法动态计算并返回剩余请求数，因为其限流模块（如 limit_req）只做令牌桶/漏桶的准入控制，不暴露桶状态。
使用 OpenResty + lua-resty-limit-traffic 实现带配额反馈的限流
这是最常用、可控性最强的方案。OpenResty 内置 Lua 环境，可精确控制请求处理流程，在限流前读取当前桶状态，并将剩余配额写入响应头。
- 安装 OpenResty（非标准 Nginx），启用
lua-resty-limit-traffic模块 - 在
location中用 Lua 创建限流对象（如基于 $binary_remote_addr 的令牌桶） - 调用
limit:incoming()获取结果：是否允许、当前剩余令牌数（rest）、桶容量（capacity）等 - 若拒绝，返回 429 并设置
X-RateLimit-Remaining: 0；若通过，设X-RateLimit-Remaining: rest - 可选：通过
X-RateLimit-Limit和X-RateLimit-Reset提供更完整配额信息
示例片段（nginx.conf）：
lua_shared_dict my_limit_store 10m;
<p>location /api/ {
access_by_lua_block {
local limit = require "resty.limit.count"
local lim, err = limit.new("my_limit_store", 100, 60) -- 100次/60秒
if not lim then
ngx.log(ngx.ERR, "failed to instantiate a limiter: ", err)
return ngx.exit(500)
end</p><pre class="brush:php;toolbar:false;"> local key = ngx.var.binary_remote_addr
local delay, err = lim:incoming(key, true)
if err then
if err == "rejected" then
ngx.header["X-RateLimit-Remaining"] = "0"
ngx.header["X-RateLimit-Limit"] = "100"
ngx.status = 429
ngx.say('{"error":"rate limited"}')
ngx.exit(429)
end
else
ngx.header["X-RateLimit-Remaining"] = tostring(lim:remaining(key))
ngx.header["X-RateLimit-Limit"] = "100"
end
}}
纯 Nginx 方案：用 log_format + stub_status + 外部监控间接估算
若无法引入 Lua，只能退而求其次：Nginx 原生命令无法返回实时剩余值，但可通过日志记录限流事件，再由外部服务（如 Prometheus + Grafana）聚合统计近期请求量，估算“窗口内已用/剩余”。这种方式不实时、不精确，且无法在响应头中动态写入。
- 开启
limit_req_log_level warn，在 error_log 中标记被限流请求 - 用
log_format记录 $request_time、$status、$binary_remote_addr - 结合
stub_status模块获取全局连接/请求计数（非按客户端） - 响应头中的配额字段需由上游应用（如后端 API）统一计算并注入，Nginx 仅作透传
关键细节与注意事项
无论哪种方式，以下几点直接影响客户端感知效果：
-
限流键要合理：用
$binary_remote_addr（IPv4/6 归一化）比$remote_addr更准确；需鉴权时可用$http_authorization或解析 JWT 后的用户 ID -
时间窗口对齐：Lua 方案中桶重置时间需明确（如每分钟整点重置），否则
X-RateLimit-Reset时间戳难生成；可用ngx.time() % 60辅助对齐 -
并发安全：
lua-resty-limit-traffic使用 shared_dict，天然支持多 worker 进程共享状态 -
响应头命名惯例：推荐遵循 RFC 6585 和业界习惯：
X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（Unix timestamp）
为什么不推荐用 map + limit_req 直接返回剩余值
limit_req 模块仅提供 limit_req_status（默认 503）和日志标记能力，它不提供任何变量暴露当前剩余请求数。Nginx 变量系统无法从限流模块读取运行时状态，因此无法用 add_header X-RateLimit-Remaining $limit_req_remaining 这类语法——该变量根本不存在。
强行绕过（如用计数器文件 + rewrite + internal location）会严重降低性能、破坏原子性，且无法应对高并发场景。
