跳到主要内容
版本：3.10.x

API7 网关 AI Agent Skill：limit-req 插件

概述​

limit-req 插件使用漏桶算法对请求进行限流。与采用固定窗口的 limit-count 不同，它通过可配置的延迟限制突发请求，从而实现平滑的流量整形，避免流量峰值压垮上游服务。

适用场景​

  • 平滑流量，保护上游服务免受突发流量影响。
  • 实施每秒 QPS 限制。
  • 延迟超额请求，而不是立即拒绝。
  • 与 limit-count 结合使用，同时实施每秒和每小时限制。

插件配置参考​

核心字段​

字段类型是否必填默认值描述
ratenumber是—持续的每秒请求数（QPS），必须大于 0
burstnumber是—超出 rate 的额外突发容量，必须大于等于 0
keystring是—用于统计请求的变量
key_typestring否"var"键类型："var" 或 "var_combination"
rejected_codeinteger否503拒绝请求时的 HTTP 状态码（200 至 599）
rejected_msgstring否—自定义拒绝消息正文
nodelayboolean否false设为 true 时，不延迟突发请求
allow_degradationboolean否false插件失败时是否允许请求通过
policystring否"local"存储策略："local"、"redis" 或 "redis-cluster"

Redis 字段（policy: "redis" 时）​

字段类型是否必填默认值
redis_hoststring是—
redis_portinteger否6379
redis_usernamestring否—
redis_passwordstring否—
redis_databaseinteger否0
redis_timeoutinteger否1000
redis_sslboolean否false

Redis 集群字段（policy: "redis-cluster" 时）​

字段类型是否必填默认值
redis_cluster_nodes字符串数组是—
redis_cluster_namestring是—
redis_passwordstring否—
redis_timeoutinteger否1000
redis_cluster_sslboolean否false

漏桶算法​

请求 → [   令牌桶（突发容量）   ] → 按每秒 `rate` 的速率流出 → 上游
                    ↓ 溢出（> rate + burst）
                    拒绝（503/429）
请求速率行为
≤ rate立即处理
> rate 且 ≤ rate + burstnodelay: false 时延迟处理以平滑流量；nodelay: true 时立即处理
> rate + burst使用 rejected_code 拒绝

nodelay 说明​

  • nodelay: false（默认值）：延迟突发请求以平滑流量。突发请求的延迟更高，但可保护上游服务。
  • nodelay: true：不延迟突发请求，立即处理。延迟更低，但上游服务会承受最高 rate + burst 的流量峰值。

分步操作：基础限流​

1. 严格 QPS 限制（无突发容量）​

a7 service create -g default -f - <<'EOF'
{
  "id": "rate-limit-backend",
  "name": "rate-limit-backend",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create -g default -f - <<'EOF'
{
  "id": "strict-qps",
  "uri": "/api/*",
  "service_id": "rate-limit-backend",
  "plugins": {
    "limit-req": {
      "rate": 10,
      "burst": 0,
      "key": "remote_addr",
      "rejected_code": 429,
      "nodelay": true
    }
  }
}
EOF

每个 IP 每秒允许 10 个请求，超出部分会被立即拒绝。

2. 使用突发容量平滑流量​

a7 service create -g default -f - <<'EOF'
{
  "id": "smooth-api-backend",
  "name": "smooth-api-backend",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create -g default -f - <<'EOF'
{
  "id": "smooth-api",
  "uri": "/api/*",
  "service_id": "smooth-api-backend",
  "plugins": {
    "limit-req": {
      "rate": 5,
      "burst": 10,
      "key": "remote_addr",
      "rejected_code": 429
    }
  }
}
EOF
  • 持续速率为 5 req/s。
  • 最多允许额外 10 个突发请求，并通过延迟平滑流量。
  • 超过 15/s 的请求返回 429。

常见模式​

多变量键​

{
  "plugins": {
    "limit-req": {
      "rate": 10,
      "burst": 5,
      "key_type": "var_combination",
      "key": "$remote_addr $http_x_api_version",
      "rejected_code": 429
    }
  }
}

按 IP 与 API 版本请求头的组合分别使用独立桶。

组合使用 limit-req 和 limit-count​

{
  "plugins": {
    "limit-req": {
      "rate": 10,
      "burst": 20,
      "key": "remote_addr",
      "rejected_code": 429
    },
    "limit-count": {
      "count": 1000,
      "time_window": 3600,
      "key": "remote_addr",
      "rejected_code": 429
    }
  }
}
  • limit-req：平滑每秒流量（10 QPS，带突发容量）。
  • limit-count：实施每小时配额（1000/小时）。

这样既能防止短期流量峰值，也能防止长期滥用。

使用 Redis 进行分布式限流​

{
  "plugins": {
    "limit-req": {
      "rate": 100,
      "burst": 50,
      "key": "remote_addr",
      "policy": "redis",
      "redis_host": "redis.example.com",
      "redis_port": 6379,
      "redis_password": "secret",
      "rejected_code": 429
    }
  }
}

limit-req 与 limit-count 的对比​

对比维度limit-reqlimit-count
算法漏桶固定窗口
单位每秒请求数每个时间窗口的请求数
突发流量处理延迟或允许直接拒绝
流量整形平滑窗口边界处可能突发
响应头无X-RateLimit-*
组支持否是
最适用场景QPS 保护、流量整形配额实施、API 套餐

故障排查​

现象原因解决方法
突发请求延迟较高nodelay: false 会延迟请求设置 nodelay: true 以降低延迟
所有突发请求都被拒绝burst: 0增加 burst 以允许一定的超额请求
没有返回限流响应头limit-req 不会添加响应头如需响应头，请使用 limit-count
限制未在 API7 企业版节点间共享policy: "local"切换为 "redis" 或 "redis-cluster"
键为空，所有请求共用一个桶变量不存在检查键变量名称

配置同步示例​

version: "1"
services:
  - id: smooth-api-backend
    name: smooth-api-backend
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1
routes:
  - id: smooth-api
    uri: /api/*
    service_id: smooth-api-backend
    plugins:
      limit-req:
        rate: 10
        burst: 20
        key: remote_addr
        rejected_code: 429

本页由 api7/a7 仓库中的 a7-plugin-limit-req/SKILL.md 生成。请在 AI Agent Skills 页面浏览所有 Skill。