限流配置写错的地方,通常不在指令拼写,而在三个前置判断:限的是谁(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 报错。

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,先按报错行号修正配置。
改完后怎么验证
验证要分两个方向:一是限流确实触发,二是正常流量没有被误伤。

触发侧可以用连续请求观察状态码分布,注意把地址和接口替换成实际值:
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 放大。回退属于止血操作,不代表性能提升,根因仍然需要回到阈值估算和维度选择上去处理。