规则引擎功能使用图形化方式配置条件规则。条件规则支持识别用户请求中的各种参数信息，以决定某个配置是否对该请求生效，可用于灵活、精确地控制CDN的配置策略执行效果。
背景说明
阿里云CDN产品控制台提供了配置缓存过期时间、回源参数改写等基础功能，满足大部分通用需求。但对于一些特殊需求，如将包含路径/example的请求回源到指定源站地址，则需要结合规则引擎实现自定义配置。此外，阿里云CDN还提供了边缘脚本功能，支持高度灵活的用户定制需求。
配置能力 | 基础功能 | 基础功能+规则引擎 | 边缘脚本 |
功能实现 | 常见的通用功能配置 | 通过图形化配置界面实现各种条件过滤目的的规则，支持 URI、Header、Cookie、Query String 等多种匹配类型，以及 AND/OR 逻辑组合。 | 支持高度灵活的用户定制需求，适合需要编写自定义脚本的高级场景。 |
使用场景 | 常见的通用需求 | 部分自定义高级配置需求 | 定制化的用户需求 |
上手难度（对用户技术要求） | 低 | 中 | 高 |
配置灵活性 | 低 | 中 | 高 |
复杂逻辑配置与边缘脚本替代方案
规则引擎支持基础的 AND/OR 逻辑组合，适用于大部分条件过滤场景。但以下场景建议使用边缘脚本（EdgeScript）替代：
复杂正则匹配：规则引擎的正则运算符默认禁用，需提交工单申请开启。对于需要频繁使用正则表达式的场景，边缘脚本原生支持正则匹配，更加便捷。
多维度精确组合：若需同时匹配客户端 IP 和 User-Agent 并使用正则表达式进行复杂判断（例如拦截特定 IP 段且 UA 包含特定关键词的请求），规则引擎的配置可能较为繁琐。边缘脚本支持通过脚本逻辑灵活组合多种条件。
多目录 IP 精细化控制：若需实现不同 IP 段访问不同目录，例如指定 IP 段可访问所有目录、指定 IP 仅可访问特定目录、其他 IP 全部拒绝，请使用 EdgeScript 的
match_re匹配 IP 和 URI 路径，使用return true放行，使用exit(403)拒绝。
注意事项
单个域名下最多支持创建50个规则条件。
单个规则条件中的子条件数量最多不超过20个。
通过控制台或者OpenAPI来配置时，无法使用正则相关的匹配运算符（包括正则匹配和正则不匹配），但是可以查看已有配置。如果要使用正则相关的匹配运算符，推荐使用边缘安全加速。
通过控制台或者OpenAPI配置时，单个域名下所有功能对规则条件的总引用次数最大不超过5次。
规则条件支持嵌套，嵌套层次最多为3层，不同层级支持独立的逻辑关系设置。
缓存过期时间、修改出站请求头等其他功能引用规则条件后，按所关联规则条件的优先级执行，而非按功能自身的配置顺序执行。
上述数量限制中，50 个规则条件、20 个子条件、3 层嵌套为系统硬性上限，无法通过后台申请调整；单个域名下所有功能对规则条件的总引用次数上限（默认 5 次）支持申请提升。
若需提升单个域名下规则条件的总引用次数上限（默认 5 次），需提交工单申请，工单中需提供以下信息：需要提升的加速域名、目标引用次数、业务场景说明。
后续若新增其他加速域名，需为该域名单独提交工单申请提升规则条件引用次数，流程与首次申请一致。
每个条件的匹配值最多支持 32 个（适用于客户端 IP、URI、文件扩展名、文件名、User-Agent 等匹配类型）。若客户端 IP 白名单数量较多，建议将多个 IP 地址转换为 IP 段（CIDR 格式，例如
120.209.XXX.X/24）进行配置，以节省匹配值配额。User-Agent 匹配值最多支持配置 32 个，超过该数量的配置不生效。若需匹配大量 User-Agent，建议使用通配符（
*）合并相似的 UA 值（例如*Chrome*可覆盖所有 Chrome 浏览器版本），或改用边缘脚本实现更灵活的匹配逻辑。
功能优先级与执行逻辑
配置规则引擎时，需注意以下功能优先级和执行逻辑：
Referer 防盗链优先级高于规则引擎：当请求携带 Referer 时，系统先执行 Referer 黑白名单校验。若命中 Referer 白名单，请求直接放行，不再执行规则引擎中的其他条件判断；若未命中白名单，请求直接被拦截。只有当请求的 Referer 为空时，才不会触发 Referer 黑白名单的放行或拦截逻辑，请求会继续匹配规则引擎中配置的条件。
规则条件引用功能的执行顺序：缓存过期时间、修改出站请求头等功能引用规则条件后，按所关联规则条件的优先级执行，而非按功能自身的配置顺序执行。例如，若缓存过期时间和回源参数改写分别引用了优先级不同的规则条件，系统会按规则条件的优先级从高到低依次执行。
鉴权与缓存配置冲突排查：若配置 URL 鉴权后出现非预期行为（如不携带鉴权参数仍可正常访问、或合法链接被误拦截），请按以下顺序排查：
检查是否配置了 WAF 白名单，WAF 白名单可能绕过CDN的鉴权逻辑导致请求直接放行。
检查忽略 URL 参数配置是否将鉴权参数（如
auth_key）过滤掉，导致缓存命中时跳过鉴权校验。确认鉴权参数未被缓存 Key 规则忽略，避免不同鉴权参数的请求命中同一缓存。
规则条件的语法说明
一个规则条件由“逻辑判断运算符”与“条件表达式”构成，具体见下方说明。
逻辑判断（Logic）
对同一个层级内的条件（包括被嵌套的条件集合）进行逻辑判断，支持and和or。
and（并且）：逻辑与运算符，所有条件都为真才会匹配成功。or（或者）：逻辑或运算符，其中一个条件为真即可匹配成功。例如为同一个响应头配置多个规则条件，可实现不同条件下添加相同响应头的效果。示例：当 URI 包含/path-a或 URI 包含/path-b时，执行添加响应头的操作。
条件表达式包含的参数
最小粒度的条件表达式包含以下参数：
参数名称 | 域名配置功能函数condition中对应的配置参数 | 参数说明 | 是否必填 |
条件匹配 | match | 表示条件匹配表达式。 | 是 |
逻辑判断 | logic | 表示条件匹配表达式的逻辑判断参数，取值为 | 是 |
条件判断内容 | criteria | 表示条件表达式的判断内容。 | 是 |
匹配类型 | MatchType | 表示对用户请求中携带的某一类型信息进行匹配。 | 是 |
匹配对象 | MatchObject | 表示对匹配类型进行进一步的细分，例如：客户端IP可以细分为“建联IP”和“XFF IP”。 | 否 |
匹配运算符 | MatchOperator | 表示匹配操作执行的具体动作。 | 是 |
匹配值 | MatchValue | 表示预先设定的匹配值，将会与用户请求中携带的信息进行匹配。 | 是 |
条件判断值取反 | negate | 表示是否对条件表达式的结果取反，取值为true和false。 | 是 |
大小写敏感 | caseSensitive | 表示对匹配值中的字符是否大小写敏感。 | 否 |
规则条件名称 | name | 表示规则条件的名称。 | 是 |
生效状态 | status | 表示规则条件的生效状态。 | 是 |
条件表达式的配置方法
匹配类型名称 | 域名配置功能函数condition中对应的配置参数 | 匹配类型含义 | 匹配对象 | 匹配运算符 | 匹配值 | 大小写敏感 | 对应nginx/tengine |
协议类型 | scheme | 客户端请求使用的协议类型，例如：HTTP、HTTPS。 | 不涉及 |
|
| 不涉及 | $scheme |
请求方法 | method | 客户端请求使用的请求方法，例如：GET、PUT。 | 不涉及 |
|
| 不涉及 | $request_method |
URI（路径） | uri | 客户端请求URL中的路径，不含请求参数，例如： | 不涉及 |
| 支持通配符 |
| $raw_uri或$uri |
文件名 | basename | 客户端请求的文件的名称，例如：name1。 | 不涉及 |
| 支持通配符 |
| - |
文件扩展名 | extension | 客户端请求的文件的后缀名，从右向左识别，识别到第一个"."，例如： | 不涉及 |
| 支持通配符 |
| - |
Hostname | hostname | 客户端请求携带的hostname，匹配顺序：请求URL中的host>请求头HOST中的host。 | 不涉及 |
| 用户请求的host，支持输入多个值。 |
| $host或$http_host |
客户端IP | clientip | 客户端的IP。 支持IPv4（例如 |
说明 建联IP、XFF IP详细说明，请参见IP地址校验模式。 |
| 支持填写IPv6格式IP，例如：240e:XXX:3004:2:3:0:0:3f7，支持网段方式填写，例如：120.209.XXX.XXX/31，支持输入多个值。 | 不涉及 | $remote_addr |
客户端IP版本 | clientipVer | IPv4或IPv6。 |
说明 建联IP、XFF IP详细说明，请参见IP地址校验模式。 |
|
| 不涉及 | - |
用户网络运营商 | geolocation | 客户端IP归属的运营商。 |
说明 建联IP、XFF IP详细说明，请参见IP地址校验模式。 |
| 可以通过下拉列表来选择，可以输入字符来过滤选项，支持输入ID或名称来模糊匹配查询，支持输入多个值。 | 不涉及 | $ip_isp_id |
用户IP地理位置 | geolocation | 客户端IP所处的地理位置。 |
说明 建联IP、XFF IP详细说明，请参见IP地址校验模式。 |
| 可以通过下拉列表来选择，可以输入字符来过滤选项，支持输入ID或名称来模糊匹配查询，支持输入多个值。 | 不涉及 | $ip_country_id |
请求参数 | querystring | 用户请求URL中携带的请求参数。 | 输入参数名称。 |
| 支持通配符 |
| $arg_{name} |
请求头 | header | 用户请求中携带的请求头。 | 支持输入参数名称，也支持通过下拉列表来选择参数。 |
| 支持输入多个值。 |
| $http_{name} |
Cookie | cookie | 请求携带的Cookie。 | 输入Cookie名称。 |
| 支持通配符 |
| $cookie_{name} |
User-Agent | useragent | 请求头里的User-Agent。 | 不涉及 |
| 可以选择下拉列表中的值，或者直接输入UA值，例如： |
| $http_user_agent |
Range分桶 | range | 将客户端请求分桶，按百分比执行。 | 不涉及 |
| 输入百分比的数值。 | 不涉及 | - |
时间 | time | 客户端请求发生的时间，时区为东八区（北京时间），例如：09:10~14:22。 | 不涉及 |
| 直接输入时间段，例如09:10~14:22 ，表示9点10分至14点22分。 | 不涉及 | - |
Nginx Var | ngxvar | 当上方所有的变量均无法满足需求时，支持使用Nginx变量来配置，支持的变量详见Nginx官网：Nginx变量。 | 可以通过下拉列表来选择或直接输入变量名，支持 |
| 支持输入多个值。 | 不涉及 | ${name} |
条件表达式常见配置说明
URI（路径）匹配起始位置：URI 匹配的值为域名后第一个
/开始的路径部分，不包含域名和请求参数。例如，对于请求https://example.com/path/file.html?key=value，实际匹配的 URI 值为/path/file.html。配置匹配值时需以/开头。文件扩展名匹配格式：配置文件扩展名匹配时，匹配值必须包含点号（
.）。例如，要匹配.txt文件，应填写.txt而非txt，否则可能导致匹配失败。通配符使用示例：URI 和文件扩展名均支持通配符
?（匹配任意 1 个字符）和*（匹配任意多个字符）。常用示例：/*.pdf：匹配根目录下所有 PDF 文件。/api/*/data：匹配/api/下任意子路径中的data路径。.??：匹配所有两个字符的文件扩展名（如.js、.ts）。
IP地址校验模式
规则引擎功能的“IP地址校验模式”分为两种，使用不同的“IP地址校验模式”会影响到CDN节点对客户端IP的判断：
建联 IP：该模式匹配客户端与CDN节点之间建连使用的IP，如果客户端与CDN节点之间有经过代理服务器，那么建联IP=代理服务器IP。
XFF IP：该模式匹配用户请求中x-forwarded-for请求头携带的左边第一个IP，不论客户端与CDN节点之间是否有经过代理服务器，XFF IP都=客户端真实IP。
选择使用哪一种“IP地址校验模式”主要取决于用户请求在经过CDN节点时，中间是否有经过代理服务器。
需注意，引用规则条件的功能在CDN节点上的生效位置也会影响到对“IP地址校验模式”的选择（对于在L2节点上生效的回源配置相关功能而言，用户请求经过的L1节点就相当于中间经过了代理服务器）。
示例：假设客户端真实IP为10.10.10.10，代理服务器IP为192.168.0.1。
没有经过代理服务器：
用户请求中x-forwarded-for请求头值：
10.10.10.10。客户端真实IP（即x-forwarded-for请求头携带的左边第一个IP）=客户端与CDN节点建连IP=
10.10.10.10。
经过代理服务器：
用户请求中x-forwarded-for请求头值：
10.10.10.10,192.168.0.1。客户端真实IP（即x-forwarded-for请求头携带的左边第一个IP）=
10.10.10.10。客户端与CDN节点建连IP=代理服务器IP=
192.168.0.1。客户端真实IP（即x-forwarded-for请求头携带的左边第一个IP）≠客户端与CDN节点建连IP。
少数互联网服务提供商（ISP）在特定区域可能会分配私有IP地址给用户端，导致CDN节点接收到的是用户的私有IP地址。
私有IP地址范围有以下三个：
A类私有IP地址：10.0.0.0～10.255.255.255，子网掩码：10.0.0.0/8
B类私有IP地址：172.16.0.0～172.31.255.255，子网掩码：172.16.0.0/12
C类私有IP地址：192.168.0.0~192.168.255.255，子网掩码：192.168.0.0/16
匹配运算符（matchOperator）
名称 | 域名配置功能函数condition中对应的配置参数 | 含义 |
等于 | matchOperator为equals。 | 变量完全等于匹配值或者完全不等于匹配值的时候，条件才成立。 |
不等于 | matchOperator为equals，并且参数negate的值为true。 | |
存在 | matchOperator为exists。 | 变量存在或者不存在时，条件即成立。 |
不存在 | matchOperator为exists，并且参数negate的值为true。 | |
包含其中任意一个 | matchOperator为contains。 | 变量包含（不包含）任意一个匹配值的时候，条件即成立。最多支持32个匹配值。 包含匹配的情况有两种：
|
不包含其中任意一个 | matchOperator为contains，并且参数negate的值为true。 | |
大于 | matchOperator为gt。 | 即 |
小于 | matchOperator为lt。 | 即 |
大于等于 | matchOperator为ge。 | 即 |
小于等于 | matchOperator为le | 即 |
正则匹配 | matchOperator为regex。 | 匹配值可以填写正则表达式，实现对变量的正则匹配。 说明 通过控制台或者OpenAPI来配置的情况下，无法使用正则相关的匹配运算符（包括正则匹配和正则不匹配），但是可以查看已经存在的配置。 |
正则不匹配 | matchOperator为regex，并且参数negate的值为true。 |
通配符
通配符号 | 含义 | 路径匹配示例 |
| 表示匹配任意1个字符。 |
|
| 表示匹配任意多个字符。 |
|
当前支持引用规则条件的功能
功能分类 | 功能名称 |
基本配置 | |
缓存配置 | |
回源配置 | |
访问控制 | |
性能优化 | |
视频相关 | |
流量限制 |
配置查看与管理说明
执行动作查看位置：规则引擎页面仅定义规则条件，不直接配置执行动作。具体的执行动作（如缓存过期时间、URL 改写、限速等）需在引用了该规则的对应功能页面查看和管理。例如，若某个缓存过期时间配置引用了规则条件，需在「缓存配置」>「缓存过期时间」中查看和修改。
远程鉴权不支持绑定规则引擎：远程鉴权功能目前不支持引用规则条件，无法通过规则引擎控制远程鉴权的生效范围。
鉴权超时限制：远程鉴权的鉴权超时时长最高可设置为 3000 毫秒（3 秒），默认值为 500 毫秒，这是系统支持的极限值。
高级用法
以下为结合规则引擎实现高级配置的典型场景：
差异化限速策略：若需对部分请求限速、部分不限速（例如对携带鉴权参数的地址限速，对其他地址不限速），或配置兜底限速策略，可在规则引擎中创建区分请求特征的规则条件，然后在「单请求限速」中分别引用不同规则条件并设置不同的限速值。
基于 IP 的灰度回源：若需实现基于客户端 IP 的灰度发布或特定 IP 回源到不同源站，可在规则引擎中创建 IP 匹配条件，然后在「条件源站」中引用该规则条件，指定不同的回源地址。
混合源站架构建议：若需同时使用 WAF 和 OSS 作为源站，不建议直接配置多个主源站。应使用规则引擎根据 URL 路径创建匹配条件，然后通过「条件源站」动态指定不同路径的回源地址，避免多源站回源冲突。
操作步骤
登录CDN控制台。
在左侧导航栏，单击域名管理。
在域名管理页面，找到目标域名，单击操作列的管理。
在指定域名的左侧导航栏，单击规则引擎。
单击添加规则。
在添加规则页面，设置规则名称和规则内容。
单击提交，完成配置。
典型配置场景
以下列举三个高频配置场景的实现思路。
场景一：IP 白名单访问控制与非白名单跳转
需求：仅允许特定 IP 访问站点，其他 IP 自动跳转至维护页面。
配置思路：
在规则引擎中创建规则条件，设置匹配类型为「客户端 IP」，匹配运算符为「不包含其中任意一个」，匹配值填写白名单 IP 地址。
在「缓存配置」>「访问 URL 改写」中引用该规则条件，将匹配到的请求（即非白名单 IP）重定向至指定的维护页面 URL（例如 OSS 上托管的 HTML 页面）。
注意事项：
若非白名单 IP 返回 403 而非预期跳转，需检查是否配置了多个 OSS 源站导致回源冲突。建议一个CDN域名只对应一个主 OSS 源站。
确保目标维护页面 URL 可公开访问，且未被其他访问控制规则拦截。
默认行为：IP 白名单规则关联 URI 路径匹配条件时，仅匹配该 URI 路径的请求触发 IP 白名单检查，不匹配该 URI 路径的请求默认放行。若需对所有路径实现全量 IP 访问控制，请使用边缘脚本（EdgeScript）编写自定义逻辑。
场景二：Referer 防盗链与文件扩展名组合控制
需求：限制特定扩展名文件的 Referer 访问，但允许空 Referer 访问特定扩展名的文件。
配置思路：
在规则引擎中创建规则条件，设置匹配类型为「文件扩展名」，匹配运算符为「不包含其中任意一个」，匹配值填写需要豁免的扩展名（如
.pdf）。在「访问控制」>「Referer 防盗链」中引用该规则条件。这样，非指定扩展名的请求受 Referer 黑白名单限制，而指定扩展名的空 Referer 请求可通过规则豁免。
场景三：阻止非图片视频文件访问
需求：OSS 存储桶通过 CDN 加速对外服务，需阻止 .html 等非媒体文件被拼接恶意链接访问。
配置思路：
在规则引擎中创建规则条件，设置匹配类型为「文件扩展名」，匹配运算符为「包含其中任意一个」，匹配值填写
.html,.htm,.php,.asp,.jsp。添加规则条件，设置匹配类型为「客户端 IP」，匹配运算符为「不包含其中任意一个」，匹配值填写白名单 IP 地址。
在「访问控制」中引用该规则条件，对匹配到的请求（即非白名单 IP 且请求非指定图片视频格式的文件）返回 403。
说明（上传侧限制）：
CDN 规则引擎限制的是访问侧，上传侧无法通过规则引擎控制。若需在上传阶段限制文件类型，可使用 OSS PostObject 接口并配置 Policy 限制文件类型（例如设置 starts-with $Content-Type image/ 可拒绝 .html 等非图片文件的上传）；OSS PutObject 接口不检查文件类型，无法在上传阶段拦截非媒体文件。