Argo Smart Routing 常见陷阱

## 最佳实践总结 **Smart Shield 说明：** Argo 智能路由正在演进为 Smart Shield。以下最佳实践仍然适用；请监控 Cloudflare 更新日志以获取 Smart Shield 的最新信息。 1. **始终检查可编辑性**：在尝试启用/禁用 Argo 之前 2. **设置计费通知**：避免意外成本 3. **结合分层缓存 (Tiered Cache)**：以获得最大性能收益 4. **仅在生产环境使用**：开发/测试环境禁用以控制成本 5. **监控分析**：48 小时内需要 500+ 请求才能获取详细指标 6. **优雅处理错误**：检查计费、权限、域名兼容性 7. **测试配置变更**：在生产环境前先在测试环境测试 8. **使用 TypeScript SDK**：以获得类型安全和更好的开发体验 9. **实现重试逻辑**：在生产系统中调用 API 时 10. **记录域名特定设置**：以便团队可见 ## 常见错误 ### "Argo unavailable" **问题：** API 返回错误 "Argo Smart Routing is unavailable for this zone" **原因：** 域名不符合资格或未设置计费 **解决方案：** 1. 验证域名是否为企业版或更高计划 2. 检查 Account → Billing 中是否已配置计费 3. 确保支付方式有效且处于最新状态 4. 如果资格不明确，请联系 Cloudflare 支持 ### "Cannot enable/disable" **问题：** API 调用成功但状态未更改，或 GET 响应中显示 `editable: false` **原因：** 权限不足或域名限制 **解决方案：** 1. 检查 API 令牌是否具有 `Zone:Argo Smart Routing:Edit` 权限 2. 在尝试 PATCH 之前，验证 GET 响应中是否为 `editable: true` 3. 如果 `editable: false`，请检查： - 账户是否已配置计费 - 域名计划是否包含 Argo (Enterprise+) - 域名没有处于挂起或暂停状态 - API 令牌具有正确的范围 ### `editable: false` 错误 **问题：** GET 请求返回 `"editable": false`，导致无法启用/禁用 **原因：** 来自计费、计划或权限的域名级限制 **解决方案模式：** typescript const status = await client.argo.smartRouting.get({ zone_id: zoneId }); if (!status.editable) { // 不要尝试修改 - 会失败 console.error('无法修改 Argo 设置:'); console.error('- 检查计费是否已配置'); console.error('- 验证域名是否为 Enterprise+ 计划'); console.error('- 确认 API 令牌具有编辑权限'); throw new Error('此域名无法编辑 Argo 设置'); } // 可以安全地进行启用/禁用操作 await client.argo.smartRouting.edit