自定义规则集（zone 级别）

创建和管理 zone 级别的自定义规则集，用于 WAF 规则。

Custom ruleset 是 custom rules 的集合，可在 zone 或账户级别部署。

与 custom rules 类似，custom ruleset 允许你通过过滤请求来控制传入流量。

例如，你可以将 custom ruleset 应用于 zone 的所有传入请求，或应用于部分传入请求。

在 zone 级别，所有客户都可以创建和部署 custom ruleset。账户级 custom ruleset 需要 Enterprise 计划。更多详情请参阅可用性。

创建自定义规则集并不会激活它。只有当带有 execute 操作的规则从 阶段入口点规则集（Cloudflare 在给定 阶段 为每个请求评估的顶级规则集）引用该自定义规则集时，它才会运行。

要为 zone 部署自定义规则集：

1. 在 zone 级别创建包含一条或多条规则的自定义规则集。或者，使用 List zone rulesets API 操作识别要部署的现有自定义规则集。
2. 向 http_request_firewall_custom 阶段入口点规则集添加一条带有 execute 操作的规则，并引用该自定义规则集 ID。此规则指示 Cloudflare 在规则表达式匹配时运行该自定义规则集。

以下请求在 zone 级别创建包含两条规则的新自定义规则集。响应将在 id 字段中包含新自定义规则集的 ID。

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets" \
	--request POST \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"name": "Custom Ruleset 1",
		"description": "My First Custom Ruleset (zone)",
		"kind": "custom",
		"phase": "http_request_firewall_custom",
		"rules": [
				{
						"expression": "(ip.src.country in {\"GB\" \"FR\"} and cf.bot_management.score < 20 and not cf.bot_management.verified_bot)",
						"action": "challenge",
						"description": "challenge GB and FR based on bot score"
				},
				{
						"expression": "not http.request.uri.path wildcard \"/api/*\"",
						"action": "challenge",
						"description": "challenge not /api"
				}
		]
	}'

{
	"result": {
		"id": "f82ccda3d21f4a02825d3fe45b5e1c10",
		"name": "Custom Ruleset 1",
		"description": "My First Custom Ruleset (zone)",
		"kind": "custom",
		"version": "1",
		"rules": [
			{
				"expression": "(ip.src.country in {\"GB\" \"FR\"} and cf.bot_management.score < 20 and not cf.bot_management.verified_bot)",
				"action": "challenge",
				"description": "challenge GB and FR based on bot score"
			},
			{
				"expression": "not http.request.uri.path wildcard \"/api/*\"",
				"action": "challenge",
				"description": "challenge not /api"
			}
		],
		"last_updated": "2025-11-09T10:27:30.636197Z",
		"phase": "http_request_firewall_custom"
	},
	"success": true,
	"errors": [],
	"messages": []
}

通过向 http_request_firewall_custom 阶段入口点规则集添加一条带有 "action": "execute" 的规则来部署自定义规则集。

1. 调用获取区域入口点规则集操作，以获取 http_request_firewall_custom 阶段的入口点规则集定义。您需要有区域 ID才能完成此任务。

   Required API token permissions

   At least one of the following token permissions is required:

   • Zone WAF Write
   • Zone WAF Read

   curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/phases/http_request_firewall_custom/entrypoint" \
   	--request GET \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

   {
   	"result": {
   		"description": "Zone-level phase entry point",
   		"id": "<ENTRY_POINT_RULESET_ID>",
   		"kind": "zone",
   		"last_updated": "2025-11-16T15:40:08.202335Z",
   		"name": "zone",
   		"phase": "http_request_firewall_custom",
   		"rules": [
   			// ...
   		],
   		"version": "10"
   	},
   	"success": true,
   	"errors": [],
   	"messages": []
   }

2. 如果入口点规则集已存在（即，如果您收到 200 OK 状态代码和规则集定义），请记下响应中的规则集 ID。然后，调用创建区域规则集规则操作，向现有规则集中添加一条 execute 规则，以部署 custom ruleset you created in Step 1 (replace f82ccda3d21f4a02825d3fe45b5e1c10 with your custom ruleset ID).
   Since the expression is true, the custom ruleset will run for all incoming requests。默认情况下，该规则将添加到规则集中已有规则列表的末尾。

   Required API token permissions

   At least one of the following token permissions is required:

   • Zone WAF Write

   curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$ENTRY_POINT_RULESET_ID/rules" \
   	--request POST \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   	--json '{
   		"action": "execute",
   		"expression": "true",
   		"action_parameters": {
   				"id": "f82ccda3d21f4a02825d3fe45b5e1c10"
   		},
   		"description": "Execute custom ruleset"
   	}'

   {
   	"result": {
   		"id": "<ENTRY_POINT_RULESET_ID>",
   		"name": "zone",
   		"description": "Zone-level phase entry point",
   		"kind": "zone",
   		"version": "11",
   		"rules": [
   			// ... any existing rules
   			{
   				"id": "<RULE_ID>",
   				"version": "1",
   				"action": "execute",
   				"action_parameters": {
   					"id": "f82ccda3d21f4a02825d3fe45b5e1c10"
   				},
   				"expression": "true",
   				"description": "Execute custom ruleset",
   				"last_updated": "2025-11-18T18:08:14.003361Z",
   				"ref": "<RULE_REF>",
   				"enabled": true
   			}
   		],
   		"last_updated": "2025-11-18T18:08:14.003361Z",
   		"phase": "http_request_firewall_custom"
   	},
   	"success": true,
   	"errors": [],
   	"messages": []
   }

3. 如果入口点规则集不存在（也就是说，如果您在步骤 1 中收到了 404 Not Found 状态码），请使用 创建区域规则集 操作来创建它。在 rules 数组中包含单个规则，该规则针对 all incoming requests in the zone 执行 custom ruleset。Replace f82ccda3d21f4a02825d3fe45b5e1c10 with your custom ruleset ID.

   Required API token permissions

   At least one of the following token permissions is required:

   • Zone WAF Write

   curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets" \
   	--request POST \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   	--json '{
   		"name": "zone",
   		"description": "Zone-level phase entry point",
   		"kind": "zone",
   		"phase": "http_request_firewall_custom",
   		"rules": [
   				{
   						"action": "execute",
   						"action_parameters": {
   								"id": "f82ccda3d21f4a02825d3fe45b5e1c10"
   						},
   						"expression": "true",
   						"description": "Execute custom ruleset"
   				}
   		]
   	}'

使用 Rulesets API 中的不同操作来处理您创建并部署的自定义规则集。下表列出了在 zone 级别使用自定义规则集的常见任务：

有关通过 Cloudflare API 使用自定义规则集的更多信息，请参阅 Ruleset Engine 文档中的 Work with custom rulesets。