跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

速率限制

最后更新 查看 MarkdownAgent 设置

Rate Limiting API 允许您定义速率限制,并在 Worker 中围绕它们编写代码。

速率限制是近似值,并且会在每个 Cloudflare 位置分别应用。计数在后台更新期间,请求可能会超过你配置的限制。如需跨位置实施严格限制,请参阅严格限制。

您可以使用它来强制执行:

  • 在 Worker 启动后应用的速率限制,仅在代码的特定部分被到达时才生效
  • 针对不同类型客户或用户(例如:免费 vs. 付费)的不同速率限制
  • 针对特定资源或路径的限制(例如:每个 API 路由的限制)
  • 以上任意组合

Rate Limiting API 由为 rate limiting rules 提供服务的相同基础设施支持。

快速入门

首先,向 Worker 添加一个绑定(binding),使其能够访问 Rate Limiting API:

{
    "main": "src/index.js",
    "upload_source_maps": true,
    "ratelimits": [
        {
            "name": "MY_RATE_LIMITER",
            // An identifier you define, that is unique to your Cloudflare account.
            // Must be an integer.
            "namespace_id": "1001",
            // Limit: the request threshold within a given period in a single
            // Cloudflare location. Requests can exceed this threshold.
            // Period: the duration of the period, in seconds. Must be either 10 or 60
            "simple": {
                "limit": 100,
                "period": 60
            }
        }
    ]
}
main = "src/index.js"
upload_source_maps = true

[[ratelimits]]
name = "MY_RATE_LIMITER"
namespace_id = "1001"

  [ratelimits.simple]
  limit = 100
  period = 60

此绑定使 MY_RATE_LIMITER 绑定可用,它提供 limit() 方法:

export default {
  async fetch(request, env) {
    const { pathname } = new URL(request.url)

    const { success } = await env.MY_RATE_LIMITER.limit({ key: pathname }) // key can be any string of your choosing
    if (!success) {
      return new Response(`429 Failure – rate limit exceeded for ${pathname}`, { status: 429 })
    }

    return new Response(`Success!`)
  }
}
interface Env {
  MY_RATE_LIMITER: RateLimit;
}

export default {
  async fetch(request, env): Promise<Response> {
    const { pathname } = new URL(request.url)

    const { success } = await env.MY_RATE_LIMITER.limit({ key: pathname }) // key can be any string of your choosing
    if (!success) {
      return new Response(`429 Failure – rate limit exceeded for ${pathname}`, { status: 429 })
    }

    return new Response(`Success!`)
  }
} satisfies ExportedHandler<Env>;

limit() API 接受单个参数——一个包含 key 字段的配置对象。

  • 您提供的 key 可以是任何 string 值。
  • 一种常见模式是通过组合唯一标识发起请求的执行者(例如:用户 ID 或客户 ID)的字符串和标识特定资源的字符串(例如:特定 API 路由)来定义 key。

您可以为每个 Worker 定义和配置多个速率限制配置,这允许您根据需要针对传入请求和/或用户参数定义不同的限制,以保护您的应用程序或上游 API。

例如,以下是如何为免费和付费层级用户定义两个速率限制配置:

{
    "main": "src/index.js",
    "upload_source_maps": true,
    "ratelimits": [
        // Free user rate limiting
        {
            "name": "FREE_USER_RATE_LIMITER",
            "namespace_id": "1001",
            "simple": {
                "limit": 100,
                "period": 60
            }
        },
        // Paid user rate limiting
        {
            "name": "PAID_USER_RATE_LIMITER",
            "namespace_id": "1002",
            "simple": {
                "limit": 1000,
                "period": 60
            }
        }
    ]
}
main = "src/index.js"
upload_source_maps = true

[[ratelimits]]
name = "FREE_USER_RATE_LIMITER"
namespace_id = "1001"

  [ratelimits.simple]
  limit = 100
  period = 60

[[ratelimits]]
name = "PAID_USER_RATE_LIMITER"
namespace_id = "1002"

  [ratelimits.simple]
  limit = 1_000
  period = 60

配置

速率限制绑定具有以下设置:

设置 类型 描述
namespace_id string 包含正整数的字符串,在您的 Cloudflare 账户内唯一标识此速率限制命名空间(例如 "1001")。虽然值必须是有效整数,但指定为字符串。这是有意为之。
simple object 速率限制配置。simple 是唯一支持的类型。
simple.limit number 针对每个 Cloudflare 位置,在指定 period 内调用 limit() 的请求阈值。请求可能会超过此阈值;请参阅准确性。
simple.period number 速率限制窗口的持续时间,以秒为单位。必须是 10 或 60。

如果您不想在绑定之间共享速率限制状态,请为每个绑定使用唯一的 namespace_id。 :::

例如,要应用每分钟 1500 个请求的速率限制,您可以按如下方式定义速率限制配置:

{
    "ratelimits": [
        {
            "name": "MY_RATE_LIMITER",
            "namespace_id": "1001",
            // 1500 requests - calls to limit() increment this
            "simple": {
                "limit": 1500,
                "period": 60
            }
        }
    ]
}
[[ratelimits]]
name = "MY_RATE_LIMITER"
namespace_id = "1001"

  [ratelimits.simple]
  limit = 1_500
  period = 60

最佳实践

传递给 limit 函数、用于确定速率限制依据的 key,应代表您希望进行速率限制的用户或用户类别的唯一特征。

  • 好的选择包括 Authorization HTTP 标头中的 API 密钥、URL 路径或路由、应用程序使用的特定查询参数,和/或用户 ID 和租户 ID。这些都是稳定的标识符,在请求之间不太可能改变。
  • 不建议使用 IP 地址或位置(区域或国家),因为在许多有效情况下,这些可能被许多用户共享。您可能会发现自己在这些 key 上进行速率限制时,无意中限制了比预期更广泛的用户群体。
// Recommended: use a key that represents a specific user or class of user
const url = new URL(req.url);
const userId = url.searchParams.get("userId") || "";
const { success } = await env.MY_RATE_LIMITER.limit({ key: userId });

// Not recommended:  many users may share a single IP, especially on mobile networks
// or when using privacy-enabling proxies
const ipAddress = req.headers.get("cf-connecting-ip") || "";
const { success } = await env.MY_RATE_LIMITER.limit({ key: ipAddress });

局部性

您在 Worker 中定义和强制执行的速率限制是本地于 Worker 运行的 Cloudflare 位置 ↗的。

例如,如果你为特定路径配置了每 60 秒 100 个请求,悉尼处理的请求会计入悉尼的限制。在另一个 Cloudflare 位置处理的请求会计入单独的限制,即使它们使用相同的命名空间和键也是如此。这些计数不会合并成一个全球限制。

每个位置分别应用近似限制。如准确性所述,同一位置中的请求可能会超过配置的阈值。

性能

Workers 中的 Rate Limiting API 设计为快速。

每次检查都会使用本地缓存的计数。Cloudflare 会在同一位置的后台更新共享计数。

这意味着在代码中 await 对 limit() 方法的调用时:

const { success } = await env.MY_RATE_LIMITER.limit({ key: customerId });

Promise 会根据速率限制决定结果进行解析。它不会等待所有运行中的实例完成计数同步,因此你可以在无需等待同步的情况下检查限制。

准确性

Rate Limiting API 提供的是近似限制。计数最终会保持一致:每次检查使用本地计数,更新会在后台传递到其他运行中的实例。

更新到达前,请求可能会超过配置的限制。在单个或多个 Worker 中都可能发生此情况,即使同一 Cloudflare 位置的每个请求使用相同的命名空间和键也是如此。

下图展示了针对同一命名空间和键进行的两次本地检查。计数同步前,两次检查都可能允许请求:

flowchart TD
    accTitle: 本地速率限制检查与后台更新
    accDescr: 在一个 Cloudflare 位置内,发往一个或多个 Workers 的请求会检查同一命名空间和键的本地计数。在后台更新将两个本地计数与共享计数同步之前,它们都可能低于限制,从而允许请求超过配置的限制。
    subgraph location["一个 Cloudflare 位置"]
        direction TB
        requests["发往一个或<br/>多个 Workers 的请求"]
        requests --> a["检查本地计数 A<br/>低于限制:允许请求"]
        requests --> b["检查本地计数 B<br/>低于限制:允许请求"]
        a <-. "后台更新" .-> shared["此位置的<br/>共享计数"]
        b <-. "后台更新" .-> shared
    end

其他 Cloudflare 位置会维护单独的计数。本地计数并不代表每个 Worker 都有独立配额。

例如,如果你配置了每 10 秒 30 个请求,一波请求可能导致超过 30 次 limit() 调用返回 success: true。跨 Worker 共享命名空间或等待每次调用完成,都不会使合并后的限制变为严格限制。Worker 数量不会决定可超出限制的请求数。

严格限制

如果需要在所有位置实施单一严格限制,请使用 Durable Objects实现速率限制器。

如需针对每个凭据实施上游 API 配额,请将该凭据的请求路由到同一个 Durable Object。在允许请求前,一起检查并更新其计数器,并将计数器持久化到 Durable Object 存储中。每个凭据使用单独的对象。

根据上游 API 的速率限制规则设置限流器,并处理该 API 返回的 HTTP 429 响应。

监控

速率限制绑定目前在 Cloudflare 仪表板中不可见。要从 Worker 监控被速率限制的请求:

  • Workers Observability — 使用 Workers Logs 和 Traces 观察 Worker 在超出速率限制时返回的 HTTP 429 响应。
  • Workers Analytics Engine — 向 Worker 添加 Analytics Engine 绑定,并在 limit() 返回 { success: false } 时发出自定义数据点(例如 rate_limited 事件)。这允许您构建仪表板并随时间查询速率限制指标。

示例

这篇文档对您有帮助吗?