Nginx限流配置教程图解

文章导读
限流配置写错的地方,通常不在指令拼写,而在三个前置判断:限的是谁(IP、用户 ID 还是接口)、超限后返回什么状态码给客户端、以及请求到达 Nginx 时来源地址是否还真实。这三件事没定下来,直接抄 limit_req 往往会误伤正常用户,或者限了个寂寞。下面按“先定位、再配置、后验证、最后看边界”的顺序展开,示例可以直接替换成你自己的路径和阈值。
📋 目录
  1. 壹 先确认当前场景和目标
  2. 贰 按这个顺序处理
  3. 叁 改完后怎么验证
  4. 肆 容易忽略的边界
A A

限流配置写错的地方,通常不在指令拼写,而在三个前置判断:限的是谁(IP、用户 ID 还是接口)、超限后返回什么状态码给客户端、以及请求到达 Nginx 时来源地址是否还真实。这三件事没定下来,直接抄 limit_req 往往会误伤正常用户,或者限了个寂寞。下面按“先定位、再配置、后验证、最后看边界”的顺序展开,示例可以直接替换成你自己的路径和阈值。

先明确限流维度和超限响应,再动手写配置。限速用 limit_req(按时间窗控制请求速率),限并发用 limit_conn(按连接数控制),两者 zone 定义在 http 块、规则应用在 server 或 location 块。前置有 CDN 或反向代理时,必须先还原客户端地址,否则全站会按代理 IP 一起被限。改完用 nginx -t 校验后 reload,通过构造连续请求观察状态码分布和 error.log 中的限流日志来确认是否生效。

先确认当前场景和目标

限流不是所有接口都需要。先判断你的问题属于哪一类:如果是单接口被脚本高频刷、登录或短信验证码被打,属于“速率型”问题,用 limit_req;如果是下载、长连接、慢接口把 worker 连接数占满,属于“并发型”问题,用 limit_conn。同一个 location 也可以两者叠加。

动手前需要确认这几项信息:

  • 限流键:按客户端 IP($binary_remote_addr)、按用户标识(如登录后的 header 或 cookie 里的 ID)、还是按接口整体。按用户标识更精准,但要求业务层已经透传该标识。
  • 真实来源是否可用:如果 Nginx 前面还有负载均衡、CDN 或另一层反代,$binary_remote_addr 拿到的是上一跳地址,直接拿来限流没有意义,需要先配置 set_real_ip_from 和 real_ip_header。
  • 超限响应的口径:默认返回 503,很多客户端会把 503 当成服务故障并重试;如果前端和调用方能正确处理 429,建议显式设置 limit_req_status 429。这一条取决于调用方实现,不能只看服务端。
  • 预期阈值:结合正常业务峰值估算,宁可先宽后紧。阈值定得过紧,最先拦下的往往是真实用户。

按这个顺序处理

第一步,在 http 块定义共享内存 zone。zone 名可以自取,size 决定能容纳多少个 key 的状态,key 数量大时需要相应放大;如果 error.log 里出现与 zone 内存分配相关的报错,说明设小了。

http {
    # 按客户端 IP 限速,平均每秒 5 个请求
    limit_req_zone $binary_remote_addr zone=perip_req:10m rate=5r/s;

    # 按客户端 IP 限制并发连接数
    limit_conn_zone $binary_remote_addr zone=perip_conn:10m;

    # 全站默认的超限响应与日志级别
    limit_req_status 429;
    limit_conn_status 429;
    limit_req_log_level warn;
    limit_conn_log_level warn;
}

第二步,在具体 server 或 location 中引用 zone。注意 limit_req 与 limit_conn 不能写在 http 块,层级放错会直接导致 nginx -t 报错。

Nginx限流配置教程图解
server {
    listen 80;
    server_name example.com;

    location /api/login {
        # burst 为允许的突发量,nodelay 表示突发请求立即放行而不是排队
        limit_req zone=perip_req burst=10 nodelay;
        limit_conn perip_conn 20;
        proxy_pass http://backend_login;
    }

    location / {
        limit_req zone=perip_req burst=20;
        proxy_pass http://backend_web;
    }
}

第三步,如果前置有代理,先还原真实地址再限流。下面这段需要替换成你上一跳的实际网段,网段写错会导致来源地址校验失效或者被全部信任。

# 仅信任来自这些网段的 X-Forwarded-For
set_real_ip_from 10.0.0.0/8;
real_ip_header X-Forwarded-For;
real_ip_recursive on;

第四步,先在非核心 location 或较低风险接口上启用。较新的 Nginx 版本支持 limit_req_dry_run on; 和 limit_conn_dry_run on;,作用是只记录日志不实际拒绝,适合先观察命中情况;能否使用需要先用 nginx -V 确认当前编译版本支持该指令,不支持时就把 rate 和 burst 放大到不会真正触发的水平,同样能起到观察作用。

第五步,改完执行 nginx -t 校验语法,通过后再 nginx -s reload。如果校验失败,不要强行 reload,先按报错行号修正配置。

改完后怎么验证

验证要分两个方向:一是限流确实触发,二是正常流量没有被误伤。

Nginx限流配置教程图解

触发侧可以用连续请求观察状态码分布,注意把地址和接口替换成实际值:

for i in $(seq 1 30); do
  curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/api/login
done | sort | uniq -c

预期信号是输出里同时出现 200 和 429(若未改状态码则是 503),并且超限集中出现在超过 burst 之后。如果全部是 200,说明阈值远高于测试强度或规则没生效;如果第一条就是 429,多半是 zone 复用导致先把测试机自己限掉了,可以先单独换一个 IP 或换一个 location 复测。

日志侧看 error.log,开启 limit_req_log_level 后,被限流的请求通常会有 limiting requests, excess: ... 这类记录,可以据此判断触发频率是否符合预期。同时翻一下 access.log 里 429 的来源 IP 分布,如果集中在一两个 IP 上,属于预期;如果分散在大量不同 IP,说明阈值偏低或者真实地址还原有问题,需要先回退再排查。

误伤侧建议在业务相对平稳的时段观察一段时间,重点看原有正常接口的失败率有没有变化。仅凭一次压测结果不足以判断线上表现,尤其不要把压测数据当成容量结论。

容易忽略的边界

  • 多台 Nginx 之间不共享计数。zone 的共享内存只在单个 Nginx 实例内生效,集群部署时每台各自计数,实际放行量是按机器数放大的。要么调高单机阈值,要么接受这个偏差,不要默认它等同于全局限流。
  • NAT 与公共出口。大量用户共用一个出口 IP 时,按 IP 限流会把整批用户算作一个人,教育网、企业内网、移动网络下都可能出现。这类场景更适合按用户标识限流,或把阈值明显放宽。
  • burst 与 nodelay 的语义容易混淆。不写 nodelay 时,超出速率的请求会进入队列等待,客户端表现为变慢;写了 nodelay 时,burst 以内的请求立即放行,超过 burst 才拒绝。两种行为的用户感受完全不同,需要结合接口特性选择。
  • limit_conn 数的是连接不是请求。HTTP/2 或长连接场景下,一个连接上可以跑很多请求,用连接数评估请求量会明显低估。
  • 默认 503 会误导客户端和监控。如果不改 limit_req_status,限流和真实故障在监控里无法区分,建议至少和调用方确认状态码口径后再固定下来。
  • 回退方式要提前想好。出问题时最快的回退是在对应 location 注释掉 limit_req / limit_conn 行,执行 nginx -t 后 reload;如果来不及改配置,也可以临时把 rate 放大。回退属于止血操作,不代表性能提升,根因仍然需要回到阈值估算和维度选择上去处理。