供应商管理

供应商管理是 Claude Code Hub 最核心的功能之一，用于添加、配置和管理上游 AI 服务供应商。通过合理配置供应商的权重、优先级和分组，您可以实现智能负载均衡、故障转移和成本优化。

页面概览

供应商管理页面位于 设置 > 供应商管理 (/settings/providers)，提供以下功能：

• 供应商列表：展示所有已配置的供应商及其状态
• 搜索与筛选：按类型、名称、URL 或分组快速查找供应商
• 排序功能：按优先级、权重、名称或创建时间排序
• 新增供应商：添加新的 AI 服务供应商
• 调度规则说明：了解系统如何选择供应商

独立管理页面入口

除了通过设置页面访问外，管理员还可以通过 仪表盘 > 供应商 (/dashboard/providers) 快捷访问供应商管理功能。该页面：

• 仅管理员可访问：非管理员用户访问时会被自动重定向到登录页或仪表盘首页
• 复用核心组件：使用与设置页面相同的 ProviderManagerLoader 组件，功能完全一致
• 快捷操作入口：页面顶部包含添加供应商、调度规则说明、排行榜等操作入口

该入口适合需要频繁管理供应商的管理员用户，无需进入设置页面即可快速进行供应商配置。

供应商列表

列表展示

每个供应商卡片包含以下信息：

搜索与筛选

页面顶部提供三个筛选工具：

1. 类型筛选：按供应商类型筛选（全部、Claude、Codex、Gemini 等）
2. 排序方式：按优先级、权重、名称、实际使用优先级或创建时间排序
3. 搜索框：根据名称、URL 或分组标签进行模糊搜索

排序选项

实际使用优先级排序

成本倍数自动排序优先级

示例：

创建供应商

点击页面右上角的「新增服务商」按钮，打开供应商创建表单。

创建流程

1. 点击「新增服务商」按钮
2. 填写基础信息（名称、类型、URL、API Key）
3. 配置调度参数（权重、优先级、分组）
4. 根据需要配置高级选项（限流、代理、模型重定向等）
5. 点击「保存」完成创建

创建成功后，新供应商会自动出现在列表中。

编辑供应商

点击供应商卡片右侧的编辑图标（铅笔图标）可修改供应商配置。编辑表单与创建表单字段相同，所有配置项均可修改。

可编辑内容

• 基础信息（名称、URL、API Key）
• 调度参数（权重、优先级、分组标签）
• 启用状态
• 限流配置（RPM、并发数、成本限制）
• 超时配置
• 代理设置
• 模型重定向规则
• 熔断器配置
• Cache TTL 偏好设置
• IP 透传设置

克隆供应商

点击供应商卡片右侧的复制图标可快速克隆一个供应商。克隆功能会复制原供应商的所有配置，您只需修改名称和 API Key 即可创建新供应商。

启用与禁用

每个供应商卡片右侧有一个开关，用于快速启用或禁用供应商。

• 启用：供应商参与请求调度
• 禁用：供应商被排除在调度之外，但配置保留

删除供应商

点击供应商卡片右侧的删除图标（垃圾桶图标）可删除供应商。

删除确认对话框会显示即将删除的供应商名称，请仔细确认后再执行。

连接测试

供应商编辑表单中提供「测试连接」功能，用于验证供应商配置是否正确。该功能不仅验证连接是否可用，还提供详细的诊断信息。

基础验证项

• API 端点是否可访问
• API Key 是否有效
• 代理配置是否正确（如有配置）
• 响应延迟是否在可接受范围内
• 响应内容是否符合预期

预置检测模板

系统为不同类型的供应商预置了多套检测模板，这些模板模拟真实 CLI 客户端的请求特征：

Claude 类型供应商

Codex / OpenAI 兼容类型供应商

客户端限制兼容性

这是因为检测请求完全模拟真实客户端的特征：

除了 User-Agent，检测请求还包含：

• 完整的请求头特征（Accept、Accept-Language、Accept-Encoding 等）
• 真实 CLI 格式的请求体结构
• 标准的 metadata 字段（如 Claude 的 user_id）

因此，即使您使用的是仅对官方客户端开放的转发服务，检测功能也能正常验证连接状态。

三层验证机制

检测功能采用三层验证机制，确保供应商不仅能连接，而且性能达标：

第一层：HTTP 状态码验证

• 通过：2xx/3xx 状态码
• 失败：
  • 401/403：认证错误（API Key 无效或权限不足）
  • 429：请求频率限制
  • 400：请求格式错误
  • 5xx：服务端错误

第二层：延迟阈值验证

• 绿色：延迟低于阈值（默认 5000ms）
• 黄色：延迟超过阈值，供应商可用但性能降级

第三层：内容验证

• 检查响应体是否包含预期的关键字（如 pong 或 isNewTopic）
• 可通过模板默认值或自定义配置指定检测关键字

检测结果状态

错误类型分类

当检测失败时，系统会对错误进行分类以帮助诊断：

使用建议

1. 新增供应商时：先使用 cc_base（Claude）或 cx_base（Codex）进行快速验证
2. 验证高级功能时：使用 cc_sonnet 测试提示缓存功能是否正常
3. 自定义检测：如需特殊验证，可切换到自定义模式编写 JSON payload

熔断器管理

当供应商因连续错误触发熔断器后，列表中会显示红色的「已熔断」标签。

熔断状态

• 已熔断：供应商暂时被排除在调度之外，等待自动恢复
• 恢复中：熔断器处于半开状态，尝试有限的请求以验证恢复

手动重置

如果确认供应商已恢复正常，可以点击旋转图标手动重置熔断器，让供应商立即参与调度。

Cache TTL 偏好设置

Cache TTL 偏好设置用于覆写客户端请求中 cache_control 的 ephemeral 类型缓存时长。该功能适用于 Claude 类型供应商。

配置选项

配置层级与优先级

系统支持多层级的 Cache TTL 配置，优先级从高到低为：

1. Key 配置：在 API Key 级别设置的 Cache TTL 偏好
2. Provider 配置：在供应商级别设置的 Cache TTL 偏好
3. 客户端请求：客户端原始请求中的缓存设置

系统会按优先级依次检查，使用第一个非 inherit 的有效值。如果所有层级都设置为 inherit 或未设置，则保持客户端请求的原始值。

应用场景

当客户端请求的消息内容块包含 cache_control: { type: "ephemeral" } 时，系统会根据配置的 TTL 偏好自动添加 ttl 字段：

{
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m"
  }
}

字段位置

在供应商编辑表单的「高级设置」区域中，可以找到「Cache TTL 偏好」下拉选择框。

1M 上下文窗口配置

1M 上下文窗口功能允许 Claude Sonnet 模型处理更长的上下文（最高 100 万 Token）。该配置项用于控制供应商是否启用此功能。

支持的模型

1M 上下文窗口功能仅对以下 Sonnet 模型生效：

• claude-sonnet-4-5（及其日期版本变体，如 claude-sonnet-4-5-20250929）
• claude-sonnet-4（及其日期版本变体，如 claude-sonnet-4-20250514）

配置选项

调度行为

当客户端请求 1M 上下文窗口时（通过 anthropic-beta 头），系统会在供应商选择阶段过滤掉 context1mPreference = disabled 的供应商，确保请求被路由到支持 1M 上下文的供应商。

分层定价说明

启用 1M 上下文窗口后，Token 计费采用分层定价模式：

示例：对于 claude-sonnet-4 模型（标准价格 $3/MTok 输入，$15/MTok 输出）：

• 前 200k Token：输入 $3/MTok，输出 $15/MTok
• 超出 200k 的部分：输入 $6/MTok，输出 $22.50/MTok

字段位置

在供应商编辑表单的「高级设置 > 调度与路由」区域中，可以找到「1M 上下文窗口」下拉选择框。该选项仅对 Claude 类型（claude、claude-auth）供应商显示。

使用建议

1. 默认保持 inherit：大多数场景下，让客户端决定是否使用 1M 上下文即可
2. 成本敏感场景使用 disabled：如果希望某些供应商仅处理常规请求以控制成本，可设置为禁用
3. 强制启用需谨慎：force_enable 会对所有支持的模型启用 1M 上下文，可能增加成本

IP 透传设置

IP 透传功能允许将客户端的真实 IP 地址传递给上游供应商。该功能默认关闭，需要手动启用。

功能说明

启用 IP 透传后，系统会在转发请求时添加以下 HTTP 头：

配置位置

在供应商编辑表单的「高级设置」区域中，可以找到「透传客户端 IP」（preserveClientIp）开关。

IP 解析来源

系统会按以下顺序从请求头中解析客户端 IP：

1. x-forwarded-for
2. x-real-ip
3. x-client-ip
4. x-originating-ip
5. x-remote-ip
6. x-remote-addr

使用场景

• 审计需求：上游供应商需要记录真实客户端 IP 用于审计
• 限流策略：上游供应商基于客户端 IP 进行限流控制
• 地理位置：上游服务需要根据客户端地理位置提供服务

供应商分组功能

供应商分组功能用于将供应商划分到不同的组中，配合用户/Key 的分组限制，实现资源隔离和精细化访问控制。

分组标签字段

在供应商编辑表单中，「分组标签」（groupTag）字段用于指定供应商所属的分组。

多标签支持：分组标签支持逗号分隔的多标签格式，例如：

• cli - 单标签，仅用于 CLI 用户
• cli,chat - 多标签，同时服务 CLI 和聊天用户
• premium,enterprise - 多标签，服务高级和企业用户

分组匹配逻辑

当用户或 Key 配置了供应商分组限制时，系统采用交集匹配策略：

1. 将用户/Key 的分组限制拆分为标签数组
2. 将供应商的分组标签拆分为标签数组
3. 检查两个数组是否存在交集
4. 存在交集则匹配成功，供应商可用

示例：

严格隔离策略

严格隔离策略的规则：

1. 有分组限制的用户/Key：只能访问分组标签与其限制匹配的供应商
2. 无分组标签的供应商：在严格隔离下会被拒绝访问
3. 会话复用检查：即使是会话复用场景，也会重新验证分组匹配

被拒绝的场景：

• 用户配置了 providerGroup: "cli"，但供应商未设置 groupTag
• 用户配置了 providerGroup: "premium"，供应商设置了 groupTag: "cli,chat"（无交集）

分组优先级

用户和 Key 都可以配置分组限制，优先级为：

1. Key 的 providerGroup：优先级最高
2. User 的 providerGroup：Key 未设置时使用

这意味着可以为同一用户的不同 Key 配置不同的供应商分组权限。

配置建议

1. 规划分组体系：根据业务需求设计清晰的分组命名，如按用途（cli、chat、api）或按等级（free、premium、enterprise）
2. 为所有供应商设置标签：避免供应商因缺少标签而被严格隔离策略拒绝
3. 使用多标签提高灵活性：对于通用供应商，可设置多个标签以服务更多用户组
4. 测试分组配置：在正式使用前，验证分组隔离是否符合预期

调度规则说明

点击页面右上角的「调度规则」按钮，可查看系统选择供应商的详细逻辑。

核心调度逻辑

1. 优先级优先：系统首先选择优先级最高（数值最小）的供应商组
2. 权重分配：在同优先级组内，按权重比例随机分配请求
3. 健康过滤：自动排除已禁用、已熔断的供应商
4. 会话复用：5 分钟内的连续请求优先路由到同一供应商

使用场景

调度规则弹窗提供了多个实际场景示例，帮助您理解如何配置：

• 成本优先：如何配置主力供应商和备用供应商
• 用户分组：如何为不同用户组配置不同的供应商
• 高可用：如何配置多供应商实现故障转移
• 负载均衡：如何使用权重实现流量分配

供应商排行榜

点击页面右上角的「排行榜」按钮，可跳转到供应商维度的排行榜页面，查看各供应商的使用统计：

• 请求数量
• Token 消耗
• 成本消费
• 使用趋势

操作权限

最佳实践

配置建议

1. 至少配置两个供应商：确保主供应商故障时有备用方案
2. 合理设置优先级：将最稳定、性价比最高的供应商设为最高优先级
3. 使用权重实现负载均衡：对于同等质量的供应商，通过权重分配流量
4. 配置分组标签：为供应商设置分组标签，便于管理和用户分组绑定
5. 使用多标签提高灵活性：对通用供应商设置多个标签（如 cli,chat），使其服务更多用户组
6. 定期检查熔断状态：关注供应商健康状况，及时处理问题
7. 配置 Cache TTL：根据业务需求设置合适的缓存时长，优化成本

故障排查

如果供应商不可用，请检查：

1. 供应商是否已启用
2. API Key 是否正确且有效
3. URL 是否可访问（使用连接测试验证）
4. 是否触发了熔断器
5. 代理配置是否正确（如有使用代理）
6. 分组标签是否匹配（用户有分组限制时，供应商必须设置匹配的分组标签）

相关功能

• 供应商字段详解 - 了解各配置字段的详细说明
• 用户管理 - 为用户配置供应商分组
• 日志查询 - 查看供应商请求日志
• 排行榜 - 查看供应商使用排行
• 高可用机制 - 了解熔断器和故障转移机制