Cloudflare AI Gateway 排障实战从 401/429 错误到缓存失效、日志缺失与限流分析的完整排查指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare AI Gateway 是介于你的应用与 OpenAI、Anthropic、Workers AI 等模型提供商之间的统一网关在转发请求的同时提供缓存、限流、日志与分析能力。本文围绕skills/.curated/cloudflare-deploy技能中 ai-gateway/troubleshooting.md 这一官方排障文档系统整理网关接入后最常遇到的错误码、隐蔽坑点Gotchas、缓存不生效、日志缺失等问题的定位与修复方法并结合同一技能目录下的 配置文档、功能说明、SDK 集成 与 动态路由 做源码级纵深说明。读完本文你将掌握一套从看状态码到查响应头再到用分析面板验证的完整排障链路能独立定位绝大多数 AI Gateway 接入问题。AI Gateway 排障前必须掌握的两条链路排障的第一步是理解请求经过的路径。根据 AI Gateway README 中的架构说明AI Gateway 本质上是应用与模型提供商之间的代理链路如下Your App → AI Gateway → AI Provider (OpenAI, Anthropic, etc.) ↓ Analytics, Caching, Rate Limiting, Logging也就是说一个请求会先后经历网关鉴权、缓存查询、限流检查、转发到模型提供商、日志采集等多个环节。任一环节出问题表现出的症状各不相同401网关鉴权失败请求还没进入网关就被拒绝403模型提供商的密钥BYOK失效网关鉴权通过但上游拒绝429限流被触发可能是网关级限流也可能是上游提供商限流缓存 MISS / 日志缺失请求虽然成功但缓存或日志链路没生效。此外要记住 AI Gateway 的 URL 形态README 关键 URL 模式统一 APIOpenAI 兼容https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions提供商专属https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}动态路由用路由名替代模型名如dynamic/{route-name}排障时先确认自己用的是哪种 URL 形态再对照下面的错误表逐项排查。常见错误码速查401 / 403 / 429关联文档开篇给出的错误速查表是排障的入口下表完整继承原文档错误码原因修复方法401缺少cf-aig-authorization请求头在请求头中添加携带 Cloudflare API Token 的该头403无效的提供商密钥 / BYOK 密钥过期在控制台检查 Provider Keys提供商密钥429超出限流阈值提高限流上限或实现退避backoff重试这里需要补充一个容易混淆的区分依据 README 网关鉴权说明401 与 403 拦截的关卡不同。AI Gateway 有两种网关类型未认证网关Unauthenticated Gateway开放访问不推荐生产环境使用认证网关Authenticated Gateway必须携带cf-aig-authorization头值格式为Bearer {Cloudflare API Token}推荐生产环境使用。而提供商侧的鉴权又分三种模式配置文档 Provider Auth OptionsUnified Billing统一计费keyless通过 Cloudflare 付费无需提供商密钥仅用cf-aig-authorization头BYOKBring Your Own Key把提供商密钥存在 Cloudflare 控制台Provider Keys 区域代码里不出现密钥请求头透传Request Headers每次请求带上提供商的鉴权头。因此401 基本指向网关鉴权cf-aig-authorization缺失或 Token 错误403 基本指向提供商密钥BYOK 过期或透传密钥无效。若使用 BYOK需到控制台的 Provider Keys 页面核对密钥是否过期、是否与目标提供商匹配。401 修复为 OpenAI SDK 客户端补上网关鉴权头原文档给出了 OpenAI SDK 场景下的 401 修复示例这也是 SDK 集成文档 中 OpenAI SDK 模式的标准写法const client new OpenAI({ baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai, defaultHeaders: { cf-aig-authorization: Bearer ${CF_API_TOKEN} } });要点拆解baseURL指向该账号下指定网关的openai提供商端点defaultHeaders中的cf-aig-authorization是网关鉴权头值为Bearer前缀 Cloudflare API Token网关管理 API Token 需要AI Gateway - Read Edit权限仅访问网关最小需要AI Gateway - ReadAPI Token 权限说明。如果你的应用还传了apiKey比如 OpenAI 自己的密钥则形成网关鉴权 提供商透传双头模式这也是三种提供商鉴权模式之一。429 重试模式指数退避的标准实现429 既可能来自网关限流也可能来自上游提供商。原文档给出的重试函数采用指数退避exponential backoff可直接嵌入任意异步请求async function requestWithRetry(fn, maxRetries 3) { for (let i 0; i maxRetries; i) { try { return await fn(); } catch (e) { if (e.status 429 i maxRetries - 1) { await new Promise(r setTimeout(r, Math.pow(2, i) * 1000)); continue; } throw e; } } }行为说明默认最多重试 3 次maxRetries 3仅在e.status 429时重试其余错误直接抛出避免掩盖真实故障第i次失败后等待2^i秒1s → 2s → 4s实现退避而非固定间隔降低对网关与上游的压力最后一次尝试若仍 429 则抛出异常交由上层处理。如果使用 Vercel AI SDK可以在 ai-gateway-provider 封装 中通过retries选项声明式配置重试retries: { maxAttempts: 3, backoff: exponential }无需手写循环。隐蔽坑点Gotchas全景七个容易踩中的陷阱原文档的 Gotchas 表浓缩了社区踩坑经验这里完整继承并逐条展开。这组表象 vs 现实的对照是排障时最容易被忽略的部分问题现实情况Metadata 限制最多 5 个条目且只支持扁平结构不支持嵌套缓存键冲突缓存键必须针对每种预期响应唯一否则串缓存BYOK 统一计费二者互斥不能同时启用限流作用域按网关per-gateway统计而非按用户要实现按用户限流需用动态路由日志延迟延迟 3060 秒属于正常现象流式 缓存不兼容二者不可同时使用模型名统一 API必须带提供商前缀如openai/gpt-4o不能只写gpt-4o逐一深入1. Metadata 扁平且限 5 条。cf-aig-metadata请求头用于传递自定义追踪信息值必须是 JSON 对象。参考 动态路由文档的 Metadata 说明headers: { cf-aig-metadata: JSON.stringify({ userId: user-123, tier: pro, region: us-east }) }限制为最多 5 个键值对、值只允许 string/number/boolean/null、不允许嵌套对象动态路由 Limitations。多传、嵌套都会导致该头被忽略或报错。2. 缓存键冲突。网关默认以请求参数模型、消息、温度等组合缓存键。若你自定义cf-aig-cache-key务必为不同预期响应分配唯一键例如按语言拆分greeting-en/greeting-zh参考 功能文档自定义缓存键示例否则用户会拿到语义错误的缓存结果且这种脏缓存极难排查。3. BYOK 与统一计费互斥。二者是两种不同的提供商鉴权路径BYOK 在控制台存密钥统一计费走 Cloudflare 账单keyless。同一网关不能同时启用两者配置文档鉴权模式排障 403 时先确认自己处于哪种模式再决定去 Provider Keys 页面还是账单设置里找问题。4. 限流按网关粒度。网关设置的限流阈值针对整个网关的所有请求功能文档 Rate Limiting不区分用户。若要做免费用户 10 次/小时、付费用户 1000 次/小时这类按用户限额必须用动态路由中的 Rate Limit 节点动态路由 Node Types配合cf-aig-metadata里的 userId 做条件分流。5. 日志延迟 3060 秒。日志从请求完成到出现在分析面板之间存在延迟3060 秒属正常。排障日志没出现时先等满这个窗口再下结论。6. 流式与缓存不兼容。开启流式响应streaming后网关无法对完整响应做缓存缓存必然失效详见下文缓存不生效。需要在实时性与命中率之间取舍。7. 模型名前缀。使用统一 API/compat端点时模型名必须写成{provider}/{model}形式例如openai/gpt-4o、anthropic/claude-sonnet-4-5只写gpt-4o会导致提供商路由失败。这一点在 README Pattern 2 与 SDK 集成文档 中均有印证。缓存不生效四类原因与一个验证头原文档把缓存不工作列为一类高频问题给出的原因清单如下常见原因请求参数不同temperature 等参数变化导致缓存键不一致开启了流式响应streaming流式与缓存不兼容网关设置中未启用缓存Dashboard → Settings → Cache Responses。快速验证读取响应头的cf-aig-cache-status值为HIT或MISS// Check response headers console.log(Cache:, response.headers.get(cf-aig-cache-status));排障顺序建议先确认网关设置中已开启缓存功能文档确认未开启流式响应检查请求头是否带cf-aig-skip-cache: true该头会强制绕过缓存对比两次相同请求的参数模型、消息内容、temperature、max_tokens 等是否完全一致最后用cf-aig-cache-status头区分 HIT/MISS始终 MISS 说明缓存键不匹配或缓存被绕过HIT 后再看响应内容是否符合预期排除缓存键冲突。补充缓存相关的可用头来自 README Headers Quick Reference 与 功能文档头用途示例备注cf-aig-cache-ttl自定义缓存时长3600单位秒最小 60最大 259200030 天cf-aig-skip-cache绕过缓存true调试或实时数据场景使用cf-aig-cache-key自定义缓存键my-key每个预期响应必须唯一cf-aig-cache-status缓存命中状态仅响应头HIT或MISS默认 TTL 由网关设置决定创建网关时可通过 API 传cache_ttl参考 配置文档创建网关示例请求级cf-aig-cache-ttl可覆盖默认值但受 60s30 天区间约束。日志不出现四步排查法日志缺失是另一个高频问题。原文档给出的排查步骤为确认日志已开启Dashboard → Gateway → Settings移除cf-aig-collect-log: false请求头该头值为false时会跳过本条请求的日志采集默认行为是记录日志参考 功能文档 Logging等待 3060 秒日志延迟正常窗口检查日志容量上限默认上限为 1000 万条即 10M。补充说明如果启用了Zero Data Retention零数据保留prompt/response 不会落库但请求计数与成本仍会统计功能文档。若你的场景要求隐私优先日志面板里看不到请求体属于预期行为此时应改看请求数、成本等聚合指标而不是日志明细。每条日志记录的字段包括prompt、response、provider、model、tokens、cost、duration、cache status、metadata功能文档日志条目说明。需要长期留存或跨平台分析时可用 Logpush 导出到 S3、GCS、Datadog、Splunk 等目标详见下文分析一节。Debugging用 curl 与响应头定位故障原文档提供了两组调试手段连通性测试与响应头检查。连通性测试curl一次调用同时带上提供商鉴权与网关鉴权两个头用于区分是哪一层拒绝了请求# Test connectivity curl -v https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/models \ -H Authorization: Bearer $OPENAI_KEY \ -H cf-aig-authorization: Bearer $CF_TOKEN排障解读返回 401 → 问题在cf-aig-authorization网关 Token 缺失或错误返回 403 → 问题在提供商侧$OPENAI_KEY无效或 BYOK 过期返回 200 但行为异常缓存/日志不对→ 问题在网关配置层继续看响应头。-v会打印完整请求/响应头便于观察cf-aig-cache-status、cf-ray等关键字段。响应头检查TypeScript// Check response headers console.log(Cache:, response.headers.get(cf-aig-cache-status)); console.log(Request ID:, response.headers.get(cf-ray));cf-aig-cache-statusHIT/MISS验证缓存是否按预期工作cf-rayCloudflare 的请求 ID当需要向支持团队反馈或对照日志时这是唯一定位单条请求的凭据。两种方式配合使用curl 验证连通性与鉴权响应头验证缓存与追踪基本能覆盖 90% 的接入问题。Analytics用指标与过滤器做数据级排障原文档指出分析面板入口为Dashboard → AI Gateway → Select gateway这是排查生产问题的终极手段——用聚合数据反向验证单请求层面的判断。核心指标MetricsRequests请求量总量与趋势TokensToken 用量输入/输出 Token 消耗Latency延迟p50 / p95 / p99 三个分位延迟p99 飙升通常指向特定提供商或特定路径Cache hit rate缓存命中率验证缓存策略是否有效Costs成本按模型/提供商统计的开销。日志过滤器Log filters过滤器示例用途status: error筛选所有出错请求快速定位错误码分布provider: openai只看指定提供商的请求cost 0.01筛出成本超过阈值的请求定位高开销调用duration 1000筛出耗时超过 1000ms 的慢请求排查延迟问题这四个过滤器可以组合使用例如provider: openai AND status: error AND duration 1000实现多条件联合定位。数据导出Export需要长期留存、告警或与自有可观测体系打通时使用Logpush将日志导出到 S3、GCS、Datadog、Splunk 等目标。导出后可以在你的 BI/监控系统中做原网关面板无法覆盖的交叉分析比如按业务线聚合成本、做异常检测告警。从排障文档看网关最佳实践结合 AI Gateway 功能文档的最佳实践 与 配置文档最佳实践可以归纳出一套少踩坑的基线配置作为排障的上游防线生产环境一律启用网关认证cf-aig-authorization杜绝开放网关被滥用导致限流误伤优先 BYOK 或统一计费把密钥移出代码wrangler secret put管理敏感变量参考 配置文档 Wrangler 集成按环境拆分网关dev / staging / prod避免开发流量污染生产缓存与限流配额设置限流防止密钥泄露或流量异常导致成本失控限流有固定窗口与滑动窗口两种算法滑动窗口更精确参考 功能文档开启日志为事后排障保留现场注意默认上限 10M 条重要网关配合 Logpush 导出确定性 prompt 启用缓存非确定性场景含流式不要依赖缓存涉及敏感数据时开启 Zero Data Retention但需接受日志明细不可见的代价对用户可见的 AI 功能开启 Guardrails 与 DLPGuardrails 支持 Flag 与 Block 两种动作DLP 可检测邮箱、SSN、信用卡等 PII 并支持 Flag / Block / Redact参考 功能文档从源头减少需要排障的异常输入。排障决策速查最后把全文内容收敛成一张决策表供接入或排障时直接对照症状首要检查项对应修复401是否带cf-aig-authorization头、Token 权限补头确认 Token 具备AI Gateway - Read403提供商密钥BYOK/透传状态Provider Keys 页面更换/续期密钥429网关限流配置、上游限流提高限流阈值或指数退避重试按用户限额需动态路由缓存全 MISS流式skip-cache 头参数一致性关流式去 skip-cache统一请求参数缓存 HIT 但内容错误自定义缓存键是否唯一换用语义唯一键如greeting-en日志缺失开关、cf-aig-collect-log头、延迟窗口、10M 上限开启日志移除false头等待 3060s导出归档统一 API 报错模型名是否带提供商前缀写openai/gpt-4o而非gpt-4o单请求无法定位cf-ray请求 ID 分析面板过滤器用status/provider/cost/duration组合过滤掌握这条状态码 → 响应头 → 分析面板的排障链路后配合本技能目录下的 AI Gateway 主文档、配置文档、功能文档、动态路由文档 与 SDK 集成文档即可独立完成 AI Gateway 从接入、优化到生产排障的完整闭环。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cloudflare AI Gateway 排障实战从 401/429 错误到缓存失效、日志缺失与限流分析的完整排查指南【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skillsCloudflare AI Gateway 是介于你的应用与 OpenAI、Anthropic、Workers AI 等模型提供商之间的统一网关在转发请求的同时提供缓存、限流、日志与分析能力。本文围绕skills/.curated/cloudflare-deploy技能中 ai-gateway/troubleshooting.md 这一官方排障文档系统整理网关接入后最常遇到的错误码、隐蔽坑点Gotchas、缓存不生效、日志缺失等问题的定位与修复方法并结合同一技能目录下的 配置文档、功能说明、SDK 集成 与 动态路由 做源码级纵深说明。读完本文你将掌握一套从看状态码到查响应头再到用分析面板验证的完整排障链路能独立定位绝大多数 AI Gateway 接入问题。AI Gateway 排障前必须掌握的两条链路排障的第一步是理解请求经过的路径。根据 AI Gateway README 中的架构说明AI Gateway 本质上是应用与模型提供商之间的代理链路如下Your App → AI Gateway → AI Provider (OpenAI, Anthropic, etc.) ↓ Analytics, Caching, Rate Limiting, Logging也就是说一个请求会先后经历网关鉴权、缓存查询、限流检查、转发到模型提供商、日志采集等多个环节。任一环节出问题表现出的症状各不相同401网关鉴权失败请求还没进入网关就被拒绝403模型提供商的密钥BYOK失效网关鉴权通过但上游拒绝429限流被触发可能是网关级限流也可能是上游提供商限流缓存 MISS / 日志缺失请求虽然成功但缓存或日志链路没生效。此外要记住 AI Gateway 的 URL 形态README 关键 URL 模式统一 APIOpenAI 兼容https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions提供商专属https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}动态路由用路由名替代模型名如dynamic/{route-name}排障时先确认自己用的是哪种 URL 形态再对照下面的错误表逐项排查。常见错误码速查401 / 403 / 429关联文档开篇给出的错误速查表是排障的入口下表完整继承原文档错误码原因修复方法401缺少cf-aig-authorization请求头在请求头中添加携带 Cloudflare API Token 的该头403无效的提供商密钥 / BYOK 密钥过期在控制台检查 Provider Keys提供商密钥429超出限流阈值提高限流上限或实现退避backoff重试这里需要补充一个容易混淆的区分依据 README 网关鉴权说明401 与 403 拦截的关卡不同。AI Gateway 有两种网关类型未认证网关Unauthenticated Gateway开放访问不推荐生产环境使用认证网关Authenticated Gateway必须携带cf-aig-authorization头值格式为Bearer {Cloudflare API Token}推荐生产环境使用。而提供商侧的鉴权又分三种模式配置文档 Provider Auth OptionsUnified Billing统一计费keyless通过 Cloudflare 付费无需提供商密钥仅用cf-aig-authorization头BYOKBring Your Own Key把提供商密钥存在 Cloudflare 控制台Provider Keys 区域代码里不出现密钥请求头透传Request Headers每次请求带上提供商的鉴权头。因此401 基本指向网关鉴权cf-aig-authorization缺失或 Token 错误403 基本指向提供商密钥BYOK 过期或透传密钥无效。若使用 BYOK需到控制台的 Provider Keys 页面核对密钥是否过期、是否与目标提供商匹配。401 修复为 OpenAI SDK 客户端补上网关鉴权头原文档给出了 OpenAI SDK 场景下的 401 修复示例这也是 SDK 集成文档 中 OpenAI SDK 模式的标准写法const client new OpenAI({ baseURL: https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai, defaultHeaders: { cf-aig-authorization: Bearer ${CF_API_TOKEN} } });要点拆解baseURL指向该账号下指定网关的openai提供商端点defaultHeaders中的cf-aig-authorization是网关鉴权头值为Bearer前缀 Cloudflare API Token网关管理 API Token 需要AI Gateway - Read Edit权限仅访问网关最小需要AI Gateway - ReadAPI Token 权限说明。如果你的应用还传了apiKey比如 OpenAI 自己的密钥则形成网关鉴权 提供商透传双头模式这也是三种提供商鉴权模式之一。429 重试模式指数退避的标准实现429 既可能来自网关限流也可能来自上游提供商。原文档给出的重试函数采用指数退避exponential backoff可直接嵌入任意异步请求async function requestWithRetry(fn, maxRetries 3) { for (let i 0; i maxRetries; i) { try { return await fn(); } catch (e) { if (e.status 429 i maxRetries - 1) { await new Promise(r setTimeout(r, Math.pow(2, i) * 1000)); continue; } throw e; } } }行为说明默认最多重试 3 次maxRetries 3仅在e.status 429时重试其余错误直接抛出避免掩盖真实故障第i次失败后等待2^i秒1s → 2s → 4s实现退避而非固定间隔降低对网关与上游的压力最后一次尝试若仍 429 则抛出异常交由上层处理。如果使用 Vercel AI SDK可以在 ai-gateway-provider 封装 中通过retries选项声明式配置重试retries: { maxAttempts: 3, backoff: exponential }无需手写循环。隐蔽坑点Gotchas全景七个容易踩中的陷阱原文档的 Gotchas 表浓缩了社区踩坑经验这里完整继承并逐条展开。这组表象 vs 现实的对照是排障时最容易被忽略的部分问题现实情况Metadata 限制最多 5 个条目且只支持扁平结构不支持嵌套缓存键冲突缓存键必须针对每种预期响应唯一否则串缓存BYOK 统一计费二者互斥不能同时启用限流作用域按网关per-gateway统计而非按用户要实现按用户限流需用动态路由日志延迟延迟 3060 秒属于正常现象流式 缓存不兼容二者不可同时使用模型名统一 API必须带提供商前缀如openai/gpt-4o不能只写gpt-4o逐一深入1. Metadata 扁平且限 5 条。cf-aig-metadata请求头用于传递自定义追踪信息值必须是 JSON 对象。参考 动态路由文档的 Metadata 说明headers: { cf-aig-metadata: JSON.stringify({ userId: user-123, tier: pro, region: us-east }) }限制为最多 5 个键值对、值只允许 string/number/boolean/null、不允许嵌套对象动态路由 Limitations。多传、嵌套都会导致该头被忽略或报错。2. 缓存键冲突。网关默认以请求参数模型、消息、温度等组合缓存键。若你自定义cf-aig-cache-key务必为不同预期响应分配唯一键例如按语言拆分greeting-en/greeting-zh参考 功能文档自定义缓存键示例否则用户会拿到语义错误的缓存结果且这种脏缓存极难排查。3. BYOK 与统一计费互斥。二者是两种不同的提供商鉴权路径BYOK 在控制台存密钥统一计费走 Cloudflare 账单keyless。同一网关不能同时启用两者配置文档鉴权模式排障 403 时先确认自己处于哪种模式再决定去 Provider Keys 页面还是账单设置里找问题。4. 限流按网关粒度。网关设置的限流阈值针对整个网关的所有请求功能文档 Rate Limiting不区分用户。若要做免费用户 10 次/小时、付费用户 1000 次/小时这类按用户限额必须用动态路由中的 Rate Limit 节点动态路由 Node Types配合cf-aig-metadata里的 userId 做条件分流。5. 日志延迟 3060 秒。日志从请求完成到出现在分析面板之间存在延迟3060 秒属正常。排障日志没出现时先等满这个窗口再下结论。6. 流式与缓存不兼容。开启流式响应streaming后网关无法对完整响应做缓存缓存必然失效详见下文缓存不生效。需要在实时性与命中率之间取舍。7. 模型名前缀。使用统一 API/compat端点时模型名必须写成{provider}/{model}形式例如openai/gpt-4o、anthropic/claude-sonnet-4-5只写gpt-4o会导致提供商路由失败。这一点在 README Pattern 2 与 SDK 集成文档 中均有印证。缓存不生效四类原因与一个验证头原文档把缓存不工作列为一类高频问题给出的原因清单如下常见原因请求参数不同temperature 等参数变化导致缓存键不一致开启了流式响应streaming流式与缓存不兼容网关设置中未启用缓存Dashboard → Settings → Cache Responses。快速验证读取响应头的cf-aig-cache-status值为HIT或MISS// Check response headers console.log(Cache:, response.headers.get(cf-aig-cache-status));排障顺序建议先确认网关设置中已开启缓存功能文档确认未开启流式响应检查请求头是否带cf-aig-skip-cache: true该头会强制绕过缓存对比两次相同请求的参数模型、消息内容、temperature、max_tokens 等是否完全一致最后用cf-aig-cache-status头区分 HIT/MISS始终 MISS 说明缓存键不匹配或缓存被绕过HIT 后再看响应内容是否符合预期排除缓存键冲突。补充缓存相关的可用头来自 README Headers Quick Reference 与 功能文档头用途示例备注cf-aig-cache-ttl自定义缓存时长3600单位秒最小 60最大 259200030 天cf-aig-skip-cache绕过缓存true调试或实时数据场景使用cf-aig-cache-key自定义缓存键my-key每个预期响应必须唯一cf-aig-cache-status缓存命中状态仅响应头HIT或MISS默认 TTL 由网关设置决定创建网关时可通过 API 传cache_ttl参考 配置文档创建网关示例请求级cf-aig-cache-ttl可覆盖默认值但受 60s30 天区间约束。日志不出现四步排查法日志缺失是另一个高频问题。原文档给出的排查步骤为确认日志已开启Dashboard → Gateway → Settings移除cf-aig-collect-log: false请求头该头值为false时会跳过本条请求的日志采集默认行为是记录日志参考 功能文档 Logging等待 3060 秒日志延迟正常窗口检查日志容量上限默认上限为 1000 万条即 10M。补充说明如果启用了Zero Data Retention零数据保留prompt/response 不会落库但请求计数与成本仍会统计功能文档。若你的场景要求隐私优先日志面板里看不到请求体属于预期行为此时应改看请求数、成本等聚合指标而不是日志明细。每条日志记录的字段包括prompt、response、provider、model、tokens、cost、duration、cache status、metadata功能文档日志条目说明。需要长期留存或跨平台分析时可用 Logpush 导出到 S3、GCS、Datadog、Splunk 等目标详见下文分析一节。Debugging用 curl 与响应头定位故障原文档提供了两组调试手段连通性测试与响应头检查。连通性测试curl一次调用同时带上提供商鉴权与网关鉴权两个头用于区分是哪一层拒绝了请求# Test connectivity curl -v https://gateway.ai.cloudflare.com/v1/{account}/{gateway}/openai/models \ -H Authorization: Bearer $OPENAI_KEY \ -H cf-aig-authorization: Bearer $CF_TOKEN排障解读返回 401 → 问题在cf-aig-authorization网关 Token 缺失或错误返回 403 → 问题在提供商侧$OPENAI_KEY无效或 BYOK 过期返回 200 但行为异常缓存/日志不对→ 问题在网关配置层继续看响应头。-v会打印完整请求/响应头便于观察cf-aig-cache-status、cf-ray等关键字段。响应头检查TypeScript// Check response headers console.log(Cache:, response.headers.get(cf-aig-cache-status)); console.log(Request ID:, response.headers.get(cf-ray));cf-aig-cache-statusHIT/MISS验证缓存是否按预期工作cf-rayCloudflare 的请求 ID当需要向支持团队反馈或对照日志时这是唯一定位单条请求的凭据。两种方式配合使用curl 验证连通性与鉴权响应头验证缓存与追踪基本能覆盖 90% 的接入问题。Analytics用指标与过滤器做数据级排障原文档指出分析面板入口为Dashboard → AI Gateway → Select gateway这是排查生产问题的终极手段——用聚合数据反向验证单请求层面的判断。核心指标MetricsRequests请求量总量与趋势TokensToken 用量输入/输出 Token 消耗Latency延迟p50 / p95 / p99 三个分位延迟p99 飙升通常指向特定提供商或特定路径Cache hit rate缓存命中率验证缓存策略是否有效Costs成本按模型/提供商统计的开销。日志过滤器Log filters过滤器示例用途status: error筛选所有出错请求快速定位错误码分布provider: openai只看指定提供商的请求cost 0.01筛出成本超过阈值的请求定位高开销调用duration 1000筛出耗时超过 1000ms 的慢请求排查延迟问题这四个过滤器可以组合使用例如provider: openai AND status: error AND duration 1000实现多条件联合定位。数据导出Export需要长期留存、告警或与自有可观测体系打通时使用Logpush将日志导出到 S3、GCS、Datadog、Splunk 等目标。导出后可以在你的 BI/监控系统中做原网关面板无法覆盖的交叉分析比如按业务线聚合成本、做异常检测告警。从排障文档看网关最佳实践结合 AI Gateway 功能文档的最佳实践 与 配置文档最佳实践可以归纳出一套少踩坑的基线配置作为排障的上游防线生产环境一律启用网关认证cf-aig-authorization杜绝开放网关被滥用导致限流误伤优先 BYOK 或统一计费把密钥移出代码wrangler secret put管理敏感变量参考 配置文档 Wrangler 集成按环境拆分网关dev / staging / prod避免开发流量污染生产缓存与限流配额设置限流防止密钥泄露或流量异常导致成本失控限流有固定窗口与滑动窗口两种算法滑动窗口更精确参考 功能文档开启日志为事后排障保留现场注意默认上限 10M 条重要网关配合 Logpush 导出确定性 prompt 启用缓存非确定性场景含流式不要依赖缓存涉及敏感数据时开启 Zero Data Retention但需接受日志明细不可见的代价对用户可见的 AI 功能开启 Guardrails 与 DLPGuardrails 支持 Flag 与 Block 两种动作DLP 可检测邮箱、SSN、信用卡等 PII 并支持 Flag / Block / Redact参考 功能文档从源头减少需要排障的异常输入。排障决策速查最后把全文内容收敛成一张决策表供接入或排障时直接对照症状首要检查项对应修复401是否带cf-aig-authorization头、Token 权限补头确认 Token 具备AI Gateway - Read403提供商密钥BYOK/透传状态Provider Keys 页面更换/续期密钥429网关限流配置、上游限流提高限流阈值或指数退避重试按用户限额需动态路由缓存全 MISS流式skip-cache 头参数一致性关流式去 skip-cache统一请求参数缓存 HIT 但内容错误自定义缓存键是否唯一换用语义唯一键如greeting-en日志缺失开关、cf-aig-collect-log头、延迟窗口、10M 上限开启日志移除false头等待 3060s导出归档统一 API 报错模型名是否带提供商前缀写openai/gpt-4o而非gpt-4o单请求无法定位cf-ray请求 ID 分析面板过滤器用status/provider/cost/duration组合过滤掌握这条状态码 → 响应头 → 分析面板的排障链路后配合本技能目录下的 AI Gateway 主文档、配置文档、功能文档、动态路由文档 与 SDK 集成文档即可独立完成 AI Gateway 从接入、优化到生产排障的完整闭环。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
