User Guide

容错配置

重试、超时和故障转移设置

容错配置

容错配置帮助你的应用优雅地处理 API 故障,确保服务稳定性。

重试机制

重试配置

选项默认值说明
最大重试次数3失败后重试的最大次数
初始延迟1s首次重试前的等待时间
最大延迟30s重试延迟的上限
退避倍数2每次重试延迟的增长倍数

退避策略

第1次重试: 1s
第2次重试: 2s
第3次重试: 4s
...

可重试错误

以下错误会触发重试:

  • 网络超时
  • 连接失败
  • 5xx 服务器错误
  • 429 速率限制

不重试的错误:

  • 4xx 客户端错误(除 429)
  • 认证失败
  • 无效请求

超时设置

超时配置

选项默认值说明
连接超时10s建立连接的超时时间
请求超时120s整个请求的超时时间
流式超时300s流式响应的超时时间

按 Provider 配置

可以为不同 Provider 设置不同的超时:

timeouts:
  default:
    connect: 10s
    request: 120s
  kiro-claude:
    request: 180s  # Claude 响应较慢
  gemini-cli:
    request: 60s   # Gemini 响应较快

故障转移

自动故障转移

当主 Provider 失败时,自动切换到备用 Provider:

  1. 主 Provider 请求失败
  2. 检查是否有可用的备用 Provider
  3. 使用备用 Provider 重试请求
  4. 记录故障转移事件

配置故障转移

failover:
  enabled: true
  providers:
    - kiro-claude      # 主 Provider
    - claude-custom    # 备用 Provider 1
    - gemini-cli       # 备用 Provider 2
  maxAttempts: 3       # 最大尝试 Provider 数

故障转移条件

条件说明
连接失败无法连接到 Provider
认证失败Token 过期或无效
速率限制达到 Provider 限制
服务不可用Provider 返回 503

熔断器

熔断器状态

状态说明
关闭正常工作,请求通过
打开熔断激活,请求直接失败
半开尝试恢复,允许部分请求

熔断配置

选项默认值说明
失败阈值5触发熔断的连续失败次数
恢复时间30s熔断后尝试恢复的等待时间
半开请求数3半开状态允许的测试请求数

熔断流程

正常 → 连续失败5次 → 熔断打开
熔断打开 → 等待30s → 半开状态
半开状态 → 3次成功 → 恢复正常
半开状态 → 1次失败 → 重新熔断

监控告警

告警条件

  • 错误率超过阈值
  • 延迟超过阈值
  • 熔断器打开
  • 所有 Provider 不可用

告警通知

当前支持:

  • 应用内通知
  • 系统通知(macOS/Windows)