一、一句 limit_req 写下去,为什么我的正常用户先被限了
那是去年一个做接口服务的站。上线前对方说担心被刷,让我加个限流。我大概是这么写的:在 http 块里丢一句 limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;,然后在 location 里加 limit_req zone=api burst=5 nodelay;,nginx -t 过了,systemctl reload nginx,收工。三天之后对方发来一张截图:他们自己的后台页面里,同一个用户连续点两下筛选按钮,第二下直接弹出一个错误提示,HTTP 状态码 503。
当时我的第一反应是"10r/s 还不够?"——这是绝大多数人第一次配限流时的误区:把 rate 当成了"每秒能处理多少个请求",以为数字写大点就没事。实际跑起来才发现,问题根本不在数字太小,而在于我从来没搞清楚三件事:rate 的单位到底是什么、burst 里排队的请求什么时候才被处理、以及在什么情况下这个模块返回的是 503 而不是 429。这三件事搞清楚了,配置才有意义。
这篇把 ngx_http_limit_req_module 从原理到落地讲一遍。内容偏运维实操,用到的版本是 nginx 1.24(Debian 12 发行版自带的 nginx-light 也带这个模块)。所有验证方法都是可以立刻在测试机上复现的。
二、先搞清楚它的算法:它是个漏桶,而且是"匀速漏"的漏桶
Nginx 的按请求速率限流用的是漏桶算法(leaky bucket)。理解这个算法有一个关键点,很多人会漏掉:桶里装的是"等待被处理的请求名额",不是"已经处理过的请求数量"。而"漏"的动作,也不是一次漏完,而是按 rate 换算出来的间隔匀速地漏。
官方文档里对 rate 的描述是 r/s 或 r/m,比如 rate=10r/s。但真正决定行为的不是这个数,而是它换算出来的毫秒级间隔。10r/s 换算下来就是每 100ms 放行一个请求。这个细节非常重要,因为后面所有"为什么我设了 10r/s 还是被拒"的问题,答案几乎都藏在这个间隔里。
具体的行为分四种情况,下面用 rate=1r/s(也就是每 1000ms 放行一个)配合不同的 burst 参数,在一个空桶状态下连发 6 个请求来演示。这个配置足够小,肉眼就能看出规律:
情况一:不设 burst,rate=1r/s
第 1 个请求进来,桶是空的,立刻放行;第 2 个请求在同一个毫秒进来,桶里没有第二个名额,直接拒绝。结果就是:1 个 200,5 个 503。这就是为什么很多人写完限流之后"正常用户第一下就挂"——因为现代浏览器的页面加载会并发发出十几个请求(HTML、CSS、JS、字体、图片),这些请求基本落在同一秒内,不设 burst 等于只放第一个进来。限流模块在这种配置下不是"防刷",是"禁止正常访问"。
情况二:burst=5,不加 nodelay
第 1 个请求立刻放行;接下来 5 个请求不拒绝,而是被放进队列里排队等待,按 1000ms 一个的节奏依次处理;第 7 个请求进来时队列满了,才被拒绝。所以这一组的结果是:前 6 个全部 200,第 7 个起 503。但要注意它们的耗时——第 2 个请求要等约 1000ms 才拿到响应,第 6 个请求要等约 5000ms。浏览器等 5 秒是什么体验?用户已经关掉页面了。所以 burst 不带 nodelay 的配置在实践中只适合极少数场景(比如允许缓慢排队的后台批处理接口),不适合普通页面和 API。
情况三:burst=5,加 nodelay(最常用的写法)
第 1 个请求立刻放行,后面 5 个请求不再排队等待,而是立刻被处理,但它们会把桶里的名额占掉。也就是说这一瞬间实际处理了 6 个请求,远超 rate 设定的 1r/s。之后桶会按 1000ms 一个的节奏慢慢把这些名额补回来,补满 5 个需要 5 秒。结果:前 6 个全部 200 且都是毫秒级响应,第 7 个 503。
这就是 nodelay 的真实含义——它不是"没有延迟",而是"允许突发,但突发额度有限"。它把漏桶变成了类似令牌桶的东西:平时攒着额度,来一波突发就一口气用掉,用完之后就硬拒。这正好符合页面加载的实际形态:一次打开页面并发 20 个请求,用户点下一页,中间隔了几秒,桶已经补满。所以对普通前台站点,burst + nodelay 是能兼顾体验和保护的基本组合。
情况四:delay=N(较新版本才有)
1.15.7 之后多了 delay=number 参数,语义比 nodelay 细致:超出 rate 的请求里,前 number 个立即处理,剩下的仍然排队但不拒绝。比如 burst=10 delay=5:前 5 个突发立刻放行,第 6 到第 10 个开始排队,第 11 个才拒。它适合"我能容忍少量延迟,但不想一刀切拒绝"的接口,比如后台导出、报表查询。注意 nodelay 和 delay 不能同时写,写了 nodelay 就是 delay 等于 burst。
三、zkey 写什么,决定了你是"按人限"还是"按 IP 限"
limit_req_zone 的第一个参数是 key,这一句决定了"谁和谁共用同一个桶"。常见写法和各自的坑:
$binary_remote_addr:按客户端 IP。这是最常用的。用二进制形式(v4 是 4 字节)而不是$remote_addr字符串,是为了省内存——官方说明里明确提到二进制形式在 IPv4 下约占 4 字节、IPv6 下 16 字节,而字符串形式在 32 位平台上长约 7 到 15 字节、64 位平台上 32 字节。共享内存区按 key 数量估算时,这个差别会被放大十几倍。$server_name:全站共用一个桶。除非你只有一个用户,否则没有意义——一个人刷就能把所有人一起限住。$http_x_forwarded_for:绝对不要直接用。这个头是客户端可以自己伪造的,攻击者每次随机带一个不同的值,就每次都是一个"新用户",限流形同虚设,而且还会把你的共享内存区撑爆。要用真实 IP,前提是前面有你自己可控的反向代理,并且通过set_real_ip_from+real_ip_header把$remote_addr修正成了真实客户端地址。- 登录后的用户:如果你的站点有会话,用
$cookie_session之类做 key 更准确,但要考虑空 cookie 的请求会全部落到同一个"空 key"桶里被一起限住。更稳妥的做法是map出一个组合 key,比如登录用户按用户 ID、未登录按 IP,避免大量未登录请求挤同一个桶。
共享内存区大小(zone 后面的 10m)决定了能同时记住多少个 key 的桶状态。粗略按每个 key 占用 64 到 128 字节估,10m 大概能装几万个。一旦装不下,新出现的 key 会被直接拒绝(这一点很容易被忽略:内存不够时不是"不限",而是"全拒")。所以刷子很猛的站,zone 给大一点,并且用 limit_req_status 和 limit_req_log_level 配合监控去发现。状态可以从 /nginx_status 或 stub_status 里看不到——这个模块没有暴露命中数,只能靠日志统计 503 或自定义状态码。
四、状态码:为什么它是 503,以及怎么改成 429
很多人在接入方那边看到"503 Service Unavailable",第一反应是"服务器挂了",运维被叫起来查半天。实际上 limit_req 默认返回的就是 503。这个默认值非常反直觉:503 的语义是"服务暂不可用,稍后重试",通常意味着后端故障,会让浏览器和 CDN 做出错误的判断(比如 CDN 会认为是源站故障,触发健康检查失败,甚至切到备用源)。
正确做法是显式改成 429:
limit_req_status 429;
429 是 Too Many Requests,语义准确,而且自带 Retry-After 的约定(Nginx 不会自动加,需要自己配 add_header Retry-After 1 always;)。另外强烈建议配一个自定义错误页,别让用户看到 Nginx 的默认页面。还有一个必须知道的坑:用 limit_req_status 改成 429 之后,error_page 429 的配置才会生效;如果你改了状态码却没配 error_page,用户看到的仍然是默认错误页。
日志方面,limit_req_log_level 默认是 error(注意:这个模块默认是 error,而 limit_conn 默认也是 error,但有些模块默认 warn),被拒的请求会在 error.log 里留一条 "limiting requests, excess: ... by zone" 的记录。这条日志是你的第一手证据,它里面就有当前桶里的 excess 值:
[error] 1234#0: *5678 limiting requests, excess: 5.234 by zone "api", client: 1.2.3.4, server: example.com, request: "GET /api/list HTTP/1.1"
看到 excess 这个数就能判断:如果是 0.0x,说明只超了一点点,burst 加一两个就够;如果是 20 多,说明这个 IP 真的是在刷,或者你的 rate 定得太低。
五、参数怎么定:从日志反推,不要拍脑袋
定 rate 和 burst 别猜,用真实流量算。第一步,从访问日志里统计单个 IP 在 1 秒内的最大请求数:
awk '{print $1, $4}' access.log | sort | uniq -c | sort -rn | head -20
这个粗略但有效——它按"IP + 秒级时间戳"聚合,能直接看出最猛的 IP 在一秒里发了多少。更精细一点,把日志的时间格式改成带毫秒的 $msec,或者直接用 Nginx 的 $request_time 结合 limit_req 的日志观察。第二步,看正常页面一次加载会产生多少个并发请求:浏览器 F12 的网络面板里,把"瀑布流"打开,数一下同一时刻在飞的请求。现在一个普通内容页,CSS + JS + 图片 + 字体加起来 30 个请求很常见,全部在一两秒内完成。
由此得出经验值:burst 至少要大于"单页面并发请求数"。如果页面有 30 个静态资源,burst 就别写 5,写 20 到 30;rate 可以写 5r/s 到 10r/s,因为正常用户的持续请求速率并没有那么高,真正需要挡住的是"同一 IP 每秒几百次"的刷子。另外,静态资源不需要限流,动态接口才需要——把 limit_req 写在 location ~ \.php$ 或 location /api/ 里,别写在 server 层影响所有静态文件。这是最省事也最不容易误伤的做法。
另外一个高频误伤场景:公司出口 IP、运营商 NAT、学校机房、CDN 回源。这些情况下几千个真实用户共用一个 IP,按 IP 限流会一起被限。如果日志里发现某个 IP 的请求量极大但 User-Agent 五花八门,那多半是出口 IP,别急着当刷子封。反过来,如果前面有 CDN,$binary_remote_addr 拿到的是 CDN 节点的 IP,所有用户挤在几十个桶里,这时候必须先配 real_ip 模块,否则限流完全错位。
六、limit_req 和 limit_conn 不是一回事,要一起用
经常有人问"我限了 req 为什么还是被拖死"。因为 limit_req 限的是单位时间的请求数量,而 limit_conn 限的是同时打开的连接数。两者挡的东西不一样:
- 刷子高频发短请求(比如每秒 500 个
GET /api/x):limit_req挡。 - 慢速攻击 / 大文件下载 / 长连接占着不放(比如开 200 个连接但每个都很慢):
limit_req完全无效,因为请求数不多,得靠limit_conn。
一个相对完整的组合大概长这样:
limit_req_zone $binary_remote_addr zone=req_api:10m rate=8r/s;
limit_conn_zone $binary_remote_addr zone=conn_api:10m;
limit_req_status 429;
limit_conn_status 429;
在 location 里:limit_req zone=req_api burst=20 nodelay; 和 limit_conn conn_api 10;
注意 limit_conn 的单位是"同时的连接数",10 的意思是这个 IP 同时最多 10 个连接。这个值别设太小,因为浏览器对同一域名会开 6 个左右的并发连接,加上 keepalive 复用,10 到 20 比较合适。
七、一个容易被忽略的坑:reload 不会清空桶
测试的时候我踩过一次:改完 rate 反复 reload、反复压测,结果怎么测都不对,数据看起来乱七八糟。原因是 nginx -s reload 不会重置共享内存区里的桶状态——共享内存区是随 master 进程一起创建和保留的,reload 只是重新加载配置、启新的 worker,老 worker 优雅退出,但 zone 里的数据还在。所以你刚被限过,桶是空的,reload 完立刻压测,第一批请求就全被拒,看起来像配置没生效。
要干净地测试,得 systemctl restart nginx(master 重启,共享内存重建),或者干脆在测试机上单独跑一个 instance。另外,多个 worker 进程共享同一个 zone,所以这个限流是进程间准确的,不是每个 worker 各限各的——这点和某些人以为的"worker 数乘以 rate"不一样。但如果你起了 multiple nginx instances 或者有多台机器在负载均衡后面,那每台机器各自独立计算,整体额度就是 rate × 机器数,这时候考虑用 limit_req_zone 的 sync 参数(1.17.5 之后支持,需要商业版之外的编译选项)或者在入口层统一限。
八、上线前的一张检查表
把上面这些收成一张表,配置完逐条对一遍:
- key 用的是
$binary_remote_addr,并且确认前面有反代时已经配了 real_ip 修正,没有直接用$http_x_forwarded_for。 limit_req_status 429和limit_conn_status 429都显式写了,不是默认的 503。- 配了
error_page 429,用户看到的是自己的提示页,不是 Nginx 默认页。 - burst 大于单页面并发请求数,或者干脆把
limit_req只写在动态接口的 location 里。 - 静态资源 location 没有限流,或单独放宽。
- zone 大小够用(按 key 数量估,宁可大一点,因为装不下时会全拒)。
limit_req_log_level保持 error 或 info,日志里能抓到 excess 数值用于调参。- 同时配了
limit_conn挡慢连接,两个模块互补。 - 压测时用
restart而不是reload,避免被残留的桶状态误导。 - 上线后用
curl -I连发几次确认状态码,并且从 error.log 里 grep 一次 "limiting requests" 确认规则真的命中了——配置没命中比配置写错更隐蔽。
九、最后一句
限流的目标从来不是"把请求拒掉",而是"在异常流量下保住正常用户的体验"。如果配置完之后你自己点的两下都弹错误,那这条规则一定是错的。所以最有价值的一步不是写配置,而是配完之后用自己的浏览器、手机、公司网络各点一遍,再找一个压测工具从一个 IP 猛打一轮,看日志和状态码是否符合预期。别人给你的限流建议,永远要落到你这台机器的真实流量上才有意义。