文档反馈
问问助手功能简介
火山引擎内容分发网络（CDN）的规则引擎提供了自定义请求处理的能力。您可以通过设置一系列匹配条件和执行动作，来控制 CDN 节点对用户请求的响应方式。例如，您可以实现自定义缓存策略、URL 重写、访问控制、以及请求头和响应头的操作。本文将详细介绍规则引擎的核心概念、处理流程、配置优先级以及具体配置项，并通过示例帮助您快速上手。
要启用规则引擎，请 提交工单。
说明
并非所有 CDN 特性都支持在规则引擎中配置。例如，"回源参数设置" 和 "Multi-range" 等特性只能在“分阶段配置”中设置。有关规则引擎支持的 CDN 特性，请参阅 动作列表。
核心概念
规则引擎包含以下核心概念：
- 规则：规则是规则引擎配置的基本单位，用于定义 CDN 如何处理特定类型的请求。每条规则都包含一个
IF...ELSE...结构的条件表达式。 - 子规则：子规则嵌套在父规则的
IF或ELSE分支下，用于实现更精细的逻辑控制。当请求满足父规则的条件时，CDN 会在执行父规则中定义的动作后继续处理父规则下的子规则。每条规则的IF和ELSE分支下总共可包含最多 10 条子规则。子规则不能再嵌套。 - 条件表达式：条件表达式是规则的核心，用于定义匹配用户请求的逻辑以及 CDN 需要执行的动作。条件表达式由
IF和ELSE两部分组成。如果请求满足IF中定义的条件，则 CDN 执行IF下的动作；否则，执行ELSE下的动作。 - 匹配条件：匹配条件用于定义
IF语句的匹配逻辑。您可以创建一个或多个匹配条件，并定义匹配条件之间的逻辑关系。逻辑关系有 全部满足 和 满足任意。匹配条件有以下类型：- 单条件：由条件类型、运算符和匹配值组成。
- 条件组：包含多个单条件及单条件之间的逻辑关系。
- 动作：动作表示 CDN 在请求满足匹配条件后执行的具体操作，例如重定向 URL 或修改 HTTP 响应头。
下图展示了这些概念之间的关系：
创建规则
规则引擎提供以下三种创建规则的方式：
- 普通创建：创建一条空白规则。
- 使用模板创建：基于预设的模板来创建规则。模板中包含了特定场景的配置。
- 复制已有规则的 DSL 代码：基于已有规则的 DSL 代码来创建规则。
普通创建
创建一个空白规则，然后根据您的需求配置规则。
使用模板创建
规则引擎为常见场景提供了配置模板。您可以基于模板创建规则，以提高配置效率。
例如，在配置精细化的封禁策略时，您可以选择 精细化封禁规则 模板来生成基础配置。之后，您只需要微调规则配置以适配您的业务场景。
复制已有规则的 DSL 代码
在规则引擎中，系统会为每条规则生成对应的 DSL 代码。在规则的右上方，您可以点击 DSL 来查看代码。您可以复制已有规则的 DSL 代码来创建规则，然后进一步修改规则配置。
处理流程
规则执行逻辑
CDN 按照规则列表的顺序，自上而下依次处理每条规则。具体的执行逻辑如下：
- 单条子规则：遵循
IF...ELSE...逻辑。如果请求满足IF条件，则 CDN 执行IF下的动作；否则，执行ELSE下的动作。 - 单条规则：
- 规则下无子规则：直接遵循
IF...ELSE...逻辑。 - 规则下有子规则：
- 如果请求满足外层
IF条件，CDN 会先执行外层IF下的动作，然后按顺序处理外层IF下的所有子规则。 - 如果请求不满足外层
IF条件，CDN 会先执行外层ELSE下的动作，然后按顺序处理外层ELSE下的所有子规则。
- 如果请求满足外层
- 规则下无子规则：直接遵循
- 多条规则：CDN 会按顺序逐一处理所有规则。
动作执行阶段
在处理用户请求的过程中，CDN 最多会经历五个阶段。规则引擎中的动作会在特定的阶段执行，如下图所示：
规则引擎主要在以下两个阶段对请求进行匹配：
- 收到用户请求
- 收到源站响应
每个动作都有其执行阶段。下表总结了条件类型、动作和动作执行阶段的对应关系：
可指定的条件类型 | 可指定的动作 | 动作执行阶段 | |
|---|---|---|---|
用户请求 |
|
| 客户端请求 |
| 回源请求 | ||
| CDN 缓存 | ||
HTTP 响应头设置 | 客户端响应 | ||
源站响应 |
| HTTP 响应头设置 | 客户端响应 |
配置优先级
相同动作的优先级
CDN 按照“从上至下、从外向内”的顺序处理规则和子规则。当多个子规则中配置了相同的动作时，后执行动作中的配置生效。
示例：
假设您有如下规则配置。当 CDN 收到对 /docs/3.php 的请求，且源站响应包含 param_a、param_b 和 param_c 三个响应头时，最终客户端收到的响应将不包含 param_a 和 param_b，但会包含 param_c，且 param_c 的值被设置为 value_2。
规则引擎与分阶段配置的优先级
如果您在规则引擎和“分阶段配置”中都设置了同一个 CDN 特性，规则引擎中的优先级更高。
示例：
假设您希望对 .php 文件的回源请求设置 HTTP 超时为 10 秒，其他文件为 5 秒。您可以如下配置：
条件与动作详解
条件列表
下表列出了所有可用的条件类型和说明。
条件类型 | 说明 | 可指定的运算符 | 忽略大小写 |
|---|---|---|---|
全部（任意请求） | 对任何用户请求都生效。 | N/A | N/A |
请求路径 | 用户请求 URL 中的路径，不包含查询字符串。 | 等于、不等于、前缀匹配、前缀不匹配、后缀匹配、后缀不匹配、正则匹配、正则不匹配 | 支持 |
URL（不含协议、host） | 用户请求 URL 中的路径和查询字符串。 | ||
完整 URL | 完整的用户请求 URL。 | ||
请求参数 | 用户请求 URL 中的查询参数。 | 等于、不等于、存在、不存在、正则匹配、正则不匹配 | |
Origin 请求头 | 用户请求中的 | ||
Referer 请求头 | 用户请求中的 | ||
UA 请求头 | 用户请求中的 | ||
HTTP 请求头 | 用户请求中的指定头部。 | ||
源站响应头 | 源站响应中的指定头部。 | ||
客户端 IP | 发送用户请求的客户端 IP 地址。 | 匹配、不匹配 | N/A |
请求时间 | CDN 收到用户请求的时间，可选项有每日、每周或特定时间段。特定时间段精确到秒。 | ||
客户端区域 | 客户端 IP 地址所在的国家或地区。 | ||
源站响应状态码 | 源站响应中的 HTTP 状态码。 | ||
请求方法 | 用户请求使用的 HTTP 方法。 | 等于、不等于 | |
请求协议 | 用户请求使用的协议，可以是 HTTP 或者 HTTPS。 |
说明
- 运算符：
- 等于/不等于：进行精确的字符串匹配。
- 前缀/后缀匹配：判断字符串是否以指定的前缀开头或者以指定的后缀结尾。
- 正则匹配：判断字符串是否匹配指定的正则表达式。例如，对于字符串
abc123a45，正则表达式[0-9]{1,}a{1,3}会匹配到123a，因此视为匹配成功。要使用 正则匹配，请 提交工单。
- 多个匹配值的逻辑：
- 对于“等于”、“前缀匹配”、“后缀匹配”、“正则匹配”，多个匹配值之间的关系是 “或”。
- 对于“不等于”、“前缀不匹配”、“后缀不匹配”、“正则不匹配”，多个匹配值之间的关系是“且”。
动作列表
下表列出了所有可用的动作、动作的执行阶段和配置说明。
动作 | 动作执行阶段 | 配置说明 |
|---|---|---|
URL 重定向改写 | 客户端请求 | |
允许访问 | ||
协议强制跳转 | ||
下载限速 | ||
客户端请求头设置 | 在 CDN 处理客户端请求前，您可以新增、修改、或删除客户端请求中的 HTTP 头部。 | |
拒绝访问 | ||
URL 鉴权 | 参见文档。在规则引擎中，您可以对各鉴权类型配置 "M3U8 改写"。 | |
缓存键值 | CDN 缓存 | 参见下方 缓存键值说明。 |
智能压缩 | ||
视频拖拽 | ||
节点缓存规则 | ||
HTTP 响应头设置 | 客户端响应 | |
Range 回源 | 回源请求 | |
回源重定向跟随 | ||
回源 TCP 超时 | ||
回源 HTTP 超时 |
缓存键值说明
在 CDN 中，您可以通过以下两种方式配置缓存键：
- 常规方式：在域名配置页面，您可以创建缓存键规则，指定缓存键包含的查询参数。更多信息，参见 缓存键值。
- 规则引擎：您也可以在规则引擎中配置缓存键。规则引擎提供了更丰富的配置项。除了查询参数，您还可以：
- 设置缓存键中包含的请求头。
- 设置缓存键中包含的 Cookie。
- 改写缓存键中的文件路径。
- 指定缓存键中的文件路径是否区分大小写。
说明
默认情况下，缓存键包含所有查询参数，但不包含任何 Cookie 和请求头。
以下是规则引擎中缓存键值的配置说明。
配置 | 说明 |
|---|---|
查询字符串 | 用于指定缓存键中需要包含请求 URL 中的哪些查询参数。该配置有以下选项：
您还可以指定参数名称是否区分大小写。例如，您指定保留的参数是 |
请求路径 | 用于改写缓存键中的文件路径。您需要指定 改写前路径 以及 改写后路径。改写前路径 是一个正则表达式。 路径必须以 参见下方的路径改写示例。 |
HTTP 请求头 | 用于指定缓存键中包含哪些请求头。头部名称不区分大小写。您可以指定最多 30 个头部，多个头部之间以回车分隔。头部名称可以包含字母、数字、下划线（_）和连字符（-），长度不能超过 30 个字符。 指定的请求头列表的顺序会影响缓存匹配结果。例如，缓存键中的头部列表是 header1, header2。CDN 收到的请求中的头部列表是 header2，header1。在这个情况下，该请求无法匹配缓存。 说明 默认情况下，缓存键中不包含任何请求头。 |
Cookie | 用于指定缓存键中包含的 Cookie。通过指定 Cookie 的键（Key）来设置需要保留的 Cookie。该配置有以下选项：
说明 默认情况下，缓存键中不包含任何 Cookie。 |
缓存路径忽略大小写 | 用于指定缓存键中的文件路径是否区分大小写。 |
缓存键中的路径改写示例
配置
- 改写前路径：^/a{1,2}(.*)g$
- 改写后路径：/food$1g
改写示例
- /a/bbb/image.png 改写为 /food/bbb/image.png
- /c/a/bbb/image.png 不会被改写
变量说明
在以下两个动作的配置中，您可以使用变量来获取特定对象的值。
- 客户端请求头设置
- HTTP 响应头设置
要在参数值中使用这些变量，使用的格式是 ${*变量*}。例如，您设置某个 HTTP 响应头的值为 my ${request_uri} is ${host}.
CDN 提供的变量列表如下。
变量名称 | 说明 | 示例 |
|---|---|---|
request_uri | 表示客户端请求 URL 中的路径和查询字符串（query string）。 |
|
raw_uri | 表示客户端请求 URL 中的路径。 |
|
host | 表示客户端请求中 host 头部的值。需要留意的是，CDN 在处理请求时可能会修改 |
|
http_host | 表示客户端请求中 host 头部的值。该头部值不会被 CDN 修改。 |
|
args | 表示客户端请求 URL 中的查询字符串。 |
|
query_string | 与 |
|
scheme | 表示客户端使用的协议。 |
|
remote_addr | 表示发起本次请求的客户端的 IP 地址。 |
|
msec | 表示 CDN 设置响应头的时间，格式是 Unix 时间戳，精确到毫秒。该时间戳接近首包的响应时间。 |
|
http_%s | 表示一个特定头部的值， |
|
arg_%s | 表示一个特定查询参数的值， |
|
应用场景
允许或拒绝特定客户端请求
根据客户端请求的特征（如请求头、客户端 IP、请求 URL、客户端所在地区等），制定黑白名单策略，并指定 CDN 的响应状态码。
设置缓存策略
根据客户端请求的特征（如请求头、请求 URL、客户端所在地区等）设置不同的缓存时间。
您还可以实现特定的缓存需求，例如让 CDN 对 OPTIONS 请求直接响应 200 状态码。
对特定客户端请求限速
根据客户端请求的特征（如请求 URL 中的参数、客户端所在地区等）对请求进行限速。
对跨域请求设置校验策略
您可以实现复杂的跨域资源共享（CORS）策略。例如，除了标准的 HTTP/HTTPS 请求外，您还可以还允许来自微信小程序的跨域请求，并根据请求中的 Origin 头部动态设置 Access-Control-Allow-Origin 响应头。
修改 Content-Disposition 响应头
您可以自定义浏览器下载时显示的文件名，并防止文件在下载过程中被劫持。
要实现此目的，您可以通过名为 filename 的查询参数、请求头或 Cookie 来传递文件的真实名称，然后将 Content-Disposition 响应头设置为 attachment;filename="${arg_filename}";filename*=utf-8''${arg_filename}。
说明
- 在本示例中，文件的真实名称通过查询参数传递。
filename*=utf-8''${arg_filename}格式遵循 RFC 5987 规范。filename="${arg_filename}";用于兼容某些旧版浏览器不支持 RFC 5987 的情况。需要留意的是，对于这些旧版浏览器，下载文件的名称可能会显示为乱码。
附录：匹配值输入要求
条件类型 | 输入要求 |
|---|---|
请求路径 |
|
URL（不含协议、host） |
|
完整 URL |
|
请求参数 |
|
Origin 请求头 |
|
Referer 请求头 |
|
UA 请求头 |
|
HTTP 请求头 |
|
源站响应头 |
|
客户端 IP |
|