API 网关与 Cloudflare API Shield：边缘与源站安全边界

Cloudflare API Shield 与源站 API 网关保护的是不同边界。Cloudflare 可以在边缘发现并评估 API 流量，执行已配置的 mTLS、Schema、JWT、限流和 WAF 控制。源站网关仍负责后端路由、服务感知策略、下游容量，以及传递给应用的已认证上下文；应用则继续负责对象与工作流授权。

只有当流量无法绕过 Cloudflare、边缘检测没有被误认为阻断、源站也不会在未认证路径上信任 Cloudflare 添加的请求头时，这套设计才成立。应把整个集成当作一条请求链，明确执行与故障行为。

核心要点

• 只保留一条经过 Cloudflare 的公网路径，并认证或限制 Cloudflare 到源站的连接。
• 分离检测与执行：当前 Schema Validation 2.0 产生违规信号，WAF 自定义规则决定采取什么动作。
• 只有能够证明请求经过预期 Cloudflare 路径时，才把 CF-Connecting-IP 当作可信上下文。
• 边缘 JWT 或客户端证书验证不能替代源站的路由、租户、对象与工作流授权。
• 先在观察模式运行规则，再切换到阻断，并测试不受支持的请求体、Content-Type、缺失 Token、旧密钥和绕过源站路径。

划分控制职责

Cloudflare 当前 API Shield 概览列出了发现、Schema、JWT、mTLS 等安全能力，但功能可用性和限制会随套餐而异。实施时应重新核对最新文档与合同，不要把套餐矩阵固化在架构代码里。

只保留一条公网路径

1flowchart LR
2    C[API 客户端] --> E[Cloudflare 边缘]
3    E -->|已认证或受限的源站路径| G[源站 API 网关]
4    G --> A[API 服务]

不要把源站网关公网地址留作备用路径。攻击者一旦可以直连，边缘 WAF、Schema、Token 和限流规则就会变成可选项。应按场景组合私有连接、防火墙允许列表、Cloudflare Tunnel 和已认证源站连接。

Cloudflare Authenticated Origin Pulls（AOP）在边缘到源站的连接上使用双向 TLS，其信任范围必须明确：

• Cloudflare 全局证书只能证明请求来自 Cloudflare 网络，不能证明属于某一个客户账号；
• Zone 或单主机证书提供更窄、由客户控制的信任边界；
• 通过 Cloudflare Tunnel 访问的主机名不适用 AOP，因为 Tunnel 使用出站 Connector 凭据，而不是源站入站监听器。

验证源站服务器证书与认证 Cloudflare 客户端解决的是 TLS 两个相反方向的问题，适用时应同时配置。随后测试直接访问 IP、不可信客户端证书、过期源站证书以及预期 Tunnel 或 AOP 路径。

建立可信客户端上下文

Cloudflare 的 HTTP 请求头参考把 CF-Connecting-IP 定义为 Cloudflare 发送给源站的客户端地址。这并不意味着任何同名请求头都可信。源站网关只有在确认连接来自预期 Cloudflare 路径后才能使用它，并应在向下游传递前删除或替换调用方提交的副本。

还要记录 Worker 与叠加代理行为。Cloudflare 指出，同 Zone Worker 子请求中的 CF-Connecting-IP 可能来自 Worker 可控制的 x-real-ip，跨 Zone 子请求则使用固定 Cloudflare 地址；X-Forwarded-For 也可能包含到达 Cloudflare 之前就存在的地址链。应明确允许哪些路径并逐一测试，而不是假设一个请求头总能代表真实最终用户。

IP 地址始终是网络信号，不是已验证账号身份。它可以在正确处理代理后用于限流与风险上下文，但不应成为敏感数据授权的唯一键。

分离 Schema 检测与执行

当前 Schema Validation 2.0会把请求与上传的 OpenAPI 3.0 Schema 比较，并暴露 cf.schema_validation.uploaded.violated。文档明确分离常驻检测与缓解：必须再由 WAF 自定义规则对该信号采取动作。

1flowchart LR
2    R[请求] --> V[Schema Profile 评估]
3    V -->|违规信号| W[WAF 自定义规则]
4    W -->|记录或质询通过| G[源站 API 网关]
5    W -->|阻断或质询失败| E[Cloudflare 边缘响应]

Profile 评估负责给出发现，WAF 规则负责执行配置动作。如果规则只记录日志，就不能把评估器描述成已经阻断请求。

Schema 覆盖也有边界。当前文档支持 OpenAPI 3.0.x，而不是所有 OpenAPI 版本和结构；它验证受支持的请求字段，而不是响应，并采用与套餐相关的请求体检查上限。JSON 请求体验证还依赖受支持的 Content-Type。超出这些限制的请求不能证明其请求体符合 Schema。

建议按以下顺序发布：

1. 从唯一事实来源导出经过审查的 API OpenAPI 契约；
2. 上传并激活 Schema Profile；
3. 发送有代表性的有效、无效、超限和其他 Content-Type 请求；
4. 检查违规原因与误报；
5. 增加范围精确的日志模式规则；
6. 对阻断动作做灰度并保留即时回滚；
7. 当部署路由与 Schema Operation 漂移时告警。

应用仍必须验证输入。边缘 Schema 检查属于纵深防御，它看到的解码表示与业务不变量可能和服务不同。

把 JWT 验证当作一层认证

Cloudflare 的 JWT 验证文档把 Token 配置与规则动作分开。Token 配置指定 Token 位置和签名验证密钥。文档中的流程会匹配 kid 与 alg、验证签名，并且只在 Token 包含 exp 和 nbf 时检查这些声明，同时允许最多 60 秒时钟容差；它不会自动要求预期 iss、aud、exp 或 nbf 必须存在且匹配。应在支持的 WAF 自定义规则中强制检查必需声明及其取值，或在源站重新验证。随后，WAF 自定义规则或 Token 验证规则才决定在选定流量上记录还是阻断。

应定义完整契约：

• 必需的 issuer、audience、算法、key ID、时间声明和密钥轮换流程，以及负责执行这些要求的规则或源站检查；
• 缺失、无效还是两者都会触发拒绝；
• 有意不携带普通 Token 的登录与刷新 Operation；
• 时钟容差和吊销预期；
• 转发到源站的最少已验证声明；
• 源站网关是否再次验证，以及应用最终信任哪个结果。

不要在已验证 Token 旁边继续传递调用方提供的 X-User，再让源站二选一。如果把已验证声明转换成请求头，应替换传入副本，并只在已认证 Cloudflare 路径上接受它们。应用仍要根据租户和对象对主体授权。

为合适的客户端群体使用 mTLS

API Shield mTLS可以认证在受保护主机或路径上出示证书的客户端，适合服务间调用或受管设备，但持有证书并不能表达所有应用权限。

规则范围必须谨慎。Cloudflare 配置指南建议检查证书验证状态，并在适用时检查签发方身份；由 Cloudflare 管理和自行上传 CA 的吊销行为也不同。应测试无证书、错误签发方、在支持范围内已吊销的证书、过期证书、有证书但无应用权限，以及证书轮换。

客户端到 Cloudflare 的 mTLS 与 Cloudflare 到源站的 AOP 是两条不同链路。图表、日志和操作手册应使用不同名称，避免把有效边缘客户端证书误认为已认证源站连接。

协调限流与故障策略

Cloudflare 与源站网关都可以限流，但它们往往看到不同身份和计数器。边缘可以在靠近客户端的位置阻断广泛滥用，源站网关则执行与后端容量一致的租户或路由预算。两层重叠范围和响应契约必须有文档。

对每项边缘依赖或策略，都要决定：

• 配置或密钥分发错误时是开放还是关闭；
• 无法完整检查的请求体会被接受、记录还是拒绝；
• WebSocket、gRPC、流式、上传和非 JSON 内容有什么区别；
• 哪些状态和原因能区分边缘拒绝、网关拒绝与后端失败；
• 紧急绕过如何授权、限时和审计。

如果没有端到端尝试预算，不要在 Cloudflare 与源站网关同时自动重试。客户端收到响应前超时，并不代表应用还没有提交写操作。

关联边缘与源站观测

在源站记录 Cloudflare Cf-Ray，用于跨层排查；同时保留网关生成的内部请求 ID。二者都不是用户身份。还应保留路由、规则、Schema Profile、部署和源站服务版本，使拒绝事件可以对应到具体配置。

仪表盘应区分：

• Cloudflare 看到的请求与真正交付源站的请求；
• Schema 发现与真正执行的 Schema 动作；
• 缺失 Token、无效 Token 与授权拒绝；
• mTLS 握手或规则失败与应用权限失败；
• Cloudflare 边缘错误、源站连接错误、网关拒绝和服务错误；
• 直接访问源站的尝试与允许的 Cloudflare 流量。

验证清单

• 直连源站会被网络阻断或密码学认证拒绝。
• 源站证书验证以及 AOP 或 Tunnel 认证符合设计。
• 伪造的 CF-Connecting-IP、身份和关联请求头在备用路径上不会被信任。
• 已测试 Schema 有效、无效、超限、不受支持媒体类型和未知 Operation 请求。
• 仅检测规则与阻断规则产生不同且符合预期的结果。
• 缺失、格式错误、过期、错误密钥和有效 JWT 分别走预期且有文档记录的路径。
• mTLS 测试覆盖无证书、签发方、吊销支持、轮换和应用授权。
• 边缘与源站限流使用已命名身份，且不会制造意外的共享保证。
• 日志可关联同一请求，同时会脱敏 Token、Cookie 与敏感请求体。
• 回滚可以停用单条错误规则，而不必关闭整条边缘安全路径。

总结

Cloudflare API Shield 提供边缘可见性和控制，源站 API 网关与应用则继续承担不同的路由、容量和授权职责。应阻止源站绕过、认证边缘到源站路径，只在该边界内把请求头当作上下文，并把每一个检测结果与执行它的规则分开。强健的设计会像测试正常请求一样，认真测试不支持和故障路径。

常见问题

Schema Validation 会自动阻断无效请求吗？

当前 Schema Validation 2.0 产生违规信号，缓解动作由单独配置的 WAF 自定义规则决定。

源站可以信任 CF-Connecting-IP 吗？

只有能够证明请求经过预期 Cloudflare 路径，并且理解有文档的 Worker 或代理拓扑时才可以。它是客户端地址信号，不是账号身份。

边缘 JWT 验证能替代应用授权吗？

不能。它可以验证受支持的 Token 密码学并暴露声明，但必需 issuer、audience 和时间声明的语义仍要由明确的规则或源站检查执行。应用还必须根据租户、对象和工作流状态决定权限。

后续步骤

继续设计完整的 API 网关与 WAF 架构，建立网关 mTLS 边界，并定义细粒度授权归属。