Cloudflare DDoS 防护配置完全指南：Dashboard、Ruleset 覆盖与 Adaptive DDoS 实战（skills4/skills 精选参考）

Cloudflare DDoS 防护配置完全指南：Dashboard、Ruleset 覆盖与 Adaptive DDoS 实战（skills4/skills 精选参考）

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills

本篇指南系统讲解 Cloudflare DDoS 防护的完整配置方法，涵盖 Dashboard 界面操作路径、基于 Ruleset 的覆盖（Override）规则结构、敏感度与动作映射、表达式套餐限制、Adaptive DDoS 自适应防护以及告警配置。读完本文，你将掌握从 Web 控制台到 TypeScript SDK / REST API 的全链路配置能力，能够按攻击类别与规则粒度精确调优，并能借助本文配套的调优策略与错误码对照表快速排障。本文主体整理自仓库中的 DDoS 配置文档，并融合了 DDoS API 文档、DDoS 常见问题 与 DDoS 防护模式 的实战细节，供部署与运维 Cloudflare 站点的开发者直接引用。

一、先理解防护体系：L7 与 L3/4 的两条主线

在动手配置之前，需要先明确 Cloudflare DDoS 防护的两个层面（详见 DDoS 模块 README）：

• HTTP DDoS（L7）：保护 HTTP/HTTPS 流量，对应 Ruleset 阶段（phase）ddos_l7，支持 zone 级与 account 级配置；
• Network DDoS（L3/4）：防护 UDP/SYN/DNS 等网络层洪水，对应 phaseddos_l4，仅支持 account 级配置；
• Adaptive DDoS：以 7 天流量为基线学习，自动检测偏差，提供 Origins、User-Agents、Locations、Protocols 四种画像（Profile）类型。

套餐可用性是配置的硬约束，下表来自仓库文档，请据此判断你的账号能使用哪些能力：

功能	Free	Pro	Business	Enterprise	Enterprise Advanced
HTTP DDoS（L7）	✓	✓	✓	✓	✓
Network DDoS（L3/4）	✓	✓	✓	✓	✓
Override 规则数	1	1	1	1	10
自定义表达式	✗	✗	✗	✗	✓
log 动作	✗	✗	✗	✗	✓
Adaptive DDoS	✗	✗	✗	✓	✓
告警过滤器	Basic	Basic	Basic	Advanced	Advanced

关键动作与敏感度速览：动作包括block、managed_challenge、challenge、log（log仅 Enterprise Advanced）；敏感度包括default（High）、medium、low、eoff（Essentially Off）；覆盖粒度可按 category/tag 或具体规则 ID；zone 级覆盖优先级高于 account 级。

二、Dashboard 配置路径：五步完成基础防护

若你是首次配置 DDoS 防护，官方推荐的 Web 控制台操作路径如下：

1. 导航至Security > DDoS；
2. 选择HTTP DDoS或Network-layer DDoS；
3. 按 ruleset / category / rule 三个粒度分别配置敏感度（sensitivity）与动作（action）；
4. 应用覆盖（override），可附带可选表达式（仅 Enterprise Advanced 支持自定义表达式）；
5. 开启Adaptive DDoS开关（仅 Enterprise / Enterprise Advanced，要求已积累 7 天流量历史）。

控制台操作的本质，是对托管规则集（Managed Ruleset）施加"覆盖"：你不直接改写 Cloudflare 内置的 DDoS 规则，而是通过 override 调整其敏感度与动作。这也是后续所有 API 化配置的核心思想。

三、Override 规则结构：DDoSOverride 逐字段拆解

无论使用控制台还是 API，覆盖规则都遵循同一个结构。仓库文档给出了完整的 TypeScript 类型定义：

interface DDoSOverride { description: string; rules: Array<{ action: "execute"; expression: string; // Custom expression (Enterprise Advanced) or "true" for all action_parameters: { id: string; // Managed ruleset ID (discover via api.md) overrides: { sensitivity_level?: "default" | "medium" | "low" | "eoff"; action?: "block" | "managed_challenge" | "challenge" | "log"; // log = Enterprise Advanced only categories?: Array<{ category: string; // e.g., "http-flood", "udp-flood" sensitivity_level?: string; }>; rules?: Array<{ id: string; action?: string; sensitivity_level?: string; }>; }; }; }>; }

字段语义要点：

• rules[].action固定为"execute"——覆盖规则的动作是"执行某个托管规则集"，真正的放行/拦截动作在overrides里定义；
• rules[].expression：命中条件。普通套餐只能使用"true"（全流量），Enterprise Advanced 可写复杂表达式（详见下节）；
• action_parameters.id：目标托管规则集的 ID。该 ID 需要通过 API 发现流程 获取，不能凭空猜测（具体发现代码见本文第六节）；
• overrides支持三级覆盖：全局sensitivity_level/action、按categories批量覆盖、按rules单条覆盖，三者的优先级关系见第五节。

四、表达式可用性：决定你能写到多细

自定义表达式是 DDoS 覆盖规则中差异化最大的能力，仓库文档的对照表如下：

套餐	自定义表达式	示例
Free/Pro/Business	✗	只能使用"true"
Enterprise	✗	只能使用"true"
Enterprise Advanced	✓	ip.src in {...}、http.request.uri.path matches "..."

注意：即使是 Enterprise 套餐，DDoS 覆盖的自定义表达式同样不可用，只有 Enterprise Advanced 支持。这意味着：

• 普通套餐只能对"全流量"施加统一覆盖，细化到路由或来源 IP 的差异化防护必须依赖 Enterprise Advanced；
• 当遇到 "Expression not allowed"（错误码 81020）时，不必怀疑语法，先确认套餐等级。

五、敏感度映射与覆盖优先级

5.1 敏感度：UI 与 API 的对应关系

控制台里看到的"高/中/低/几乎关闭"，在 API 层面对应如下（来自仓库文档）：

UI	API	阈值
High	default	Most aggressive（最激进，误报风险最高）
Medium	medium	Balanced（均衡）
Low	low	Less aggressive（较温和）
Essentially Off	eoff	Minimal mitigation（仅保留最小缓解）

eoff不是"关闭防护"——Cloudflare DDoS 托管规则集属于**始终在线（always-on）**防护，无法完全禁用，eoff只是把缓解力度降到最低（详见 gotchas.md 的 "Cannot disable DDoS protection" 条目）。

5.2 常见规则类别

覆盖既可按"类别"批量调整，也可按"单条规则"精确调整。常见类别如下：

• L7（应用层）：http-flood、http-anomaly；
• L3/4（网络层）：udp-flood、syn-flood、dns-flood。

5.3 覆盖优先级：多层规则如何裁决

当多个覆盖层同时存在时，按以下顺序生效（高优先级者胜出）：

Zone-level > Account-level Individual Rule > Category > Global sensitivity/action

示例：对/api/*路径配置的 zone 级规则，会覆盖 account 级的全局设置。若你发现"zone 覆盖被忽略"，多半是 account 级配置与之冲突——仓库建议要么统一在 zone 级配置，要么移除 zone 覆盖改走 account 级（详见 gotchas.md）。

六、Adaptive DDoS 自适应防护：四类画像与配置方式

可用性：Enterprise、Enterprise Advanced学习期：需要 7 天的流量历史作为基线

画像类型	说明	检测目标
Origins	按源站服务器统计流量模式	针对特定源站的异常请求
User-Agents	按 User-Agent 统计流量模式	恶意/异常的 UA 字符串
Locations	按地理位置统计流量模式	来自特定国家/地区的攻击
Protocols	按协议统计流量模式（L3/4）	特定协议的洪水攻击

配置方式：通过 API 定位特定的 adaptive 规则 ID，再对其施加覆盖（如把某个 adaptive 规则的敏感度降为low）。具体示例见 api.md 的 typed-override-examples 章节。

如果 adaptive 规则"不生效"，最可能的原因是流量历史不足 7 天——先等待基线建立完成，再到 Dashboard 查看 adaptive 规则状态（见 gotchas.md）。

七、告警配置：Alerting 与通知机制

通过 Notifications 配置 DDoS 攻击告警：

• 告警类型：http_ddos_attack_alert、layer_3_4_ddos_attack_alert，以及对应的advanced_*变体（如advanced_http_ddos_attack_alert、advanced_layer_3_4_ddos_attack_alert）；
• 过滤器：zones、hostnames、RPS/PPS/Mbps 阈值、IP、协议；
• 通知机制：email、webhooks、PagerDuty。

告警的 API 化配置（含完整请求结构）见 api.md 的 alert-configuration 章节，其核心类型如下：

interface DDoSAlertConfig { name: string; enabled: boolean; alert_type: "http_ddos_attack_alert" | "layer_3_4_ddos_attack_alert" | "advanced_http_ddos_attack_alert" | "advanced_layer_3_4_ddos_attack_alert"; filters?: { zones?: string[]; hostnames?: string[]; requests_per_second?: number; packets_per_second?: number; megabits_per_second?: number; ip_prefixes?: string[]; // CIDR ip_addresses?: string[]; protocols?: string[]; }; mechanisms: { email?: Array<{ id: string }>; webhooks?: Array<{ id: string }>; pagerduty?: Array<{ id: string }>; }; }

八、API 与 TypeScript SDK 编程化配置

控制台操作适合人工调优，而自动化、可审计的配置应走 API。仓库 api.md 提供了完整的端点与 SDK 用法。

8.1 REST 端点

HTTP DDoS（L7）：

// Zone-level PUT /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint GET /zones/{zoneId}/rulesets/phases/ddos_l7/entrypoint // Account-level (Enterprise Advanced) PUT /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint GET /accounts/{accountId}/rulesets/phases/ddos_l7/entrypoint

Network DDoS（L3/4，仅 account 级）：

// Account-level only PUT /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint GET /accounts/{accountId}/rulesets/phases/ddos_l4/entrypoint

8.2 SDK 三步走：发现 ID → 读取现状 → 应用覆盖

使用 TypeScript SDK 配置需要cloudflare包版本>= 3.0.0（该版本起才提供 ruleset phase 方法）：

import Cloudflare from "cloudflare"; const client = new Cloudflare({ apiToken: process.env.CLOUDFLARE_API_TOKEN }); // STEP 1: Discover managed ruleset ID (required for overrides) const allRulesets = await client.rulesets.list({ zone_id: zoneId }); const ddosRuleset = allRulesets.result.find( (r) => r.kind === "managed" && r.phase === "ddos_l7" ); if (!ddosRuleset) throw new Error("DDoS managed ruleset not found"); const managedRulesetId = ddosRuleset.id; // STEP 2: Get current HTTP DDoS configuration const entrypointRuleset = await client.zones.rulesets.phases.entrypoint.get("ddos_l7", { zone_id: zoneId, }); // STEP 3: Update HTTP DDoS ruleset with overrides await client.zones.rulesets.phases.entrypoint.update("ddos_l7", { zone_id: zoneId, rules: [ { action: "execute", expression: "true", action_parameters: { id: managedRulesetId, // From discovery step overrides: { sensitivity_level: "medium", action: "managed_challenge", }, }, }, ], }); // Network DDoS (account level, L3/4) const l4Rulesets = await client.rulesets.list({ account_id: accountId }); const l4DdosRuleset = l4Rulesets.result.find( (r) => r.kind === "managed" && r.phase === "ddos_l4" ); const l4Ruleset = await client.accounts.rulesets.phases.entrypoint.get("ddos_l4", { account_id: accountId, });

"Managed ruleset not found" 是最常见的报错之一，排查方向是：确认 zone/account 上确实存在 DDoS 托管规则集，并核对 phase 名称是ddos_l7还是ddos_l4（见 gotchas.md）。

8.3 更细的覆盖：按类别或按规则 ID

按类别批量覆盖：

interface CategoryOverride { action: "execute"; expression: string; action_parameters: { id: string; overrides: { categories?: Array<{ category: "http-flood" | "http-anomaly" | "udp-flood" | "syn-flood"; sensitivity_level?: "default" | "medium" | "low" | "eoff"; action?: "block" | "managed_challenge" | "challenge" | "log"; }>; }; }; }

按单条规则 ID 覆盖：

interface RuleOverride { action: "execute"; expression: string; action_parameters: { id: string; overrides: { rules?: Array<{ id: string; action?: "block" | "managed_challenge" | "challenge" | "log"; sensitivity_level?: "default" | "medium" | "low" | "eoff"; }>; }; }; } // Example: Override specific adaptive rule const adaptiveOverride: RuleOverride = { action: "execute", expression: "true", action_parameters: { id: managedRulesetId, overrides: { rules: [ { id: "...adaptive-origins-rule-id...", sensitivity_level: "low" }, ], }, }, };

8.4 创建告警策略（REST 直调）

await fetch( `https://api.cloudflare.com/client/v4/accounts/${accountId}/alerting/v3/policies`, { method: "POST", headers: { Authorization: `Bearer ${apiToken}`, "Content-Type": "application/json", }, body: JSON.stringify(alertConfig), } );

九、高频错误、错误码与配额速查

仓库 gotchas.md 整理了最常见的排障场景，摘录如下：

现象	根因	解决方向
误杀正常流量	敏感度过高、动作过强或缺少例外	降低特定规则/类别的敏感度；先用log动作验证；用自定义表达式加例外（如 IP 白名单）；用 GraphQL Analytics API 分析被标记请求
攻击仍能穿透	敏感度过低或动作过弱	提升到default敏感度并使用block动作
Adaptive 规则不生效	流量历史不足 7 天	等待基线建立，检查 Dashboard 中 adaptive 规则状态
Zone 覆盖被忽略	与 account 级覆盖冲突	统一在 zone 级配置，或移除 zone 覆盖改用 account 级
log 动作不可用	非 Enterprise Advanced 套餐	测试期改用managed_challenge+low敏感度
覆盖规则数超限	Free/Pro/Business 限 1 条、Enterprise Advanced 限 10 条	用and/or合并条件到单条表达式
无法覆盖某规则	该规则为只读	检查 API 响应中的只读标识，改选其他规则
无法关闭 DDoS 防护	托管规则集始终在线，不可完全禁用	将敏感度设为eoff以最小化缓解
表达式不被允许	自定义表达式仅限 Enterprise Advanced	改用"true"或升级套餐

API 层面对应的错误码：

错误码	含义	解决方向
10000	认证失败	检查 API token 是否具备 DDoS 权限
81000	Ruleset 校验失败	确认action_parameters.id是托管规则集 ID
81020	表达式不被允许	使用"true"或升级至 Enterprise Advanced
81021	规则数超限	精简规则或升级（Enterprise Advanced 上限 10）
81022	敏感度非法	仅可使用default/medium/low/eoff
81023	动作非法	log动作仅 Enterprise Advanced 可用

配额总览（来自 gotchas.md）：

资源/限制	Free/Pro/Business	Enterprise	Enterprise Advanced
每 zone 覆盖规则数	1	1	10
自定义表达式	✗	✗	✓
log 动作	✗	✗	✓
Adaptive DDoS	✗	✓	✓
所需流量历史	-	7 天	7 天

十、调优策略与最佳实践

仓库给出的渐进式调优路线（适用于生产环境平滑升级）：

1. 以log动作 +medium敏感度起步（先观察、不拦截）；
2. 持续监控 24–48 小时；
3. 识别误报并补充例外；
4. 逐步提升到default敏感度；
5. 动作按log→managed_challenge→block的顺序递进；
6. 记录所有调整以便回滚与复盘。

最佳实践清单：

• 在低流量时段测试规则变更；
• 优先使用 zone 级配置做按站点调优；
• 借助 IP 列表（Reference Lists）简化管理；
• 设置合理的告警阈值，避免告警噪音；
• 与 WAF 组合实现纵深防御；
• 避免过度调优，保持配置简洁。

十一、进阶模式速览

若需要更完整的实现模板，仓库 patterns.md 提供了可直接落地的场景代码，包括：

• 可信 IP 白名单：对ip.src in {...}命中流量施加eoff敏感度；
• 路由差异化敏感度：/api/*用低敏感度 +managed_challenge，其余路径用default+block；
• 渐进式防护等级：用MONITORING → LOW → MEDIUM → HIGH枚举封装setProtectionLevel()函数；
• 攻击动态响应：通过 Worker + KV 记录攻击事件，连续攻击超过阈值自动提升防护等级、流量恢复后回落；
• 多规则分级防护（Enterprise Advanced）：结合$known_ips、cf.bot_management.score、$trusted_ips实现多层覆盖；
• 纵深防御：DDoS + WAF + Rate Limiting + Bot Management 四层叠加，分别对应ddos_l7、http_request_firewall_managed、http_ratelimit、http_request_sbfm四个 phase；
• 缓存抗 DDoS：对/api/路径设置set_cache_settings并排除查询字符串，抵御随机 query 参数绕缓存的攻击。

相关阅读

• DDoS 模块 README（阅读顺序与总览）
• DDoS API 与 SDK 文档
• DDoS 常见问题与调优
• DDoS 防护模式示例
• 相关安全产品：WAF（应用层安全规则）、Bot Management（机器人检测与缓解）

【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills