Cloudflare WAF 规则排障全指南:autoskills cloudflare-deploy 技能中的常见陷阱与规避方案

原创2026-10-09 15:07:202,231 阅读

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 参考资料目录共五份文件,形成完整的阅读链路:

  1. api.md —— SDK 方法、表达式语法、动作与阶段;
  2. configuration.md —— Wrangler / Terraform / Pulumi / 控制台配置;
  3. patterns.md —— 部署托管规则集、速率限制、Skip、Override 的常见组合;
  4. gotchas.md(本文主体)—— 执行顺序、限制、表达式错误等排障要点。

本文即是对 gotchas.md 的逐节展开,并交叉引用其余三份文件与相关测试场景,帮助开发者在"能跑通"和"跑得对"之间补齐最后一块拼图。

二、执行顺序:三个阶段是硬编码的,混用动作必然翻车

问题现象:规则按意外顺序执行。 根因:对阶段(Phase)执行顺序的误解。Cloudflare Ruleset Engine 的阶段是顺序执行且不可更改的:

  1. http_request_firewall_custom —— 自定义规则(第一道防线);
  2. http_request_firewall_managed —— 托管规则集(Cloudflare Managed、OWASP CRS、Exposed Credentials 等);
  3. 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 拦截。 根因:规则或阈值过于激进。

推荐的灰度流程:

  1. 先用日志模式观察:overrides: { action: 'log' }(对托管规则集整体降级为只记录);
  2. 在 Security Events 中复盘被拦流量,识别误报来源;
  3. 仅对具体规则降级: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 后延迟上升。 根因:表达式过于复杂、规则数量过多。

性能优化清单:

  1. 尽早跳过静态资源:为 \\.(jpg|css|js)$ 配置 action: 'skip',让图片、样式、脚本绕过后续全部检查;
  2. 按路径部署托管规则:把 execute 的 expression 从 'true' 收窄到 'http.request.uri.path starts_with "/api"' 或 /admin,避免对全站所有请求跑完整规则集;
  3. 关闭用不到的分类:{ category: 'wordpress', enabled: false }——如果站点不是 WordPress,就该关掉该分类以省下匹配开销;
  4. 优先用字符串运算符而非正则: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 文档中反复出现,是规避本文绝大多数"配置了但没生效"问题的第一道防线。


延伸阅读(同一技能目录内)

登录后查看全文
autoskills