> For the complete documentation index, see [llms.txt](https://www.axisnow.io/zh/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.axisnow.io/zh/docs/edge/policies/rate-limiting/configuration.md). # 配置项速率控制规则每个配置项的含义与取值范围一条速率控制规则由名称、条件和三张卡片组成：**计数 Key**、**限速阈值**、**限速动作**。下面按控制台从上到下的顺序逐项说明，参数怎么搭配见[防护场景](/zh/docs/edge/policies/rate-limiting/use-cases.md)。 ## 名称规则的显示名，创建时随机生成，建议改成能看出意图的名字，例如「公开接口-削峰兜底」「登录接口-只数失败」。规则列表、洞察页的筛选、IP 封禁记录和日志检索里都用这个名字。 ## 条件条件决定哪些请求进入这条规则的计数。两种模式： * **任意**：所有请求都匹配。用于全站兜底规则。 * **自定义**：用字段、匹配方式、值三元组搭建表达式。同一组内的条件为 And，组与组之间为 Or。可用字段按来源分八类，常用的有：

分类	字段
站点与资源	请求 Host、域、标签、边缘
客户端	客户端 IP 地址、客户端 IP ASN、客户端 IP 区域、浏览器类型、浏览器版本
请求	HTTP 请求方法、HTTP 请求协议、HTTP 版本、请求头 referer、User Agent、请求时间、目的端口号
URI	请求完整 URL、请求 URI、请求 URI 路径、文件后缀、请求 URI 参数、匹配指定 URI 参数
请求头与 Cookie	请求头、请求 Cookie、匹配指定 Cookie 值、X-Forwarded-For
请求体	请求 MIME 类型、请求体大小、POST 表单
TLS	TLS 加密
Bot 与指纹	TLS 客户端 JA4 指纹、TLS 客户端 JA4 指纹已验证、挑战通过、AxisNow 挑战通过、第三方挑战通过、已验证的 Bot

每个字段的含义见[条件匹配字段](/zh/docs/edge/policies/rules/condition-fields.md)，匹配方式（在以下各项之中、包含字符、与正则表达式匹配、开头为、在对象中……）见[操作符和函数](/zh/docs/edge/policies/rules/operators-and-functions.md)。「请求头」「匹配指定 Cookie 值」「匹配指定 URI 参数」「POST 表单」这类字段要先填名称再选匹配方式；多值用标签输入，一个路径一个标签。 {% hint style="info" %} 「Bot 与指纹」分类里的「已验证的 Bot」和「挑战通过」可以直接用在条件里，例如「已验证的 Bot 等于 false」让规则跳过搜索引擎，「AxisNow 挑战通过等于 false」只对还没通过挑战的客户端限速。 {% endhint %} ## 计数 Key 计数 Key 决定按什么来数。支持多个维度组合，系统把各维度的取值拼成一个唯一键，每个键独立累计。配置方式有两条路：选一个常用组合，或用 **+** 逐个追加维度；两者可以叠加。下方的**计数 Key 预览**实时显示最终表达式，例如 `ip.src + http.request.uri.path`。

### 常用组合

分组	选项	计数 Key	适合
常规限速	客户端 IP 地址客户端 IP 地址 + 请求 URI 路径	`ip.src` `ip.src + http.request.uri.path`	匿名流量的通用兜底限制同一 IP 对单个接口的频率，不影响它访问其它接口
登录态限速	会话 Cookie 会话 Cookie + 请求 URI 路径	`http.request.cookies["``名称``"]` `http.request.cookies["``名称``"] + http.request.uri.path`	登录后的用户按账号限速，不受共享出口影响按账号 + 接口
API 配额限速	API 密钥 API 密钥 + 请求 URI 路径	`http.request.headers["``名称``"]` `http.request.headers["``名称``"] + http.request.uri.path`	开放 API 按调用方限额按调用方 + 接口

选到带「名称」的组合时会立即弹出对话框，让您填 Cookie 名或请求头名（例如 `session_id`、`authorization`、`x-api-key`）。清空常用组合会同时清空已选的全部维度。 ### 可追加的维度 **+** 菜单列出全部维度。其中四个带名称的维度（请求头、匹配指定 URI 参数、POST 表单、匹配指定 Cookie 值）要先填名称，可以用不同名称重复添加；其余维度直接取请求的某个属性，每个只能加一次。

点击计数 Key 右侧的 + 展开维度菜单，列出可追加的全部维度，悬浮每一项会显示取值说明

维度	预览里的写法	取值说明
客户端 IP 地址	`ip.src`	客户端的 IP 地址。启用真实客户端 IP插件后为还原出的真实地址
请求 Host	`http.host`	请求的域名，统一小写
HTTP 请求方法	`http.request.method`	GET、POST 等
请求 URI	`http.request.uri`	路径加查询参数，如 `/path?id=1`，区分大小写
请求 URI 路径	`http.request.uri.path`	只有路径，不含查询参数，如 `/path`，区分大小写
请求完整 URL	`http.request.full_uri`	协议 + Host（不含端口）+ 路径 + 查询参数，不含 `#` 片段
请求头 referer	`http.request.referer`	Referer 头的值，区分大小写
User Agent	`http.request.user_agent`	User-Agent 头的值，区分大小写
会话标识	`http.user_session`	AxisNow 边缘为浏览器下发的跟踪 Cookie，用于区分同一个公共出口 IP 后面的不同用户，仅适用于浏览器环境。请求没有带这个 Cookie 时按客户端 IP 计数，不会落入空值计数器。它不是您业务自己的会话 Cookie，后者用「匹配指定 Cookie 值」
TLS 客户端 JA4 指纹	`ja4_fingerprint`	由 TLS / QUIC 握手特征（协议版本、SNI、加密套件、扩展、ALPN）生成的客户端指纹。同一个工具换 IP 不换指纹
请求头	`http.request.headers["authorization"]`	指定请求头的值，例如 `authorization` 里的 Bearer Token。头名不区分大小写，值区分
匹配指定 URI 参数	`http.request.uri.args["token"]`	指定查询参数的值，例如 `?token=abc123` 里的 `abc123`，名称与值都区分大小写
POST 表单	`http.request.body.form["email"]`	取指定表单字段的值。只解析 `Content-Type` 为 `application/x-www-form-urlencoded` 的请求体；`multipart/form-data` 和 JSON 请求体取不到值，按空值参与计数
匹配指定 Cookie 值	`http.request.cookies["session_id"]`	指定 Cookie 的值

请求中不存在指定的请求头、参数、表单字段或 Cookie 时，该维度以空值参与计数——所有缺这项的请求落在同一个计数器里。按身份计数的规则通常要在条件里限定“带身份的请求”，或另配一条按 IP 的规则兜底，见[工作原理 › 计数 Key](/zh/docs/edge/policies/rate-limiting/how-it-works.md#counting-key)。 {% hint style="info" %} 维度超过三个时控制台会提示：维度过多会让 Key 过碎，计数分散从而限速不易触发。优先选择 Host、URI、IP、会话标识这类稳定维度；只在用 API 密钥、用户标识做精细限速时，再使用请求头、Cookie、查询参数这类自定义维度。 {% endhint %} ### 响应计数条件默认关闭。开启后，只有响应满足条件的请求才计数，例如只统计 5xx、404，或带某个响应头的响应。可用字段两个：

字段	匹配方式
响应状态码	在以下各项之中、不在以下各项之中、在以下范围之中、不在以下范围之中
响应头	先填头名，再选：在以下各项之中、不在以下各项之中、包含字符、不包含字符、存在、不存在

同样支持 And / Or 组合。计数发生在响应阶段，计数达到阈值后从下一个请求起执行限速动作，见[工作原理 › 响应计数条件](/zh/docs/edge/policies/rate-limiting/how-it-works.md#response-counting)。 ## 限速阈值两个数字：时间窗口（秒，≥ 1）和窗口内允许的请求数（≥ 0），读作「N 秒内不超过 M 请求」。例如 `3 秒内不超过 10 请求`、`60 秒内不超过 600 请求`。两者都没有上限；窗口越短，对突发越敏感。计数按滑动窗口估算，不是整窗口清零重数，见[工作原理 › 阈值与窗口](/zh/docs/edge/policies/rate-limiting/how-it-works.md#threshold-and-window)。卡片下方嵌着一张参考图**每 60 秒窗口请求数**，展示所选域名最近 1 小时 / 1 天 / 1 周的请求量和峰值，红色虚线是当前阈值折算到图表时间粒度后的位置。

限速阈值卡片：上方填写时间窗口与请求数，下方的参考图展示所选域名最近一天每 60 秒窗口的请求量，红色虚线标出阈值折算后的位置

{% hint style="info" %} 参考图是全部流量的总和，真正的计数按每个 Key 分别累计，单个 Key 的量远小于总量。它的用途是看日常水位和历史尖峰的数量级，不是精确标定阈值。定阈值更可靠的做法是先用**观察**动作跑一段时间，看洞察里的超限数量再调整。 {% endhint %} ## 限速动作请求频率超过阈值时执行的缓解动作，四选一。四种动作的语义与适用场景见[工作原理 › 四种动作](/zh/docs/edge/policies/rate-limiting/how-it-works.md#actions)，这里只讲各自的配置。 ### 观察只记录超限的请求，不影响请求处理。没有子配置。 ### 阻断拒绝超额请求，作用于触发的计数 Key。两种方式： * **返回页面**：设定响应状态码（400–599，默认 429 Too Many Requests）和页面内容。页面可以**直接编辑**，也可以用**上传内容**上传 HTML、JSON、XML 等文本文件（单个不超过 1 MB）；正文里可用 `${{remote_addr}}`、`${{http_host}}`、`${{ip_src_country}}`、`${{request_id}}`、`${{edge_uuid}}`、`${{current_time}}` 六个变量。默认提供一个带 Request ID、边缘节点、客户端 IP 和时间的 429 页面。 * **断开连接**：不返回任何页面内容。客户端拿不到页面里的 Request ID，误拦截的排查只能依靠访问日志和洞察页的日志检索。对 API 流量建议用**返回页面**加 429 Too Many Requests，正文可以上传一个 JSON 文件，让客户端能识别并退避；注意响应的 `Content-Type` 固定为 `text/html`，客户端应按状态码和 `X-RateLimit` 头识别，不要依赖 Content-Type 解析正文。对明显的扫描流量可以用**断开连接**。 ### IP 封禁按指定时长封禁超频访问的客户端 IP，封禁期内该 IP 到这个节点的全部连接都被丢弃，不区分域名和端口。唯一的配置是**封禁时长**，1 到 31536000 秒（1 年），默认 60 秒。常用取值：试探性规则 60–300 秒，确认的攻击来源 600–3600 秒。目前不能手动解除，设定前请确认条件和阈值不会卷入共享出口的正常用户。 ### 挑战向客户端发起人机验证，仅对浏览器页面导航请求生效，API 调用拿到验证页只会报错。

配置	说明
挑战类型	AxisNow 挑战：访客在浏览器中自动完成轻量校验，开箱即用。第三方挑战：使用您自己的挑战服务，需先在设置里添加挑战提供商（Cloudflare Turnstile 或 Google reCAPTCHA）；提供商为 reCAPTCHA v3 时可设分数阈值（0.0–1.0）
通过有效期	通过挑战后，在此时间内无需再次挑战。选项 30 分钟、1 小时、2 小时、4 小时、12 小时、24 小时（默认），或自定义 60 秒到 7 天。凭证与这条规则、客户端 IP、TLS 指纹绑定
自动封禁	客户端 IP 在窗口内触发挑战的次数达到上限时封禁该 IP。默认 60 秒内 100 次，封禁 5 分钟；窗口可选 10 秒到 10 分钟或自定义 1 秒到 7 天，次数 1 到 100 万，封禁时长 5 分钟、30 分钟、1 小时或 24 小时

## 优先级与保存创建规则时可以选择它的位置：第 1 个、最后 1 个（默认）或自定义序号。规则按序号从小到大评估，严格的规则放前面、宽松的兜底放后面，见[防护场景 › 分层](/zh/docs/edge/policies/rate-limiting/use-cases.md#layering)。创建后可在列表里拖拽或用**移动到**调整。保存有两个按钮：**确认**创建并立即启用；**保存为草稿**创建但不启用，之后在列表的**生效状态**开关或规则页的**管理**菜单里启用。修改已有规则时，控制台会先展示修改前后的配置差异，确认后才生效。规则的启停、改名、删除都在列表的操作菜单或规则页的**管理**菜单里。 ## 给可信来源豁免监控探针、合作伙伴的固定 IP、搜索引擎爬虫的请求模式天然像机器，容易被限速规则误伤。豁免有两种做法： * 在[通用访问控制](/zh/docs/edge/policies/access-control/use-cases.md#trusted)里为这些来源配一条**跳过**规则，并开启**绕过速率控制插件**。访问控制先于速率控制执行，被放行的请求不再进入任何限速规则。这是推荐做法，豁免名单集中在一处。 * 在限速规则的条件里排除它们，例如「客户端 IP 地址不在以下各项之中 {…}」或「已验证的 Bot 等于 false」。适合只想让某一条规则放过它们的情况。 ## 下一步 * [防护场景](/zh/docs/edge/policies/rate-limiting/use-cases.md)：这些字段在四类攻击面上怎么搭配。 * [工作原理](/zh/docs/edge/policies/rate-limiting/how-it-works.md)：每个字段背后的计数与判定逻辑。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://www.axisnow.io/zh/docs/edge/policies/rate-limiting/configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.