Cloudflare WAF 规则排障全指南:autoskills cloudflare-deploy 技能中的常见陷阱与规避方案
Cloudflare WAF 规则排障全指南:autoskills cloudflare-deploy 技能中的常见陷阱与规避方案
Cloudflare Web Application Firewall(WAF)通过自定义规则、托管规则集与速率限制三层防护拦截攻击,但错误的执行顺序认知、表达式语法、Skip 作用域或 update() 语义都会让配置"静默失效"甚至误伤业务。本文以 autoskills 仓库中 cloudflare-deploy 技能 的 WAF 参考资料为骨架,完整梳理 gotchas.md 中记录的九类高频故障——从阶段执行顺序、表达式报错到 NAT 误限速、配额上限——并给出可直接复制的 TypeScript SDK 修复代码。读完你将掌握:如何用正确的方式组织多阶段规则、如何写出合法且高效的 Wirefilter 表达式、如何安全地更新 ruleset 而不误删已有规则,以及如何把托管规则集 override 到恰到好处的"日志模式"。
一、文档定位:这份排障指南在技能体系中的位置
在 cloudflare-deploy 这个整合技能中,安全类需求的决策树指向 WAF:Web Application Firewall → waf/。WAF 参考资料目录共五份文件,形成完整的阅读链路:
- api.md —— SDK 方法、表达式语法、动作与阶段;
- configuration.md —— Wrangler / Terraform / Pulumi / 控制台配置;
- patterns.md —— 部署托管规则集、速率限制、Skip、Override 的常见组合;
- gotchas.md(本文主体)—— 执行顺序、限制、表达式错误等排障要点。
本文即是对 gotchas.md 的逐节展开,并交叉引用其余三份文件与相关测试场景,帮助开发者在"能跑通"和"跑得对"之间补齐最后一块拼图。
二、执行顺序:三个阶段是硬编码的,混用动作必然翻车
问题现象:规则按意外顺序执行。 根因:对阶段(Phase)执行顺序的误解。Cloudflare Ruleset Engine 的阶段是顺序执行且不可更改的:
http_request_firewall_custom—— 自定义规则(第一道防线);http_request_firewall_managed—— 托管规则集(Cloudflare Managed、OWASP CRS、Exposed Credentials 等);http_ratelimit—— 速率限制。
补充:在 api.md 中还可看到第 4 个阶段
http_request_sbfm(Super Bot Fight Mode,Pro 及以上套餐可用)。它会排在速率限制之后执行。
阶段内的执行语义:从上到下逐条匹配,首个匹配即命中(first match wins),除非遇到 skip 动作提前跳出。
最常见的错误是把不同阶段的动作塞进同一个 ruleset,例如在自定义规则阶段里混入 execute(该动作只属于托管阶段):
// WRONG: 不能混用阶段专属动作
await client.rulesets.create({
phase: 'http_request_firewall_custom',
rules: [
{ action: 'block', expression: 'cf.waf.score gt 50' },
{ action: 'execute', action_parameters: { id: 'managed_id' } }, // WRONG
],
});
// CORRECT: 每个阶段一个独立 ruleset
await client.rulesets.create({ phase: 'http_request_firewall_custom', rules: [...] });
await client.rulesets.create({ phase: 'http_request_firewall_managed', rules: [...] });
动作与阶段的兼容关系在 api.md 中有完整矩阵:block / challenge / js_challenge / managed_challenge / log 可用于自定义与限速阶段,skip 仅用于自定义阶段,execute 仅用于托管阶段。部署前先对照此表,可避免绝大多数 "Action not supported" 报错。
三、表达式错误:字段、引号、大小写与正则的四大坑
问题现象:表达式语法错误导致部署失败。 根因:字段名错误、字符串未加引号、大小写敏感、正则不合法。
// 常见错误与修正
'http.request.path' → 'http.request.uri.path' // Correct field
'ip.geoip.country eq US' → 'ip.geoip.country eq "US"' // Quote strings
'http.user_agent eq "Mozilla"' → 'lower(http.user_agent) contains "mozilla"' // Case sensitivity
'matches ".*[.jpg"' → 'matches ".*\\.jpg$"' // Valid regex
要点拆解:
- 字段名:正确路径是
http.request.uri.path,不存在http.request.path这个字段;api.md 的字段清单还给出了http.request.method、http.host、ip.src、ip.geoip.country、cf.waf.score及其子分数(cf.waf.score.sqli、cf.waf.score.xss)、请求头与 Cookie 的取值写法(如http.request.headers["authorization"][0]); - 字符串必须加双引号:
eq US会被解析为字段而非字面量; - 大小写敏感:
eq "Mozilla"无法匹配"mozilla",需要先lower(...)再contains; - 正则转义:
matches使用的正则中,.需要\\.转义,并以$锚定结尾。
官方建议的验证手段:在正式部署前,先到控制台的 Security Events 中用真实流量测试表达式(该建议同时出现在 configuration.md 与 gotchas.md 中)。表达式若解析失败,API 会直接返回 "Expression parse error"(见下文 API 错误一节)。
四、Skip 规则陷阱:ruleset: 'current' 与 phases 的作用域天差地别
问题现象:Skip 规则没有按预期放行流量。 根因:混淆了 Skip 的两种作用范围。
Skip 动作有两种目标:
ruleset: 'current'—— 仅跳过当前 ruleset 内剩余的规则;phases: ['phase_name']—— 整体跳过指定的一个或多个阶段。
// WRONG: 想在自定义阶段跳过托管规则(做不到)
// 这段代码位于 http_request_firewall_custom 阶段:
{
action: 'skip',
action_parameters: { ruleset: 'current' },
expression: 'ip.src in {192.0.2.0/24}',
}
// 它只会跳过后续的自定义规则,托管规则集照样执行
// CORRECT: 用 phases 显式跳过对应阶段
{
action: 'skip',
action_parameters: {
phases: ['http_request_firewall_managed', 'http_ratelimit'],
},
expression: 'ip.src in {192.0.2.0/24}',
}
方向性约束(api.md 明确给出):由于执行顺序固定,自定义阶段的 Skip 可以跳过托管/限速阶段,反之则不行——托管阶段执行时自定义阶段早已结束,无法回退跳过。这正是"为可信 IP(如办公网段 192.0.2.0/24)放行全部 WAF 检查"的标准姿势:patterns.md 的完整示例中,第一条自定义规则即用 phases 跳过托管与限速两个阶段,随后才进入攻击分拦截逻辑。
五、update() 会整体替换规则列表:先 get 再 update
问题现象:更新一次 ruleset,其他规则神秘消失。
根因:client.rulesets.update() 的语义是用传入的 rules 数组整体替换该 ruleset 的全部规则,而非追加。
// WRONG: 这条 update 会删掉 ruleset 里所有既有规则!
await client.rulesets.update({
zone_id: 'zone_id',
ruleset_id: 'ruleset_id',
rules: [{ action: 'block', expression: 'cf.waf.score gt 50' }],
});
// CORRECT: 先取回现有规则,再在末尾追加新规则
const ruleset = await client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' });
await client.rulesets.update({
zone_id: 'zone_id',
ruleset_id: 'ruleset_id',
rules: [...ruleset.rules, { action: 'block', expression: 'cf.waf.score gt 50' }],
});
结合 api.md 的说明:update() 时保留既有规则要带上它们的 id,新增规则则省略 id(Cloudflare 会为无 id 的规则生成新 id)。因此安全更新套路是 list/get 出当前规则 → 保留原 id 与动作 → 拼接新规则 → update。同理,"Ruleset already exists" 报错的正确应对也是先 list 该阶段已有 ruleset,存在则改走 update,不存在才 create(见第八节 API 错误)。
六、Override 冲突:规则 ID 与分类名必须精确
问题现象:托管规则集的 override 不生效。 根因:引用了不存在的规则 ID,或分类名拼写错误。
托管规则集(如 Cloudflare Managed,ID efb7b8c949ac4650a09736fc376e9aee)内部的每条规则都有稳定 ID。修改前先取回规则清单,打印 ID 与描述以便核对:
// 列出托管规则集的规则,找到真实 ID
const ruleset = await client.rulesets.get({
zone_id: 'zone_id',
ruleset_id: 'efb7b8c949ac4650a09736fc376e9aee',
});
console.log(ruleset.rules.map(r => ({ id: r.id, description: r.description })));
// 用正确 ID 配置 override
{ action: 'execute', action_parameters: { id: 'efb7b8c949ac4650a09736fc376e9aee',
overrides: { rules: [{ id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log' }] } } }
两类 override 对象(patterns.md 给出了完整示例):
- rules 级:按规则 ID 精确调整,如把
5de7edfa648c4d6891dc3e7f84534ffa改为log,或把75a0060762034b9dad4e883afc121b4c设为enabled: false; - categories 级:按分类整体调整,可用分类包括
wordpress、sqli、xss、rce等,例如{ category: 'wordpress', enabled: false }或{ category: 'sqli', action: 'log' }。
值得注意的是,同一个规则 ID 5de7edfa648c4d6891dc3e7f84534ffa 在 configuration.md 的 Terraform 示例中同样被用于 override——它是 Cloudflare Managed 规则集中一条可复用的真实规则,说明这些 ID 是跨工具(SDK / Terraform / Pulumi)一致的稳定标识。写 override 前务必先 get 一次确认 ID 存在,是避免"静默不生效"的最短路径。
七、误报处理:从 log 模式起步,分三步收敛
问题现象:合法流量被 WAF 拦截。 根因:规则或阈值过于激进。
推荐的灰度流程:
- 先用日志模式观察:
overrides: { action: 'log' }(对托管规则集整体降级为只记录); - 在 Security Events 中复盘被拦流量,识别误报来源;
- 仅对具体规则降级:
overrides: { rules: [{ id: 'rule_id', action: 'log' }] }。
这与 patterns.md 的自定义规则分层思路一脉相承:攻击分 gt 50 直接 block,gt 20 用 managed_challenge(智能挑战)而非硬拦截,攻击分又进一步细分 cf.waf.score.sqli / cf.waf.score.xss 定向处理。"先 log、后 block、逐规则收敛" 是生产环境变更 WAF 的安全基线。
八、NAT 场景的速率限制:别让一个出口 IP 误伤整栋楼
问题现象:NAT 后面的真实用户很快触发限速。
根因:多个用户共享同一出口 IP,ip.src 无法区分个体。
解决方案是增加限速特征(characteristics),用 User-Agent、会话 Cookie 或授权头进一步区分用户:
{
action: 'block',
expression: 'http.request.uri.path starts_with "/api"',
action_parameters: {
ratelimit: {
characteristics: ['cf.colo.id', 'ip.src', 'http.request.cookies["session"][0]'],
period: 60,
requests_per_period: 100,
},
},
}
关于 characteristics 的参数语义(api.md 有完整注释):
characteristics:定义"唯一性"的维度,可取ip.src、cf.colo.id、http.request.headers["key"][0]、http.request.cookies["session"][0];推荐组合['cf.colo.id', 'ip.src'](按数据中心 × IP 计数);period:时间窗口(秒);requests_per_period:窗口内最大请求数;mitigation_timeout:封禁持续时长(秒);counting_expression(可选):只统计满足条件的请求,例如'http.request.method ne "GET"'仅对非 GET 请求计数;requests_to_origin:为false时统计全部请求而非仅回源请求。
需要警惕的是:可用的 characteristics 数量受套餐配额限制(详见第十节:Free 2 个、Pro/Business 3 个、Enterprise 5 个)。若在 Free 套餐上配置 3 个特征,接口会直接报错。典型生产示例见 patterns.md:全局按 cf.colo.id + ip.src 限 100 次/分钟,登录端点 /api/login 单独按 ip.src 收紧到 5 次/分钟并带 mitigation_timeout: 600。
九、性能问题:表达式复杂度直接转化为延迟
问题现象:接入 WAF 后延迟上升。 根因:表达式过于复杂、规则数量过多。
性能优化清单:
- 尽早跳过静态资源:为
\\.(jpg|css|js)$配置action: 'skip',让图片、样式、脚本绕过后续全部检查; - 按路径部署托管规则:把
execute的 expression 从'true'收窄到'http.request.uri.path starts_with "/api"'或/admin,避免对全站所有请求跑完整规则集; - 关闭用不到的分类:
{ category: 'wordpress', enabled: false }——如果站点不是 WordPress,就该关掉该分类以省下匹配开销; - 优先用字符串运算符而非正则:
starts_with/ends_with/contains比matches快得多,matches只在必要时使用。
配套的求值语义(gotchas.md 的 Important Notes 明确列出,务必记住):
- 规则按序执行,首个命中即生效(Skip 除外);
- AND 链中首个
false即短路,后续条件不再求值——把廉价条件写在前面、昂贵条件(如正则、lower())写在后面,可以显著减少求值成本; matches正则运算符比字符串运算符慢;- 速率限制的计数发生在缓解动作之前——即使最终命中
block,这一请求也已计入窗口统计。
十、限额与配额:不同套餐的天花板对照表
在 configuration.md 中可以看到,WAF 是 zone 级别的配置(非 Worker 级别),因此配额按站点套餐生效。gotchas.md 给出的官方限额对照如下:
| 资源 | Free | Pro | Business | Enterprise |
|---|---|---|---|---|
| 自定义规则数 | 5 | 20 | 100 | 1000 |
| 速率限制规则数 | 1 | 10 | 25 | 100 |
| 规则表达式长度 | 4096 字符 | 4096 字符 | 4096 字符 | 4096 字符 |
| 每个 ruleset 的规则数 | 75 | 75 | 400 | 1000 |
| 托管规则集 | 支持 | 支持 | 支持 | 支持 |
| 限速 characteristics 数 | 2 | 3 | 5 | 5 |
这些数字直接影响方案设计:例如 Free 套餐只有 1 条限速规则与 2 个特征,那么第八节的"加 Cookie 特征"方案在 Free 上就不可行,必须依赖托管规则集 + 少量自定义规则兜底;而 Enterprise 的 1000 条自定义规则则允许按业务路径精细化拆解。patterns.md 的"完整配置示例"正是按"自定义 → 托管 → 限速"三个阶段各建一个 ruleset 的组合拳,可作为套餐内配额分配的参考基线。
十一、API 错误速查:从报错信息反推修复动作
问题现象:API 调用返回难以理解的错误。 根因:参数非法或权限不足。
gotchas.md 给出了四类高频报错及对应解法:
// Error: "Invalid phase" → 使用精确的阶段名
phase: 'http_request_firewall_custom'
// Error: "Ruleset already exists" → 改用 update(),或先 list 再决定
const rulesets = await client.rulesets.list({ zone_id, phase: 'http_request_firewall_custom' });
if (rulesets.result.length > 0) {
await client.rulesets.update({ zone_id, ruleset_id: rulesets.result[0].id, rules: [...] });
}
// Error: "Action not supported" → 检查阶段与动作的兼容性
// 'execute' 只出现在 http_request_firewall_managed
// 限速配置只出现在 http_ratelimit 阶段
// Error: "Expression parse error" → 常见修复:
'ip.geoip.country eq "US"' // 字符串加引号
'cf.waf.score gt 40' // 用 'gt' 而不是 '>'
'http.request.uri.path' // 不是 'http.request.path'
权限前置条件(configuration.md):调用这些 API 前,API Token 需具备 Zone.WAF Edit 或 Zone.Firewall Services Edit 权限,Zone Resources 指定目标 zone 或全部 zone;Zone ID 可在控制台 Overview 右侧 API 区找到。若是在 Worker 内直接调 WAF API,参考 configuration.md 中通过 fetch 访问 https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets 的写法,把 Token 存进 env.CF_API_TOKEN 而非硬编码。
最后再强调一遍全篇通用的一条黄金建议:任何表达式在部署前,先到控制台 Security Events 中用真实流量验证一遍("Test expressions in dashboard Security Events before deploying")。这条建议在本技能的五份 WAF 文档中反复出现,是规避本文绝大多数"配置了但没生效"问题的第一道防线。
延伸阅读(同一技能目录内)
- WAF 总览与托管规则集速查表(三个托管规则集的官方 ID 与覆盖范围)
- SDK 方法与表达式语法参考(字段、运算符、动作×阶段矩阵、限速参数全注释)
- Terraform / Pulumi / 控制台 / Wrangler 配置方式
- 常见组合模式:完整三阶段示例
- cloudflare-deploy 技能总入口(含安全类决策树)