企业官网建设流程全解析

Cloudflare Bot Management 实战指南：从 Bot Fight Mode 到 Enterprise 的多层级 Bot 防护与 Workers/WAF 集成

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

本指南以cloudflare-deployskill 中的 Bot Management 参考文档 为主线，系统讲解 Cloudflare Bot Management 的三层防护体系：Free 的 Bot Fight Mode、Pro/Business 的 Super Bot Fight Mode、以及 Enterprise 的精细化管理能力。读完本文，你将掌握 Bot Score 语义、WAF 规则模板、JavaScript Detections 配置、Workers 中request.cf.botManagement的编程式接入，以及真实场景下的防误杀调优方案，可直接应用于反爬、API 保护、电商风控等实战场景。

产品总览：Bot Management 的分层防护体系

Bot Management 是 Cloudflare 面向企业级流量的机器人检测、防护与缓解方案，核心依赖机器学习（ML）、启发式规则（Heuristics）、Bot Score 评分、JavaScript 检测以及已验证 Bot（Verified Bot）处理。它按套餐分为三个层级，对应不同的能力边界：

在 cloudflare-deploy skill 的安全决策树中，Bot Management 与 WAF、DDoS、API Shield、Turnstile 并列，用于"Bot 检测与管理"场景（见 SKILL.md）。

快速开始：两条最常用的规则模板

无论是通过仪表盘（Security > Bots）还是 Enterprise 规则模板，以下两条表达式是 Bot 防护的起点：

# 直接封禁确定型 Bot（score = 1 且非已验证 Bot） (cf.bot_management.score eq 1 and not cf.bot_management.verified_bot) → Block # 对疑似 Bot（score <= 29）下发托管质询 (cf.bot_management.score le 29 and not cf.bot_management.verified_bot) → Managed Challenge

核心原则是：先质询（Managed Challenge），后封禁（Block），并始终用not cf.bot_management.verified_bot排除已验证的良性 Bot。

阅读路径：按任务定位所需文档

关联参考是一组相互协作的文档，不同任务对应不同文件（以下链接均已转换为仓库根目录相对路径）：

├─ 初始配置 → configuration.md │ ├─ Free 套餐 → "Bot Fight Mode" │ ├─ Pro/Business → "Super Bot Fight Mode" │ └─ Enterprise → "Bot Management for Enterprise" ├─ Workers API 集成 → api.md ├─ WAF 规则 → patterns.md ├─ 问题排查 → gotchas.md └─ 分析 → api.md#bot-analytics

核心概念：Bot Score、检测引擎与已验证 Bot

Bot Score（Bot 分数）

• 取值范围1-99：1 代表"确定是自动化程序"，99 代表"基本确定是真人"。
• 阈值经验：分数 < 30 视为 Bot 流量。
• 套餐差异：Enterprise 可获得1-99 的粒度分数；Pro/Business 只能看到分组（groupings）。

四大检测引擎

Verified Bots（已验证 Bot）

已验证 Bot 是被 Cloudflare 反向 DNS 或 Web Bot Auth 验证过的良性白名单 Bot（搜索引擎、AI 爬虫等）。在规则中通过cf.bot_management.verified_bot或cf.verified_bot_category访问。验证方式详见 gotchas.md 的"Bot 验证方法"章节。

平台限制对照表

配置篇：三个套餐的完整开启方式

完整配置细节见 configuration.md。注意新旧两版仪表盘的路径差异：新版在 Security > Settings 搜索 "Bot traffic"，旧版在 Security > Bots，两者操作的是同一套设置。

Bot Score 分组语义（Pro/Business）

Pro/Business 用户看到的是分组而非 1-99 粒度分数：

Bot Fight Mode（Free）

• 自动封禁确定型 Bot（score=1），默认排除已验证 Bot；
• JavaScript Detections始终启用，无任何可配置项。

Super Bot Fight Mode（Pro/Business）

仪表盘：Security > Bots > Configure - Definitely automated（确定自动化）：Block / Challenge - Likely automated（可能自动化）：Challenge / Allow - Verified bots（已验证 Bot）：Allow（推荐） - Static resource protection（静态资源保护）：ON（注意可能拦截邮件客户端） - JavaScript Detections：可选

Bot Management for Enterprise

仪表盘：Security > Bots > Configure > Auto-updates：ON（推荐开启） # 模板 1：封禁确定型 Bot (cf.bot_management.score eq 1 and not cf.bot_management.verified_bot and not cf.bot_management.static_resource) Action: Block # 模板 2：质询疑似 Bot (cf.bot_management.score ge 2 and cf.bot_management.score le 29 and not cf.bot_management.verified_bot and not cf.bot_management.static_resource) Action: Managed Challenge

两个模板都排除了静态资源（static_resource），避免对图片、CSS、JS 等资源做无意义的质询。

JavaScript Detections（JSD）设置

方式一：仪表盘开启

Security > Bots > Configure Bot Management > JS Detections：ON 同时更新 CSP： script-src 'self' /cdn-cgi/challenge-platform/;

方式二：手动注入（API，用于按页面选择性部署）

<script> function jsdOnload() { window.cloudflare.jsd.executeOnce({ callback: function(result) { console.log('JSD:', result); } }); } </script> <script src="/cdn-cgi/challenge-platform/scripts/jsd/api.js?onload=jsdOnload" async></script>

API 方式的适用场景：仅在特定页面选择性部署。注意不要把"域名级开关"和"手动注入"叠加使用。

JSD 的 WAF 规则用法：

# 绝不能在首次页面访问时使用（需要先有 HTML 页面） (not cf.bot_management.js_detection.passed and http.request.uri.path eq "/api/user/create" and http.request.method eq "POST" and not cf.bot_management.verified_bot) Action: Managed Challenge（必须用 Managed Challenge，不能用 Block）

JSD 已知限制：

• 首次请求没有 JSD 数据（需要先加载 HTML 页面）；
• 会从 HTML 响应中剥离 ETag；
• 不支持通过<meta>标签配置 CSP；
• 不支持 WebSocket 端点；
• 原生移动 App 无法通过；
• cf_clearancecookie 生命周期 15 分钟，最大 4096 字节。

__cf_bm Cookie

Cloudflare 会设置__cf_bmcookie，用于平滑跨会话的 Bot Score：

• 目的：降低分数波动导致的误报；
• 范围：按域名（per-domain）、HTTP-only；
• 生命周期：会话时长；
• 隐私：不含 PII，仅含会话分类信息；
• 配置：全自动，无需任何配置。

重复访客的 Bot Score 会通过该 cookie 参考其会话历史。

静态资源保护（Static Resource Protection）

受保护的扩展名：ico, jpg, png, jpeg, gif, css, js, tif, tiff, bmp, pict, webp, svg, svgz, class, jar, txt, csv, doc, docx, xls, xlsx, pdf, ps, pls, ppt, pptx, ttf, otf, woff, woff2, eot, eps, ejs, swf, torrent, midi, mid, m3u8, m4a, mp3, ogg, ts，外加/.well-known/路径（全部文件）。

# 从 Bot 规则中排除静态资源 (cf.bot_management.score lt 30 and not cf.bot_management.static_resource)

警告：开启静态资源保护可能误拦截邮件客户端拉取静态图片。

JA3/JA4 指纹（Enterprise）

# 封禁特定攻击指纹 (cf.bot_management.ja3_hash eq "8b8e3d5e3e8b3d5e") # 按指纹放行移动 App (cf.bot_management.ja4 eq "your_mobile_app_fingerprint")

前置条件：仅对 HTTPS/TLS 流量可用；Worker 路由流量或 HTTP 请求中缺失。

Verified Bot 分类

# 只放行搜索引擎爬虫 (cf.verified_bot_category eq "Search Engine Crawler") # 封禁 AI 爬虫（训练型） (cf.verified_bot_category eq "AI Crawler") Action: Block # 或使用仪表盘：Security > Settings > Bot Management > Block AI Bots

常见分类字符串值：

配置最佳实践

• ML 自动更新：Enterprise 应开启，及时获取最新模型；
• 先 Managed Challenge 再 Block：上线前先用质询验证效果；
• 始终排除已验证 Bot：规则里加上not cf.bot_management.verified_bot；
• 豁免企业代理：B2B 流量可通过cf.bot_management.corporate_proxy豁免；
• 使用静态资源例外：提升性能、降低开销。

API 篇：Workers 中的 BotManagement 接口与 WAF 字段

详见 api.md。

Workers: BotManagement 接口

interface BotManagement { score: number; // 1-99（Enterprise），未计算时为 0 verifiedBot: boolean; // 是否为已验证 Bot staticResource: boolean; // 是否静态资源 ja3Hash: string; // JA3 指纹（Enterprise，仅 HTTPS） ja4: string; // JA4 指纹（Enterprise，仅 HTTPS） jsDetection?: { passed: boolean; // 是否通过 JS 检测（若已启用） }; detectionIds: number[]; // 启发式检测 ID corporateProxy?: boolean; // 是否来自企业代理（Enterprise） } // 已废弃：请使用 botManagement.score 替代 // request.cf.clientTrustScore（旧接口，是 botManagement.score 的副本） // 通过 request.cf 访问 import type { IncomingRequestCfProperties } from '@cloudflare/workers-types'; export default { async fetch(request: Request): Promise<Response> { const cf = request.cf as IncomingRequestCfProperties | undefined; const botMgmt = cf?.botManagement; if (!botMgmt) return fetch(request); if (botMgmt.verifiedBot) return fetch(request); // 放行已验证 Bot if (botMgmt.score === 1) return new Response('Blocked', { status: 403 }); if (botMgmt.score < 30) return new Response('Challenge required', { status: 429 }); return fetch(request); } };

WAF 字段参考

# 分数相关字段 cf.bot_management.score # 0-99（0 = 未计算） cf.bot_management.verified_bot # boolean cf.bot_management.static_resource # boolean cf.bot_management.ja3_hash # string（Enterprise） cf.bot_management.ja4 # string（Enterprise） cf.bot_management.detection_ids # array cf.bot_management.js_detection.passed # boolean cf.bot_management.corporate_proxy # boolean（Enterprise） cf.verified_bot_category # string # Workers 中的等价字段 request.cf.botManagement.score request.cf.botManagement.verifiedBot request.cf.botManagement.ja3Hash request.cf.botManagement.ja4 request.cf.botManagement.jsDetection.passed request.cf.verifiedBotCategory

JA4 Signals（Enterprise 高级信号）

request.cf.ja4Signals提供基于 JA4 的 1 小时窗口聚合信号，分为比率（0.0-1.0）、排名（分布中的相对位置）和分位数三类：

import type { IncomingRequestCfProperties } from '@cloudflare/workers-types'; interface JA4Signals { // 比率（0.0-1.0） heuristic_ratio_1h?: number; // 被启发式标记的比例 browser_ratio_1h?: number; // 来自真实浏览器的比例 cache_ratio_1h?: number; // 命中缓存的比例 h2h3_ratio_1h?: number; // 使用 HTTP/2 或 HTTP/3 的比例 // 排名 uas_rank_1h?: number; // User-Agent 多样性排名 paths_rank_1h?: number; // 路径多样性排名 reqs_rank_1h?: number; // 请求量排名 ips_rank_1h?: number; // IP 多样性排名 // 分位数（0.0-1.0） reqs_quantile_1h?: number; // 请求量分位数 ips_quantile_1h?: number; // IP 数量分位数 } export default { async fetch(request: Request): Promise<Response> { const cf = request.cf as IncomingRequestCfProperties | undefined; const ja4Signals = cf?.ja4Signals as JA4Signals | undefined; if (!ja4Signals) return fetch(request); // HTTP 或 Worker 路由场景不可用 // 检测异常行为：启发式标记比例过高或浏览器比例过低 = 可疑 const heuristicRatio = ja4Signals.heuristic_ratio_1h ?? 0; const browserRatio = ja4Signals.browser_ratio_1h ?? 0; if (heuristicRatio > 0.5 || browserRatio < 0.3) { return new Response('Suspicious traffic', { status: 403 }); } return fetch(request); } };

Bot Analytics（Bot 分析）

访问位置：仪表盘 Security > Bots（旧）或 Security > Analytics > Bot analysis（新）；GraphQL API 可编程访问；Security Events 与 Security Analytics；Logpush/Logpull。

可用数据：

• Enterprise BM：Bot Score（1-99）、分数来源、分布；
• Pro/Business：Bot 分组（automated / likely automated / likely human）；
• 顶部属性：IP、路径、User-Agent、国家；
• 检测来源：Heuristics、ML、AD（Anomaly Detection）、JSD；
• Verified Bot 分类。

时间范围：

• Enterprise BM：单次最多 1 周，历史 30 天；
• Pro/Business：单次最多 72 小时，历史 30 天；
• 多数情况下实时，采样率自适应（按流量规模 1%-10%）。

Logpush 字段

BotScore # 1-99，未计算为 0 BotScoreSrc # 检测引擎（ML、Heuristics 等） BotTags # 分类标签 BotDetectionIDs # 启发式检测 ID

BotScoreSrc 取值：

可通过 Logpush（流式到云存储/SIEM）、Logpull（API 拉取日志）或 GraphQL API（查询分析数据）获取。

使用 Miniflare 本地测试

Miniflare 为本地开发提供 mock 的botManagement数据，默认值：

• score: 99（人类）
• verifiedBot: false
• corporateProxy: false
• ja3Hash: "25b4882c2bcb50cd6b469ff28c596742"
• staticResource: false
• detectionIds: []

测试中覆盖默认值：

import { getPlatformProxy } from 'wrangler'; const { cf, dispose } = await getPlatformProxy(); // cf.botManagement 是冻结的 mock 对象 expect(cf.botManagement.score).toBe(99);

如需自定义测试数据，可在测试环境中直接 mockrequest.cf。

实战模式篇：常见场景的规则与代码模板

完整模式库见 patterns.md。

电商防护（高安全级结算）

# 结算/加购路径：score < 50 即质询，同时排除企业代理 (cf.bot_management.score lt 50 and http.request.uri.path in {"/checkout" "/cart/add"} and not cf.bot_management.verified_bot and not cf.bot_management.corporate_proxy) Action: Managed Challenge

API 防护（JS 检测 + 分数）

# API 路径：分数 < 30 或未通过 JS 检测即封禁 (http.request.uri.path matches "^/api/" and (cf.bot_management.score lt 30 or not cf.bot_management.js_detection.passed) and not cf.bot_management.verified_bot) Action: Block

SEO 友好的 Bot 处理

# 对分数 < 30 但非搜索引擎爬虫的流量质询（保护 SEO 收录） (cf.bot_management.score lt 30 and not cf.verified_bot_category in {"Search Engine Crawler"}) Action: Managed Challenge

封禁 AI 爬虫

# 只封禁训练型爬虫（放行 AI 助手/搜索） (cf.verified_bot_category eq "AI Crawler") Action: Block # 封禁全部 AI 相关 Bot（训练 + 助手 + 搜索） (cf.verified_bot_category in {"AI Crawler" "AI Assistant" "AI Search"}) Action: Block # 封禁 AI Crawler 与 AI Assistant，放行 AI Search (cf.verified_bot_category in {"AI Crawler" "AI Assistant"}) Action: Block

也可直接使用仪表盘：Security > Settings > Bot Management > Block AI Bots。

按 Bot Score 分级限速

# 可疑流量更严格的限速 (cf.bot_management.score lt 50) Rate: 10 requests per 10 seconds # 正常流量更宽松的限速 (cf.bot_management.score ge 50) Rate: 100 requests per 10 seconds

移动 App 白名单（按 JA3/JA4 指纹）

# 识别移动 App 的 JA3/JA4 指纹并跳过后续所有规则 (cf.bot_management.ja4 in {"fingerprint1" "fingerprint2"}) Action: Skip (all remaining rules)

数据中心流量检测（Workers）

import type { IncomingRequestCfProperties } from '@cloudflare/workers-types'; // 低分数 + 非企业代理 = 大概率是数据中心 Bot export default { async fetch(request: Request): Promise<Response> { const cf = request.cf as IncomingRequestCfProperties | undefined; const botMgmt = cf?.botManagement; if (botMgmt?.score && botMgmt.score < 30 && !botMgmt.corporateProxy && !botMgmt.verifiedBot) { return new Response('Datacenter traffic blocked', { status: 403 }); } return fetch(request); } };

条件延迟（蜜罐/Tarpit）

import type { IncomingRequestCfProperties } from '@cloudflare/workers-types'; // 延迟与 Bot 可疑程度成正比 export default { async fetch(request: Request): Promise<Response> { const cf = request.cf as IncomingRequestCfProperties | undefined; const botMgmt = cf?.botManagement; if (botMgmt?.score && botMgmt.score < 50 && !botMgmt.verifiedBot) { // 延迟：分数 50-0 对应 0-2 秒 const delayMs = Math.max(0, (50 - botMgmt.score) * 40); await new Promise(r => setTimeout(r, delayMs)); } return fetch(request); } };

分层防御（Layered Defense）

1. Bot Management（基于分数的检测） 2. JavaScript Detections（面向支持 JS 的客户端） 3. Rate Limiting（兜底防护） 4. WAF Managed Rules（OWASP 等托管规则集）

渐进式增强（Progressive Enhancement）

公开内容：高阈值（score < 10） 已认证用户：中阈值（score < 30） 敏感操作：低阈值（score < 50）+ JSD

面向 Bot 的零信任（Zero Trust for Bots）

1. 默认拒绝（所有 score < 30） 2. 白名单放行已验证 Bot 3. 白名单移动 App（JA3/JA4） 4. 白名单企业代理 5. 白名单静态资源

Workers：分数 + JS 检测组合

import type { IncomingRequestCfProperties } from '@cloudflare/workers-types'; export default { async fetch(request: Request): Promise<Response> { const cf = request.cf as IncomingRequestCfProperties | undefined; const botMgmt = cf?.botManagement; const url = new URL(request.url); if (botMgmt?.staticResource) return fetch(request); // 跳过静态资源 // API 端点：要求通过 JS 检测且分数良好 if (url.pathname.startsWith('/api/')) { const jsDetectionPassed = botMgmt?.jsDetection?.passed ?? false; const score = botMgmt?.score ?? 100; if (!jsDetectionPassed || score < 30) { return new Response('Unauthorized', { status: 401 }); } } return fetch(request); } };

按 JWT Claim + Bot Score 限速（Enterprise）

Rate limiting > Custom rules - 字段：lookup_json_string(http.request.jwt.claims["{config_id}"][0], "sub") - 匹配：用户 ID claim - 附加条件：cf.bot_management.score lt 50

WAF 集成点汇总

• WAF Custom Rules：主要执行机制；
• Rate Limiting Rules：以 Bot Score 为维度，对低分流量限速更严格；
• Transform Rules：通过自定义 Header 把分数传给源站；
• Workers：编程式 Bot 逻辑、自定义评分算法；
• Page Rules / Configuration Rules：区域级覆盖、按路径定制设置。

排障篇：常见问题与限制（Gotchas）

详细排查手册见 gotchas.md。

常见错误速查

"Bot Score = 0"

• 原因：Bot Management 未运行——内部 Cloudflare 请求、Worker 路由到同域（Orange-to-Orange）、或在 Bot Management 之前被处理（如 Redirect Rules）。
• 解决：检查请求链路，确保 Bot Management 在请求生命周期中执行。

"JavaScript Detections 不工作"

• 原因：CSP 不允许/cdn-cgi/challenge-platform/；首次页面访问（需先有 HTML 页面）；广告拦截或禁用 JS；仪表盘未启用 JSD；使用了 Block 动作（必须用 Managed Challenge）。
• 解决：添加 CSP 头Content-Security-Policy: script-src 'self' /cdn-cgi/challenge-platform/;，并以 Managed Challenge 动作启用 JSD。

"误报（真实用户被拦截）"

• 原因：检测将合法用户误判为 Bot。
• 解决：在 Bot Analytics 中查看受影响 IP/路径，定位检测来源（ML、Heuristics 等），创建例外规则(cf.bot_management.score lt 30 and http.request.uri.path eq "/problematic-path")并执行Action: Skip (Bot Management)，或按 IP/ASN/国家白名单放行。

"漏报（Bot 未被拦截）"

• 原因：Bot 绕过检测。
• 解决：降低分数阈值（30 → 50）、启用 JavaScript Detections、增加 JA3/JA4 指纹规则，或用限速兜底。

"已验证 Bot 被拦截"

• 原因：被 WAF Managed Rules（而非仅 Bot Management）拦截。
• 解决：为特定规则 ID 创建 WAF 例外，并通过反向 DNS 验证 Bot。

"Yandex Bot 在 IP 更新期间被拦截"

• 原因：Yandex 更新 Bot IP，新 IP 在 48 小时传播期内未被识别。

• 解决：① 在 Security Events 中定位拦截 Yandex 的具体 WAF 规则 ID；② 创建 WAF 例外：

  (http.user_agent contains "YandexBot" and ip.src in {<yandex-ip-range>}) Action: Skip (WAF Managed Ruleset)

  ③ 在 Bot Analytics 观察 48 小时；④ 传播完成后移除例外。该问题 48 小时后会自动解决，持续存在则联系 Cloudflare 支持。

"JA3/JA4 缺失"

• 原因：非 HTTPS 流量、Worker 路由流量、经 Worker 的 Orange-to-Orange 流量，或 Bot Management 被跳过。
• 解决：JA3/JA4 仅对 HTTPS/TLS 流量可用，检查请求路由。

JA3/JA4 非用户唯一：相同浏览器/库版本 = 相同指纹。不要用于用户身份识别，仅用于客户端画像；浏览器升级后指纹会变化。

Bot 验证方法

1. 反向 DNS（IP 校验）：传统方法——Bot IP 反向解析到预期域名；
2. Web Bot Auth：现代密码学验证——传播更快。

当verifiedBot=true时，表示 Bot 至少通过了一种验证方式。非活跃的已验证 Bot：连续 24 小时无流量后其 IP 会被移除。

检测引擎行为对照

优先级：Heuristics > ML——启发式命中时无论 ML 结果如何，score 一律为 1。

限制速查

套餐功能限制

延伸阅读

• WAF 参考：WAF 自定义规则用于 Bot 处置执行；
• Workers 参考：request.cf.botManagementAPI 的运行时细节；
• API Shield 参考：API 专属的 Bot 防护能力；
• cloudflare-deploy skill 总览：在完整安全决策树中定位 Bot Management。

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