熔断器配置

熔断器（Circuit Breaker）是 Claude Code Hub 的核心保护机制，用于自动检测和隔离故障供应商，防止级联失败影响整体服务可用性。本文档详细介绍熔断器的工作原理、配置参数和最佳实践。

概述

熔断器模式源自电路保护器的设计思想：当检测到异常时自动"断开"，保护系统免受持续故障的影响。在 Claude Code Hub 中，每个供应商都有独立的熔断器实例，当某个供应商连续失败达到阈值时，熔断器会自动"打开"，后续请求将跳过该供应商，转而使用其他可用供应商。

状态机详解

熔断器采用三态状态机模型，通过状态转换实现故障检测和自动恢复。

状态转换图

                    失败次数 >= 阈值
        ┌───────────────────────────────────────┐
        │                                       ▼
    ┌───────┐                             ┌─────────┐
    │CLOSED │                             │  OPEN   │
    │ 正常  │                             │  熔断   │
    └───┬───┘                             └────┬────┘
        │                                      │
        │ 成功次数 >= 恢复阈值                  │ 熔断时间到期
        │                                      ▼
        │                               ┌───────────┐
        └───────────────────────────────│ HALF-OPEN │
                                        │   探测    │
                                        └───────────┘

CLOSED（关闭/正常）状态

这是熔断器的默认状态，表示供应商运行正常。

状态特征：

• 所有请求正常转发到该供应商
• 系统持续监控请求成功/失败情况
• 每次成功请求会重置失败计数器

状态转换条件：

• 当失败次数累计达到 circuitBreakerFailureThreshold 时，转换到 OPEN 状态

OPEN（打开/熔断）状态

当供应商连续失败达到阈值后，熔断器进入此状态，起到保护作用。

状态特征：

• 请求不会转发到该供应商（被选择器跳过）
• 系统会自动选择其他可用供应商
• 状态持续 circuitBreakerOpenDuration 毫秒

状态转换条件：

• 当熔断持续时间到期后，自动转换到 HALF-OPEN 状态
• 管理员可通过手动重置立即关闭熔断器

HALF-OPEN（半开/探测）状态

熔断时间到期后的过渡状态，用于验证供应商是否已恢复正常。

状态特征：

• 允许少量请求通过，测试供应商是否恢复
• 系统会记录这些探测请求的成功/失败情况
• 根据探测结果决定后续状态

状态转换条件：

• 连续成功次数达到 circuitBreakerHalfOpenSuccessThreshold 时，转换到 CLOSED 状态
• 如果探测请求失败，重新转换到 OPEN 状态

配置参数

熔断器支持供应商级别的独立配置，可在供应商管理页面为每个供应商设置不同的参数。

circuitBreakerFailureThreshold

失败阈值 - 触发熔断所需的连续失败次数。

说明：

• 较低的阈值（如 3）可以更快检测到故障，但可能导致误熔断
• 较高的阈值（如 10）更保守，但故障检测速度较慢
• 建议根据供应商的稳定性历史进行调整

circuitBreakerOpenDuration

熔断持续时间 - 熔断器保持 OPEN 状态的时长（毫秒）。

说明：

• 较短的持续时间可以更快恢复服务，但可能频繁尝试仍不可用的供应商
• 较长的持续时间更保守，但恢复速度较慢
• 可结合智能探测功能实现更快的恢复

circuitBreakerHalfOpenSuccessThreshold

恢复阈值 - HALF-OPEN 状态下需要连续成功的次数才能关闭熔断器。

说明：

• 较低的阈值（如 1）可以更快恢复正常
• 较高的阈值（如 5）可以更充分验证供应商确实已恢复

自定义熔断规则

可以自定义熔断规则吗？ 答案是：可以。Claude Code Hub 支持为每个供应商独立配置熔断器参数，满足不同场景的需求。

配置位置

熔断器参数在供应商管理页面配置：

路径： 设置 > 供应商管理 > 编辑供应商 > 熔断器配置

配置步骤

1. 进入「设置」页面，点击「供应商管理」
2. 找到需要配置的供应商，点击编辑按钮
3. 展开「熔断器配置」折叠区域
4. 根据需求调整以下参数：
   • 失败阈值：触发熔断所需的连续失败次数
   • 熔断时间：熔断器保持打开状态的时长（分钟）
   • 恢复阈值：半开状态下需要连续成功的次数
5. 点击「保存」按钮完成配置

参数输入范围

在 UI 界面中，各参数的允许输入范围如下：

配置示例

场景一：高稳定性要求

适用于核心业务供应商，需要更保守的熔断策略：

场景二：快速恢复

适用于备用供应商，希望尽快恢复服务：

场景三：敏感检测

适用于付费 API 供应商，需要快速发现问题：

配置生效机制

• 即时生效：配置保存后立即生效，无需重启服务
• 配置缓存：配置会缓存在内存中（5 分钟 TTL），减少数据库查询
• Redis 同步：配置同时缓存到 Redis，支持多实例部署场景
• 降级策略：Redis 不可用时自动从数据库读取配置

网络错误处理

网络错误（如 DNS 解析失败、连接超时、代理连接失败）与供应商错误（HTTP 4xx/5xx）有本质区别。系统提供配置选项来控制网络错误是否计入熔断器。

ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS

环境变量配置 - 控制网络错误是否计入熔断器失败计数。

配置示例：

# 默认关闭：网络错误不计入熔断器
ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS=false

# 启用：网络错误也计入熔断器
ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS=true

网络错误类型

系统识别的网络错误包括：

配置建议

默认关闭（推荐用于不稳定网络环境）：

• 适用于使用代理的场景
• 适用于跨境网络环境
• 避免因临时网络抖动触发熔断

启用（适用于稳定网络环境）：

• 适用于网络稳定的内网环境
• 连续网络错误也应触发熔断保护
• 避免持续请求不可达的供应商

HTTP 404 错误处理

上游供应商返回 HTTP 404 错误时，系统采用特殊的处理策略：触发供应商故障切换，但不计入熔断器失败计数。

处理逻辑

1. 检测 404 错误：当上游供应商返回 HTTP 404 状态码时，系统识别为「资源未找到」错误
2. 触发故障切换：系统将该供应商加入当前请求的失败列表，避免重复选择
3. 不计入熔断器：404 错误不会增加熔断器的失败计数，不影响供应商的健康状态

设计理由

HTTP 404 错误通常意味着特定供应商不支持请求的模型或资源，而非供应商本身出现故障。例如：

• 供应商尚未部署最新模型
• 模型名称与供应商支持的版本不匹配
• 某些端点在特定供应商上不可用

将 404 计入熔断器可能导致正常供应商被误熔断，影响其处理其他模型请求的能力。

决策链标识

在请求日志的供应商决策链中，404 错误会以 resource_not_found 标识：

[1234ms] Provider-A 请求失败
         - 状态码：404
         - 原因：resource_not_found
         - 备注：不计入熔断器
[1240ms] 触发故障切换，重新选择供应商

智能探测

智能探测（Smart Probing）是一项可选功能，当熔断器处于 OPEN 状态时，系统会定期主动探测供应商，实现更快的故障恢复。

工作原理

1. 定期检查所有处于 OPEN 状态的熔断器
2. 使用轻量级测试请求探测供应商可用性
3. 探测成功则提前将熔断器转为 HALF-OPEN 状态
4. 允许真实请求逐步验证供应商恢复情况

配置参数

ENABLE_SMART_PROBING

启用智能探测 - 控制是否启用智能探测功能。

PROBE_INTERVAL_MS

探测间隔 - 探测周期的时间间隔（毫秒）。

PROBE_TIMEOUT_MS

探测超时 - 单次探测请求的超时时间（毫秒）。

配置示例：

# 启用智能探测
ENABLE_SMART_PROBING=true

# 每 30 秒探测一次
PROBE_INTERVAL_MS=30000

# 探测超时 5 秒
PROBE_TIMEOUT_MS=5000

状态存储

熔断器使用内存存储运行时状态，配置信息缓存在 Redis 中以优化性能。

内存存储

每个供应商的健康状态存储在内存中：

interface ProviderHealth {
  failureCount: number;           // 当前失败计数
  lastFailureTime: number | null; // 最后失败时间戳
  circuitState: "closed" | "open" | "half-open";  // 当前状态
  circuitOpenUntil: number | null;  // 熔断结束时间戳
  halfOpenSuccessCount: number;     // 半开状态成功计数
  config: CircuitBreakerConfig | null;  // 缓存的配置
  configLoadedAt: number | null;    // 配置加载时间
}

Redis 状态同步增强（v0.3.24+）

v0.3.24 版本引入了更智能的 Redis 状态同步机制，优化了多实例部署场景下的状态一致性和性能。

智能同步策略

系统采用「内存优先，Redis 持久化」的混合存储架构：

设计原理：

• CLOSED 状态：表示供应商正常，无需频繁同步。仅在首次加载时检查 Redis，之后依赖内存状态
• OPEN/HALF-OPEN 状态：可能被管理员通过后台手动重置。每次访问都检查 Redis，确保重置操作能够及时生效

外部重置同步机制

当管理员通过后台手动重置熔断器时，系统能够自动检测并同步状态：

1. 管理员操作：在可用性监控页面点击「重置」按钮
2. Redis 更新：Redis 中对应供应商的状态被清除或更新为 CLOSED
3. 内存同步：下次访问该供应商时，系统检测到 Redis 状态已变更，自动将内存状态重置为 CLOSED

管理后台重置 → Redis 状态清除 → 内存检测到差异 → 自动重置为 CLOSED

loadedFromRedis 标记机制

系统使用 loadedFromRedis 集合跟踪已从 Redis 加载过状态的供应商：

• 首次访问：供应商 ID 不在集合中，从 Redis 加载状态
• 后续访问：
  • CLOSED 状态：直接使用内存状态，不再查询 Redis
  • OPEN/HALF-OPEN 状态：仍然检查 Redis（可能被外部重置）
• 强制刷新：调用 getAllHealthStatusAsync 时可传入 forceRefresh: true 清除标记，强制从 Redis 重新加载

批量加载优化

getAllHealthStatusAsync 函数支持批量加载多个供应商的健康状态，减少 Redis 查询次数：

// 批量获取供应商健康状态
const healthStatus = await getAllHealthStatusAsync(providerIds, {
  forceRefresh: true  // 强制从 Redis 刷新
});

参数说明：

使用场景：

• 管理后台：展示所有供应商的熔断器状态时，使用 forceRefresh: true 确保显示最新状态
• 请求路由：路由选择时使用默认参数，优先使用内存缓存以提升性能

性能优化：

• 使用 Promise.allSettled 并行加载所有供应商状态
• 仅对需要刷新的供应商发起 Redis 查询
• 单次批量操作替代多次单独查询

Redis 配置缓存

供应商的熔断器配置缓存在 Redis 中，键格式为：

circuit_breaker:config:{providerId}

存储内容：

HSET circuit_breaker:config:1
  failureThreshold "5"
  openDuration "1800000"
  halfOpenSuccessThreshold "2"

缓存策略：

监控与告警

熔断器状态监控

可通过以下方式监控熔断器状态：

1. 可用性监控页面 - 查看供应商健康状态和熔断器状态
2. 日志查看 - 搜索 [CircuitBreaker] 关键字查看状态变化
3. API 查询 - 通过 Server Actions 获取供应商健康信息

Webhook 通知

系统支持通过企业微信机器人发送熔断告警通知。

配置位置： 设置 > 通知设置 > 熔断器告警

告警内容包含：

• 供应商名称和 ID
• 触发熔断的失败次数
• 预计恢复时间
• 最后一次错误信息

防重复机制：

• 同一供应商 5 分钟内只发送一次告警
• 使用 Redis 缓存实现告警去重

最佳实践

稳定网络配置

适用于网络稳定的生产环境：

# 网络错误计入熔断器
ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS=true

# 启用智能探测
ENABLE_SMART_PROBING=true
PROBE_INTERVAL_MS=30000
PROBE_TIMEOUT_MS=5000

供应商配置建议：

不稳定网络配置

适用于使用代理或跨境网络环境：

# 网络错误不计入熔断器（避免误熔断）
ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS=false

# 启用智能探测（加速恢复）
ENABLE_SMART_PROBING=true
PROBE_INTERVAL_MS=60000
PROBE_TIMEOUT_MS=10000

供应商配置建议：

多供应商配置

当配置多个供应商时，建议采用差异化配置：

主要供应商（高权重）：

• 失败阈值：5-7（相对保守）
• 熔断时长：1800000（30 分钟）
• 原因：主要供应商承载大部分流量，需要更稳定的熔断策略

备用供应商（低权重）：

• 失败阈值：3-5（更敏感）
• 熔断时长：900000（15 分钟）
• 原因：备用供应商可以更快熔断和恢复，为主供应商故障时提供保障

故障排查

熔断器频繁打开

可能原因：

1. 供应商确实不稳定
2. 失败阈值设置过低
3. 网络问题被误判为供应商错误

排查步骤：

1. 查看请求日志，分析失败原因（HTTP 状态码、错误信息）
2. 检查是否为网络错误，考虑关闭 ENABLE_CIRCUIT_BREAKER_ON_NETWORK_ERRORS
3. 适当提高失败阈值

熔断器不生效

可能原因：

1. 熔断器配置未正确保存
2. Redis 配置缓存过期未更新
3. 应用刚重启，状态被重置

排查步骤：

1. 检查供应商配置页面的熔断器参数
2. 查看日志中的 [CircuitBreaker] 记录
3. 清除 Redis 缓存或等待缓存过期（5 分钟）

智能探测不工作

可能原因：

1. ENABLE_SMART_PROBING 未设置为 true
2. 没有处于 OPEN 状态的熔断器
3. 探测超时时间过短

排查步骤：

1. 检查环境变量配置
2. 查看日志中的 [SmartProbe] 记录
3. 适当增加 PROBE_TIMEOUT_MS

相关功能

• 可用性监控 - 查看供应商健康状态
• 供应商管理 - 配置熔断器参数
• 通知设置 - 配置熔断告警通知
• 请求日志 - 分析请求失败原因