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

速率限制参数

最后更新 查看 MarkdownAgent 设置

可用的速率限制规则参数在以下各节中说明。

有关当前规则配置限制的更多信息,请参阅 配置限制。

参数参考

当传入请求匹配时

  • 数据类型:String
  • API 中的字段名:expression(规则字段)

定义速率限制规则匹配请求的条件。

同时对缓存资产应用速率限制

  • 数据类型:Boolean
  • API 中的字段名:requests_to_origin(可选,含义与 Cloudflare 仪表板选项相反)

若禁用此参数(或当 API 字段 requests_to_origin 设为 true 时),在确定请求速率时仅会考虑发往源站的请求(即未缓存的请求)。

在某些情况下,由于配置限制,您无法禁用 Also apply rate limiting to cached assets(同时对缓存资源应用速率限制) 参数。详情请参阅 配置限制。

取决于您的 Cloudflare 套餐,此规则参数可能不可用。在这种情况下,Cloudflare 也会对缓存资源应用速率限制(该参数默认启用)。

使用相同特征

  • 数据类型:Array<String>
  • API 中的字段名:characteristics

定义 Cloudflare 如何为该规则跟踪请求速率的一组参数。

使用以下一个或多个特征:

仪表板值 API 值 说明
不适用(隐式包含) cf.colo.id(必填) 不要在表达式中用作字段
IP ip.src 与 IP with NAT support 不兼容
支持 NAT 的 IP cf.unique_visitor_id 与 IP 不兼容
Clearance UUID http.request.clearance.uuid Advanced Rate Limiting 可使用此特征。在计数表达式中使用 http.request.clearance.uuid ne "",以排除没有有效通行 Cookie 的请求。
Header value of(输入标头名称) http.request.headers["<header_name>"] API 用户请使用小写标头名称 与 字段缺失与空值
Cookie value of(输入 cookie 名称) http.request.cookies["<cookie_name>"] 推荐配置 与 字段缺失与空值
Query value of(输入参数名称) http.request.uri.args["<query_param_name>"] 字段缺失与空值
主机 http.host
路径 http.request.uri.path
AS 编号 ip.src.asnum
国家/地区 ip.src.country
JA3 指纹 cf.bot_management.ja3_hash
JA4 cf.bot_management.ja4
JSON string value of(输入键) lookup_json_string(http.request.body.raw, "<key>") 字段缺失与空值 与 lookup_json_string() 函数参考
JSON integer value of(输入键) lookup_json_integer(http.request.body.raw, "<key>") 字段缺失与空值 与 lookup_json_integer() 函数参考
Form input value of(输入字段名称) http.request.body.form["<input_field_name>"] 字段缺失与空值
JWT claim of(输入令牌配置 ID、声明名称) lookup_json_string( http.request.jwt.claims["<token_configuration_id>"][0], "<claim_name>") 在 JWT 中使用声明的要求、字段缺失与空值 与 JWT Validation 参考
正文 http.request.body.raw
Body size(选择运算符,输入大小) http.request.body.size
Custom(输入表达式) 输入自定义表达式。您可以使用 substring() 或 lower() 等函数,或输入更复杂的表达式。 函数

可用特征取决于你的 Cloudflare 计划。Clearance UUID 仅适用于 Advanced Rate Limiting。更多信息请参阅可用性。

递增计数器的条件

  • 数据类型:String
  • API 中的字段名:counting_expression(可选)

仅在 Cloudflare 仪表板中启用 Use custom counting expression(使用自定义计数表达式) 后可用。

定义用于确定请求速率的条件。默认情况下,计数表达式与规则匹配表达式(在 When incoming requests match(当传入请求匹配时) 中定义)相同。将此字段设为空字符串("")时也会应用该默认行为。

计数表达式可以包含 HTTP 响应字段。当计数表达式中存在响应字段时,计数将在响应发送后进行。

在某些情况下,由于配置限制,您无法在计数表达式中包含 HTTP 响应字段。详情请参阅 配置限制。

当速率超过限制时

  • API 中的字段名:不适用(根据所选选项需要不同的 API 字段)

速率限制计数方式可以是:

  • Request based(基于请求):根据给定周期内传入请求的数量进行速率限制。在基于复杂度的速率限制不可用时,这是唯一的计数方法。
  • Complexity based(基于复杂度):根据给定周期内处理请求的复杂度或成本进行速率限制。仅对拥有高级速率限制(Advanced Rate Limiting)的 Enterprise 客户可用。

当速率超过限制 > 请求数

  • 数据类型:Integer
  • API 中的字段名:requests_per_period

在指定时间周期内将触发规则的请求数。适用于基于请求的速率限制。

当速率超过限制 > 时间段

  • 数据类型:Integer
  • API 中的字段名:period

评估请求速率时要考虑的时间周期(以秒为单位)。可用值因您的 Cloudflare 套餐而异。

可用的 API 值为:10、60(一分钟)、120(两分钟)、300(五分钟)、600(10 分钟)或 3600(一小时)。

当速率超过限制 > 每个时间段的评分

  • 数据类型:Integer
  • API 中的字段名:score_per_period

每周期最大得分。超过此值时将执行规则动作。适用于基于复杂度的速率限制。

当速率超过限制 > 响应标头名称

  • 数据类型:String
  • API 中的字段名:score_response_header_name

响应中由源站服务器设置的 HTTP 标头名称,其中包含当前请求的得分。适用于基于复杂度的速率限制。

然后执行操作

  • 数据类型:String
  • API 中的字段名:action(规则字段)

当达到规则中指定的速率时要执行的动作。

在 API 中使用以下值之一:block、js_challenge(非交互式质询)、managed_challenge(受管质询)、challenge(交互式质询)或 log。

若选择 Block(拦截) 动作,可以使用以下参数定义自定义响应:

响应类型(适用于 Block 操作)

  • 数据类型:String
  • API 中的字段名:response > content_type(可选)

定义因速率限制而拦截请求时自定义响应的内容类型。仅在将规则动作设为 Block 时可用。

可用的 API 值:application/json、text/html、text/xml 或 text/plain。

响应代码(适用于 Block 操作)

  • 数据类型:Integer
  • API 中的字段名:response > status_code(可选)

定义因速率限制而拦截请求时返回给访问者的 HTTP 状态码。仅在将规则动作设为 Block 时可用。

您必须输入 400 到 499 之间的值。默认值为 429(Too many requests)。

响应正文(适用于 Block 操作)

  • 数据类型:String
  • API 中的字段名:response > content(可选)

定义因速率限制而拦截请求时返回的 HTTP 响应正文。仅在将规则动作设为 Block 时可用。

字段最大大小为 30 KB。

持续时间

  • 数据类型:Integer
  • API 中的字段名:mitigation_timeout

一旦达到速率,速率限制规则会在此字段定义的时间段内(以秒为单位)对后续请求应用规则动作。

在仪表板中,选择可用值之一,这些值因您的 Cloudflare 套餐而异。可用的 API 值为:0、10、60(一分钟)、120(两分钟)、300(五分钟)、600(10 分钟)、3600(一小时)或 86400(一天)。

Free、Pro 与 Business 套餐客户在使用质询动作时不能选择持续时长——其速率限制规则对这些动作始终执行请求节流(request throttling)。使用请求节流时,您无需定义持续时长。当访问者通过质询后,其对应的请求计数器会被置为零。当具有相同规则特征值的访问者再次发起足够多请求以触发速率限制规则时,他们将收到新的质询。

Enterprise 客户始终可以配置持续时长(或 mitigation timeout),即使使用质询动作之一也是如此。

使用以下行为

  • 数据类型:Integer
  • API 中的字段名:mitigation_timeout

定义所选动作的具体行为。

动作行为可以是以下之一:

  • 在所选持续时长内执行动作:在所选持续时长内对收到的所有请求应用已配置的动作。要通过 API 配置此行为,请将 mitigation_timeout 设为大于零的值。更多信息请参阅 持续时长。

    显示配置为在整个缓解周期内应用其动作的速率限制规则行为的图表
  • 对超过所配置最大速率的请求进行节流:对超过所配置限制的传入请求应用所选动作,并允许其他请求。要通过 API 配置此行为,请将 mitigation_timeout 设为 0(零)。

    显示配置为对超过所配置限制的请求进行节流的速率限制行为的图表

关于速率限制特征的说明

支持 NAT 的 IP 的使用场景

使用 IP with NAT support 可处理 NAT 下多个请求共享同一 IP 地址等情况。Cloudflare 使用多种保护隐私的技术识别唯一访问者,其中可能包括使用会话 cookie。详情请参阅 Cloudflare Cookies。

使用支持 NAT 的 IP 时的注意事项

IP with NAT support 依赖于基于 cookie 的访问者识别机制(_cfuvid cookie)。请注意以下几点:

  • 清除 cookie、使用无痕浏览或不接受 cookie 的访问者不会被单独识别。这些访问者的请求共享同一计数器桶,在高流量 NAT 环境中可能导致误报。
  • 对于关键安全的速率限制(例如保护登录或支付端点),请将 IP with NAT support 与 Path 或 Header value of 等其他特征结合使用,以降低识别缺口的影响。

不兼容的特征

您不能在同一条速率限制规则中同时使用 IP with NAT support 与 IP 作为特征。

不要在表达式中使用 cf.colo.id 字段

您不应将 cf.colo.id 特征(数据中心 ID)用作规则表达式中的字段。此外,cf.colo.id 的值可能在未事先通知的情况下发生变化。有关此速率限制特征的更多信息,请参阅 请求速率计算。

使用小写的标头名称(适用于 API 用户)

若在 API 请求中使用 Header value of 特征(配合 http.request.headers["<header_name>"]),您必须输入小写的标头名称,因为 Cloudflare 会在 Cloudflare 全球网络上对标头名称进行规范化。

缺少字段与空值

如果使用 Header value of、Cookie value of、Query value of、Clearance UUID、JSON string value of、lookup_json_integer(...) 或 Form input value of 特征,而请求中不存在相应值,则速率限制规则仍可能应用于该请求,具体取决于你的计数表达式。

若您未过滤掉此类请求,则对于字段不存在的请求会有一个专门的请求计数器,它与字段存在但值为空的请求计数器不同。

例如,要在特定速率限制规则的上下文中仅考虑存在特定 HTTP 标头的请求,请调整规则计数表达式,使其包含类似以下内容:

and len(http.request.headers["<header_name>"]) > 0

其中 <header_name> 与用作速率限制特征的标头名称相同。

对于 Clearance UUID,请使用 http.request.clearance.uuid ne ""。此表达式会将没有有效 cf_clearance Cookie 的请求排除在通行计数器之外。如果还需要限制这些请求的速率,请使用单独的规则。

若使用 Cookie value of 作为速率限制规则特征,请遵循以下建议:

  • 创建一条自定义规则,拦截该 cookie 存在多个值的请求。
  • 在执行任何高开销的服务器操作之前,先在源站验证 cookie 值。

在 JSON Web Token (JWT) 中使用声明的要求

要在 JSON Web Token (JWT) 中使用声明,您必须先在 API Shield 中设置令牌验证配置。

配置限制

  • 若在 When incoming requests match(当传入请求匹配时) 参数中定义的规则过滤表达式包含自定义列表,则必须启用 Also apply rate limiting to cached assets(同时对缓存资源应用速率限制) 参数。
  • 规则过滤表达式不能包含 HTTP 响应字段。
  • 在 Increment counter when(在以下情况递增计数器) 参数中定义的规则计数表达式,不能同时包含 HTTP 响应字段 与自定义列表。若使用自定义列表,必须启用 Also apply rate limiting to cached assets(同时对缓存资源应用速率限制) 参数。
  • 在账户级创建速率限制规则集时,规则集部署表达式(定义作用域)不能包含 HTTP 响应字段 或自定义列表。

这篇文档对您有帮助吗?