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：
- 主 Provider 请求失败
- 检查是否有可用的备用 Provider
- 使用备用 Provider 重试请求
- 记录故障转移事件
配置故障转移
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）