企业 API 防护的另一条路：从「拦坏人」到「只放行对的请求」

直接回答： WAF 判断的是「这个请求像不像攻击」，API Shield 判断的是「这是不是我的接口本来就该收到的请求」。它的几个组件回答的是不同问题：mTLS 与 JWT 校验解决身份，Schema 校验拿上传的 OpenAPI 契约比对请求，接口发现负责盘点到底有哪些接口，序列分析建模调用顺序，每会话阈值解决频率异常。但它们都不直接拦截流量——每个组件只产出信号，真正做动作的是你写的 WAF 自定义规则或限流规则。API Shield 是 Enterprise 的付费附加产品，而用 Cloudflare 托管 CA 的 mTLS 在任何套餐都能配。

为什么「黑名单式」防护在 API 上会失效

托管 WAF 规则依赖已知攻击特征：注入语法、利用载荷、扫描器指纹。这些规则在它们被写出来的那类攻击上一直有效，而且上了 API Shield 之后仍然有效——两者是叠加关系，不是替换关系。

问题在于，真正烧钱的 API 事故里，请求往往根本不含攻击载荷。看几类典型事故在日志里长什么样：

事故类型	请求长什么样	黑名单模型为什么漏
影子 API	一个没人知道对外开放的合法路径	没有特征可匹配；从未被登记的接口，自然没人给它写过规则
凭证滥用	凭证正确、JSON 正确、频率合理	载荷里没有任何恶意内容，错的只是身份
越权读取（BOLA）	GET /api/invoices/{id}，令牌有效	请求完全合规，只是这个对象不属于调用方

三类请求在语法上都和正常流量无法区分。真正能区分的证据在别处：这个接口在不在我的契约里、调用方拿的是不是我签发的凭证、这个调用顺序是不是我的客户端真实产生的、这个会话在这个接口上的量是不是正常。这就是正向安全模型——先声明什么是对的，其余一律视为未知。

正向安全模型到底在校验什么

请求被转发之前，可以先断言三个维度：

1. 结构：接口路径、方法、查询参数形状、请求体，是否符合已发布的契约。
2. 身份：调用方是否持有你签发的凭证——客户端证书，或者一个未过期、未被篡改的签名令牌。
3. 行为：调用顺序与每会话的请求量，是否符合这个接口平时的样子。

黑名单模型说的是「拦掉我认得的坏东西」，正向模型说的是「只放行我认得的自己人」。对 API 来说后者才抓得住贵的那部分事故，因为 API 滥用通常是格式完全正确的。

API Shield 里到底有哪些东西

这个名字底下挂着好几个经常被混为一谈的组件。每个只回答一个问题，而且每个都有各自独立的可用性声明——所以「我们是 Enterprise，所以有 API Shield」这个推断并不成立。

组件	回答什么问题	产出什么	可用性
会话标识（session identifier）	这条请求属于哪个客户端会话	供后续所有功能使用的会话上下文	需要 API Shield 订阅或可用试用；最多配置 10 个
接口发现（Discovery）	我到底对外暴露了哪些接口	候选接口与影子接口	需要付费的 API Shield 附加产品
Schema 校验	这个请求符合我的契约吗	cf.schema_validation.uploaded.violated	上传配额按 zone 套餐划分；Log 动作需要 Enterprise
mTLS	客户端是否持有我信任的证书	边缘完成证书校验	用 Cloudflare 托管 CA 时全套餐可用；上传自有 CA 限 Enterprise，最多 5 个
JWT 校验	令牌是否过期、被篡改、尚未生效	cf.api_gateway.tokens.valid 与已验证的 claims	API Shield 客户可用；Enterprise 可预览
序列分析（Sequence Analytics）	这个调用顺序正常吗	带优先级评分的调用序列，最长 9 个操作	API Shield 客户可用；Pro / Business 可试用
用量异常检测（Volumetric Abuse Detection）	这个会话的量正常吗	每会话阈值建议，含 p50/p90/p99 与置信度	仅 Enterprise

其中两个值得单独说清楚。

Schema 校验 2.0 是「检测」，不是「拦截」。 上传 OpenAPI 契约后会产生一个常开检测，Cloudflare 文档写得很明确：这个检测本身不会缓解流量。你要先在 Profile Analysis 里看违规情况，再用一条 WAF 自定义规则匹配 cf.schema_validation.uploaded.violated 去执行。上传完契约就等着拦效果，是等不到结果的。

用量异常检测改变了计数的单位。 传统限流按 IP 或某个特征在固定窗口里数请求；这个能力按会话把请求切成 10 分钟一组，分析 7 天流量，然后给每个接口返回一个建议阈值，附带分位值和置信度。按会话计数能显著减少「很多人共用一个出口 IP」带来的误杀。要真正启用按会话的限流，还需要订阅 Advanced Rate Limiting。

检测到执行：两段式才是真流程

最常见的落地错误，是把这些功能当成一开就能拦流量的开关。它们只产出信号，做动作的是规则。

不容易走弯路的落地顺序

第一步：会话标识。 先配这个，最多 10 个，可以是 Cookie、HTTP 头或 JWT claim。如果你什么都不配，而 Authorization 头出现在超过 1% 的合格采样请求（返回 2xx）里，Cloudflare 会自动把该头配成会话标识，且不会覆盖已有配置。注意依赖关系：接口发现、序列分析、序列缓解和限流建议全都依赖这个设置，跳过它等于静默关掉后面所有分析能力。

第二步：接口发现，当盘点用而不是当防护用。 发现功能用路径结构启发式从采样流量里生成接口地图，会把 /api/profile/238 和 /api/profile/392 归并为 /api/profile/{var1}。规划之前先看门槛：一个接口要出现，必须从边缘返回 2xx、不能来自 Cloudflare Worker，并且在连续 10 天内收到至少 500 次请求。低频的内部接口根本不会出现。另外发现功能需要在账号和 zone 两个层面都启用，只在账号层订阅而没分配到 zone 的话不会有任何结果。

第三步：上传 OpenAPI 契约，然后执行它。 Cloudflare 接受 OpenAPI v3.0 语义——v3.1 的文件若只用 v3.0 兼容语义可以上传成功，但 v3.1 独有语义和 OpenAPI 2.0 不支持。接口必须先在 Web Assets 里存在为已保存操作。先用 Log 跑检测：在 Profile Analysis 里看违规，是契约写错了就改契约，确认之后才切到 Block。同时补一条兜底规则——控制台里有 Mitigate API requests to unidentified endpoints 模板，用 cf.api_gateway.fallthrough_detected 抓所有没匹配到已保存接口的请求。真正关掉影子 API 的是这条规则。

第四步：身份。 机器对机器流量（合作伙伴集成、IoT 设备、服务账号）用 mTLS 把凭证绑定到证书而不是一串共享字符串，用 Cloudflare 托管 CA 时全套餐都能配，也支持 gRPC。面向用户的流量用 JWT 校验，在边缘检查签名与有效期，并把已验证的 claims 暴露给规则。两个运维细节要注意：令牌配置不会自动去 JWKS 地址拉取或轮换密钥，换密钥要主动推送；浏览器会发不带凭证的 OPTIONS 预检请求，JWT 规则里要加 or http.request.method eq "OPTIONS"，否则会打掉 CORS 客户端。

第五步：行为。 有了会话标识和已保存接口，序列分析会给出按优先级评分排列的调用顺序，评分基于最近 24 小时的数据，序列最长 9 个操作。用它找出关键业务路径，再和你自己的研发确认「最后一个接口是否必须被前面的接口前置」。之后用量异常检测给出按接口、按会话的阈值建议——置信度低的时候先用 log 模式观察。

第六步：应用层控制不要撤。 边缘判断不了某个租户能不能读某个对象，也撑不起全局配额，更没法把一次请求换算成成本。这些留在你自己的代码里。

API Shield 做不到的事

把边界写清楚正是本文的目的，所以直接列出来：

限制	具体说明
响应校验	不支持。校验作用在请求上，不校验你的接口返回什么
契约特性	不支持 responses、外部引用、非基础路径模板、uniqueItems
对象类型参数	目前不校验
请求体校验大小	Free 1 KiB、Pro 8 KiB、Business 8 KiB、Enterprise 128 KiB，且与 WAF 的请求体检查大小是两套独立限制
接口发现覆盖	达不到「10 天 500 次请求」门槛的接口永远不会出现
序列长度	最长 9 个操作
JWT 位置	只支持请求头或 Cookie；放在 POST body 里的令牌需要联系客户团队
全局配额	限流计数器按数据中心累加，边缘规则给不出全网统一上限
业务授权	对象级访问控制属于应用逻辑

其中两条值得重申，因为它们最容易造成落差。Schema 校验管的是形状，不是语义——一个请求可以完全符合契约，同时仍是一次对他人数据的越权读取。另外共享出口 IP 不等于一个会话：按会话计数正是用来解决 NAT 和代理撞车问题的，但它依赖你主动配置的会话标识，而不是 Cloudflare 猜出来的东西。

套餐与计费边界

下表根据 Cloudflare 的 API Shield 套餐文档整理，实际以控制台为准：

	Free	Pro	Business	Enterprise（未订阅 API Shield）	Enterprise（已订阅 API Shield）
可保存接口数	100	250	500	3,000	10,000
启用状态的上传契约数	5	5	10	10	10
启用契约的总大小	200 KiB	500 KiB	2 MiB	5 MiB	10 MiB 以上
规则动作	仅 Block	仅 Block	仅 Block	Log 或 Block	Log 或 Block

这张表和官方的可用性声明一起，推出三个结论：

• API Shield 是 Enterprise 专属的付费附加产品，升套餐并不自带。Cloudflare 文档同时说明，Enterprise 客户可以把 API Shield 作为非合同服务预览使用，预览期内功能完整且不产生计量费用——这是判断「自己的契约和会话标识是否已经整理到位、值不值得买」最实际的办法。
• Enterprise 以下只有 Block 动作，会改变上线节奏。 没有 Log 就无法先观察再执行，所以在 Free、Pro、Business 上诚实的做法是先把契约写准再执行；或者改用 WAF 的 Application Profiles + Schema Learning，用真实流量反推契约，而不是上传文件。
• mTLS 是那个到处都能用的例外。 任何套餐都可以用 Cloudflare 托管 CA 配双向 TLS；上传自有 CA 限 Enterprise，最多 5 个，更高数量需要申请。如果你的当务之急是「合作伙伴集成还在共用一把长期密钥」，这件事不需要买附加产品就能解决。

什么情况下值得做，什么情况下不值得

值得投入的情况：你把文档化的 API 开放给第三方或合作伙伴；你有机动端、桌面端或 IoT 客户端，而它们无法快速发版修补；你有多个 API 子域、接口重叠；你要应对一次要求提供接口清单的审计；或者你的契约足够稳定，维护 OpenAPI 文件比排查事故便宜。

不太适合的情况：API 只有几个内部接口、只有一个消费方，治理成本高于风险；流量远低于接口发现的门槛，导致清单始终不完整；协议是二进制、不在 Schema 校验覆盖范围，这时靠 mTLS 加应用层校验扛住；或者没人负责维护 OpenAPI 文件——因为一份过期的契约在边缘强制执行，挡住正常调用方的速度会比挡住攻击者更快。

还没准备好采购的团队，可以走一条中间路线：配置会话标识、用 Schema Learning 从真实流量反推契约、对未登记接口启用兜底规则、给机器对机器集成加 mTLS。这条路线不需要附加产品，却覆盖了导致大多数 API 事故的两种失效模式——未登记的接口，以及共享的凭证。

常见问题

Cloudflare Enterprise 套餐会自动包含 API Shield 吗？ 不会。Cloudflare 文档把完整的 API Shield 安全套件标注为 Enterprise 专属的付费附加产品，订阅方式是先升级到 Enterprise 再联系客户团队。Enterprise 客户可以把 API Shield 作为非合同服务预览使用，预览期内功能完整且不产生计量费用。各组件的可用性并不一致：用 Cloudflare 托管 CA 的 mTLS 在所有套餐都能用，序列分析对未购买 API Shield 的 Pro、Business 与 Enterprise 客户提供试用。

上传 OpenAPI 契约之后会自动拦截不合规的请求吗？ 不会。Schema 校验产生的是一个常开检测，Cloudflare 明确说明该检测本身不缓解流量。你需要先在 Profile Analysis 里查看违规情况，再写一条 WAF 自定义规则匹配 cf.schema_validation.uploaded.violated 去执行。Free、Pro、Business 上唯一的动作是 Block，Log 需要 Enterprise——这也是「先观察后执行」的节奏依赖套餐的原因。

不买 API Shield 能用 mTLS 吗？ 可以。所有套餐都能用 Cloudflare 托管的证书颁发机构配置 mTLS，mTLS 文档里明确写了它并不依赖 API Shield。上传最多 5 个非 Cloudflare 的 CA 属于 Enterprise 能力。mTLS 也支持 gRPC 接口，这对不说 JSON 的服务间流量很关键。

API Shield 能解决越权读取（BOLA）吗？ 不能。Schema 校验确认的是请求形状合规，它无法判断这个已认证的调用方是否有权读取这个具体对象——对象级授权属于应用逻辑。全局配额同理：限流计数器按数据中心累加，全网统一的上限必须在你自己的系统里实现。

可以上传哪个版本的 OpenAPI？ Cloudflare 接受 OpenAPI v3.0 语义（含所有 3.0.x 补丁版本），格式为 YAML 或 JSON。使用 v3.1 的文件在只依赖 v3.0 兼容语义时可以上传成功，但 v3.1 独有语义不支持，OpenAPI 2.0 完全不支持。外部 $ref 引用也不支持，多文件契约需要先打包成单文件再上传。

什么情况下 API Shield 不值得买？ 接口面很小且只有一个消费方、没有人维护准确的 OpenAPI 文件、或者流量低于接口发现的门槛（单个接口连续 10 天内不足 500 次请求）时，都不划算。这种情况下，会话标识、基于真实流量的 Schema Learning、未登记接口的兜底规则，加上机器对机器场景的 mTLS，已经能拿到大部分价值，且不需要附加产品。

相关阅读

• API Key 泄露后如何防止接口被滥用？
• AI SaaS 如何防止 API 被恶意调用？
• 企业级 WAF 应该如何选择？
• 如何识别正常用户、恶意爬虫和自动化 Bot？

如果你在判断正向模型是否适合自己的接口体系，建议从现有契约和真实流量出发，而不是从功能清单出发——和我们一起评估现有架构。