limit-req插件
更新时间 2026-04-21 15:48:56
最近更新时间: 2026-04-21 15:48:56
本文将详细介绍limit-req插件功能、配置和使用。
功能说明
limit-req 插件支持限制单个客户端对服务的请求速率。该插件内部使用的算法为漏桶算法。
配置字段
| 名称 | 类型 | 填写要求 | 默认值 | 有效值 | 描述 |
|---|---|---|---|---|---|
| rate | integer | 必填 | rate>0 | 指定的请求速率（以秒为单位），请求速率超过 rate 但没有超过（rate + burst）的请求会被延时处理。 | |
| burst | integer | 必填 | burst>0 | 请求速率超过（rate + burst）的请求会被直接拒绝。 | |
| key_type | string | 可选 | "var" | ["var", "var_combination"] | 要使用的用户指定 key 的类型。 |
| key | string | 必填 | ["remote_addr", "server_addr", "http_x_real_ip", "http_x_forwarded_for", "consumer_name"] | 用来做请求计数的依据，当前接受的 key 有：remote_addr（客户端 IP 地址），server_addr（服务端 IP 地址）, 请求头中的 X-Forwarded-For 或 X-Real-IP，consumer_name（Consumer 的 username）。 | |
| rejected_code | integer | 可选 | 503 | [200,599] | 当超过阈值的请求被拒绝时，返回的 HTTP 状态码。 |
| rejected_msg | string | 可选 | 非空 | 当超过阈值的请求被拒绝时，返回的响应体。 | |
| nodelay | boolean | 可选 | false | 当设置为 true 时，请求速率超过 rate 但没有超过（rate + burst）的请求不会加上延迟；当设置为 false，则会加上延迟。 | |
| allow_degradation | boolean | 可选 | false | 当设置为 true 时，如果限速插件功能临时不可用，将会自动允许请求继续。 |
配置示例
limit-req 使用示例
rate: 2
burst: 3
rejected_code: 503
key_type: "var"
key: "remote_addr"
rejected_msg: "Requests are too frequent, please try again later."根据该场景请求路由
curl http://example.com/test当请求速率在2(rate)次/秒内时，请求正常返回。
当请求速率超过2(rate)次/秒，但在5(rate+burst)次/秒内时，请求将被延迟处理，延迟时间根据漏桶算法。
当请求速率超过5(rate+burst)次/秒时，请求被限制，返回响应如下。
HTTP/1.1 503 Service Temporarily Unavailable
......
{"error_msg":"Requests are too frequent, please try again later"}配置模板
# [必填]指定的请求速率（以秒为单位），请求速率超过rate但没有超过（rate+burst）的请求会被延时处理, rate需大于0.
rate: 1
# [必填]请求速率超过（rate+burst）的请求会被直接拒绝, burst需大于等于0.
burst: 2
# [可选]请求超过阈值被拒绝时，返回的 HTTP 状态码。默认503，有效范围[200, 599].
#rejected_code: 503
# [可选]key 的类型
#key_type: "var"
# [必填]用来做请求计数的依据.当前接受的 key 有：remote_addr，server_addr, 请求头中的 X-Forwarded-For 或 X-Real-IP，consumer_name。
key: "remote_addr"
# [可选]当超过阈值的请求被拒绝时，返回的HTTP状态码
#rejected_msg: "Requests are too frequent, please try again later."
# [可选]当设置为 true 时，请求速率超过rate但没有超过（rate+burst）的请求不会加上延迟。默认 false
#nodelay: false
# [可选]当设置为 true 时，如果限速插件功能临时不可用，将会自动允许请求继续。默认 false
#allow_degradation: false
