独家合作CubenceAI 中转平台立减 20%访问

Claude Code Hub

参考文档

供应商字段详解

本文档详细说明 Claude Code Hub 供应商（Provider）的所有配置字段，包括字段类型、默认值、取值范围和使用场景。这是管理员配置供应商时的核心参考文档。

供应商配置直接影响系统的路由策略、高可用性和成本控制。建议在修改关键字段前仔细阅读相关说明。

字段分类概览

供应商配置字段按功能分为以下几类：

分类说明关键字段
基础字段供应商的标识和连接信息id, name, url, key
调度字段控制请求路由和负载均衡weight, priority, costMultiplier, groupTag
限制字段并发和成本限制limitConcurrentSessions, limit5hUsd, limitDailyUsd
超时配置请求超时控制firstByteTimeoutStreamingMs, streamingIdleTimeoutMs
代理配置HTTP/SOCKS 代理设置proxyUrl, proxyFallbackToDirect
模型配置模型重定向和白名单modelRedirects, allowedModels
特性配置供应商特定功能codexInstructionsStrategy, mcpPassthroughType
熔断器配置故障隔离和恢复circuitBreakerFailureThreshold 等
元数据字段时间戳和软删除createdAt, updatedAt, deletedAt

基础字段

基础字段定义供应商的核心标识和连接信息。

字段说明

字段名类型必填默认值说明
idinteger-自增供应商唯一标识，系统自动生成
namestring是-供应商名称，用于显示和日志记录，最大 64 字符
descriptionstring否null供应商描述信息
urlstring是-API 端点地址，最大 255 字符，必须是有效 URL
keystring是-API 密钥，最大 1024 字符，存储时脱敏
isEnabledboolean否true是否启用供应商参与调度
providerTypeenum否claude供应商类型（见下表）
websiteUrlstring否null供应商官网地址，用于快速跳转
faviconUrlstring否null网站图标 URL，系统根据 websiteUrl 自动生成

供应商类型（providerType）

类型说明认证方式
claudeAnthropic 官方 APIx-api-key 头 + Bearer Token
claude-authClaude 中转服务仅 Bearer Token
codexOpenAI Codex/Response APIBearer Token
geminiGoogle Gemini APIAPI Key
gemini-cliGemini CLI 格式API Key
openai-compatibleOpenAI 兼容 APIBearer Token

配置示例

{
  "name": "官方 Claude API",
  "url": "https://api.anthropic.com",
  "key": "sk-ant-api03-xxx...",
  "providerType": "claude",
  "isEnabled": true,
  "websiteUrl": "https://console.anthropic.com"
}

API Key 在数据库中以明文存储。生产环境请确保数据库访问受到严格限制。

调度相关字段

调度字段控制系统如何选择供应商处理请求，是实现智能负载均衡的核心。

字段说明

字段名类型默认值范围说明
weightinteger11-100权重，同优先级内按权重比例分配流量
priorityinteger00-2147483647优先级，数值越小越优先被选择
costMultiplierdecimal1.0>= 0成本系数，用于调整该供应商的成本计算
groupTagstringnull最大 50 字符分组标签，用于用户分组绑定

调度算法说明

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

权重（weight）

权重决定了同优先级供应商之间的流量分配比例：

供应商A (weight=70) + 供应商B (weight=30)
→ A 获得 70% 流量，B 获得 30% 流量

权重范围为 1-100，建议使用整十数值（如 10、20、50）便于理解和计算。

优先级（priority）

优先级用于实现主备切换和故障转移：

配置场景主供应商 priority备用供应商 priority
主备模式010
三级容灾010 / 20
负载均衡相同值相同值

成本系数（costMultiplier）

成本系数用于调整供应商的计费计算，常见场景：

  • 中转站优惠：设为 0.8 表示 8 折计费
  • 溢价供应商：设为 1.2 表示 120% 成本
  • 内部渠道：设为 0 表示免费（不计入成本统计）

分组标签（groupTag）

分组标签用于将供应商划分到不同组，配合用户的 providerGroup 实现：

  • 用户隔离：不同用户组使用不同供应商池
  • 资源分配：VIP 用户使用高优供应商
  • 成本控制：按部门分配不同供应商

配置示例

{
  "name": "主力供应商",
  "weight": 80,
  "priority": 0,
  "costMultiplier": 1.0,
  "groupTag": "production"
}

限制字段

限制字段用于控制供应商的并发使用和成本消耗。

字段说明

字段名类型默认值范围说明
limitConcurrentSessionsinteger00-1000并发 Session 上限，0 表示不限制
limit5hUsddecimalnull0-100005 小时消费上限（美元），null 不限制
limitDailyUsddecimalnull0-10000每日消费上限（美元），null 不限制
dailyResetModeenumfixedfixed/rolling每日限制重置模式
dailyResetTimestring00:00HH:mm 格式固定模式的重置时间点
limitWeeklyUsddecimalnull0-50000每周消费上限（美元），null 不限制
limitMonthlyUsddecimalnull0-200000每月消费上限（美元），null 不限制

并发限制（limitConcurrentSessions）

控制同时活跃的会话数量，防止单供应商过载：

  • 0：不限制并发
  • 正整数：最大允许的同时活跃会话数

并发限制生效需要 Redis 可用。Redis 不可用时会 Fail-Open（允许请求）。

成本限制时间窗口

限制类型窗口周期说明
5 小时限制滚动 5 小时防止短时间内大量消费
每日限制固定/滚动 24 小时控制每日支出
每周限制自然周（周一至周日）周期性成本控制
每月限制自然月月度预算管理

每日重置模式（dailyResetMode）

模式说明使用场景
fixed在指定时间点重置与工作时间对齐
rolling滚动 24 小时窗口持续平滑限制

配置示例

{
  "limitConcurrentSessions": 50,
  "limit5hUsd": 100,
  "limitDailyUsd": 500,
  "dailyResetMode": "fixed",
  "dailyResetTime": "00:00",
  "limitWeeklyUsd": 2000,
  "limitMonthlyUsd": 8000
}

成本限制基于实时计算的消费金额。当达到限制时，供应商会被临时排除在调度之外，直到窗口重置。

超时配置

超时配置用于控制与上游供应商的请求超时行为。

字段说明

字段名类型默认值范围说明
firstByteTimeoutStreamingMsinteger00 或 1000-180000流式首字节超时（毫秒）
streamingIdleTimeoutMsinteger00 或 60000-600000流式空闲超时（毫秒）
requestTimeoutNonStreamingMsinteger00 或 60000-1800000非流式总超时（毫秒）

值为 0 表示不设置超时限制。非零值必须在指定范围内。

流式首字节超时（firstByteTimeoutStreamingMs）

控制从发起请求到收到首个响应字节的最大等待时间：

  • 作用：解决流式请求启动缓慢问题
  • 场景：供应商响应延迟过高时快速切换
  • 推荐值：30000（30 秒）

流式空闲超时（streamingIdleTimeoutMs）

控制流式响应中两次数据块之间的最大间隔：

  • 作用：解决流式中途卡住问题
  • 场景：检测供应商中途无响应
  • 推荐值：60000（60 秒）
  • 最小值：如果配置，最少为 60 秒

非流式总超时（requestTimeoutNonStreamingMs）

控制非流式请求的总处理时间：

  • 作用：防止长请求无限挂起
  • 场景：count_tokens 等非流式 API
  • 推荐值：120000（2 分钟）

配置示例

{
  "firstByteTimeoutStreamingMs": 30000,
  "streamingIdleTimeoutMs": 60000,
  "requestTimeoutNonStreamingMs": 120000
}

跨境网络环境建议适当增加超时时间，避免因网络延迟导致误判。

代理配置

代理配置用于通过 HTTP/HTTPS/SOCKS 代理访问上游供应商。

字段说明

字段名类型默认值说明
proxyUrlstringnull代理服务器地址，最大 512 字符
proxyFallbackToDirectbooleanfalse代理失败时是否降级为直连

代理 URL 格式

支持以下代理协议：

协议格式示例
HTTPhttp://proxy.example.com:8080
HTTPShttps://proxy.example.com:8080
SOCKS5socks5://proxy.example.com:1080
SOCKS4socks4://proxy.example.com:1080
带认证http://user:pass@proxy.example.com:8080

降级直连（proxyFallbackToDirect）

当代理连接失败时的处理策略：

  • false（默认）：代理失败直接返回错误
  • true：代理失败后尝试直接连接

启用降级直连可能导致请求绕过代理。如果代理是必须的（如合规要求），请保持关闭。

配置示例

{
  "proxyUrl": "http://192.168.1.100:7890",
  "proxyFallbackToDirect": true
}

模型配置

模型配置用于控制模型名称映射和访问限制。

字段说明

字段名类型默认值说明
modelRedirectsJSON objectnull模型名称重定向映射
allowedModelsJSON arraynull允许的模型列表
joinClaudePoolbooleanfalse是否加入 Claude 调度池

模型重定向（modelRedirects）

将请求中的模型名称映射到实际模型：

{
  "modelRedirects": {
    "claude-3-5-sonnet-20241022": "claude-3-5-sonnet-latest",
    "gpt-4": "claude-3-opus-20240229"
  }
}

使用场景：

  • 模型名称规范化
  • 模型版本升级过渡
  • 跨平台模型映射

允许模型列表（allowedModels）

根据供应商类型有不同语义：

供应商类型allowedModels 语义
claude/claude-auth白名单：仅允许调用列表中的模型
其他类型声明列表：供应商支持的模型列表
{
  "allowedModels": [
    "claude-3-5-sonnet-20241022",
    "claude-3-opus-20240229",
    "claude-3-haiku-20240307"
  ]
}
  • null 或空数组：不限制（允许所有模型）

加入 Claude 调度池（joinClaudePool）

即将上线

此功能正在开发中，尚未正式发布。

仅对非 Anthropic 类型供应商有效：

  • false（默认）：独立调度
  • true：配合 modelRedirects 加入 Claude 请求的调度池

启用此选项后，非 Claude 类型的供应商也可以参与处理 Claude 模型的请求（通过模型重定向）。

Codex 特殊配置

针对 Codex 类型供应商的专属配置。

字段说明

字段名类型默认值说明
codexInstructionsStrategyenumautoCodex instructions 处理策略

Instructions 处理策略

策略值说明使用场景
auto透传客户端 instructions，400 错误时自动重试（使用官方 instructions）默认推荐
force_official始终强制使用官方 Codex CLI instructions严格合规场景
keep_original始终透传客户端 instructions，不重试宽松的中转站

此配置仅对 providerType = 'codex' 的供应商生效。

配置示例

{
  "providerType": "codex",
  "codexInstructionsStrategy": "auto"
}

MCP 透传配置

MCP（Model Context Protocol）透传功能用于增强模型能力。

字段说明

字段名类型默认值说明
mcpPassthroughTypeenumnoneMCP 透传类型
mcpPassthroughUrlstringnullMCP 服务 URL，最大 512 字符

MCP 透传类型

类型值说明
none不启用 MCP 透传
minimax透传到 minimax MCP 服务（图片识别、联网搜索）
glm透传到智谱 MCP 服务（预留）
custom自定义 MCP 服务（预留）

配置示例

{
  "mcpPassthroughType": "minimax",
  "mcpPassthroughUrl": "https://api.minimaxi.com"
}

MCP 透传 URL 禁止使用内部网络地址（localhost、私有 IP 等）以防止 SSRF 攻击。

熔断器配置

熔断器用于隔离故障供应商，防止级联失败。

字段说明

字段名类型默认值范围说明
circuitBreakerFailureThresholdinteger51-100触发熔断的连续失败次数
circuitBreakerOpenDurationinteger18000001000-86400000熔断持续时间（毫秒）
circuitBreakerHalfOpenSuccessThresholdinteger21-10恢复需要的连续成功次数

熔断器状态

CLOSED（正常）
    ↓ 连续失败达到阈值
  OPEN（熔断）
    ↓ 等待 openDuration 后
HALF-OPEN（试探）
    ↓ 连续成功达到阈值 → CLOSED
    ↓ 发生失败 → OPEN

参数说明

  • 失败阈值（failureThreshold）：越小越敏感，越容易触发熔断
  • 熔断时长（openDuration）：建议 30 分钟（1800000ms），避免频繁探测
  • 恢复阈值（halfOpenSuccessThreshold）：建议 2-3 次，确保真正恢复

配置示例

{
  "circuitBreakerFailureThreshold": 5,
  "circuitBreakerOpenDuration": 1800000,
  "circuitBreakerHalfOpenSuccessThreshold": 2
}

网络不稳定的环境可以适当提高失败阈值，避免误触发熔断。

元数据字段

系统自动管理的时间戳和软删除字段。

字段说明

字段名类型说明
createdAttimestamp创建时间，系统自动设置
updatedAttimestamp最后更新时间，每次修改自动更新
deletedAttimestamp软删除时间，非 null 表示已删除

软删除说明

  • 删除供应商时设置 deletedAt 为当前时间
  • 已删除的供应商不参与调度
  • 历史日志仍可关联到已删除供应商
  • 软删除数据不可恢复

废弃字段

以下字段已废弃，保留仅为向后兼容，不再生效：

字段名类型说明
tpmintegerTokens Per Minute（已废弃）
rpmintegerRequests Per Minute（已废弃）
rpdintegerRequests Per Day（已废弃）
ccintegerConcurrent Connections（已废弃）

请勿依赖这些废弃字段，它们可能在未来版本中移除。

完整配置示例

以下是一个典型供应商的完整配置示例：

{
  "name": "主力 Claude API",
  "url": "https://api.anthropic.com",
  "key": "sk-ant-api03-xxx...",
  "providerType": "claude",
  "isEnabled": true,
  "websiteUrl": "https://console.anthropic.com",

  "weight": 70,
  "priority": 0,
  "costMultiplier": 1.0,
  "groupTag": "production",

  "limitConcurrentSessions": 50,
  "limit5hUsd": 100,
  "limitDailyUsd": 500,
  "dailyResetMode": "fixed",
  "dailyResetTime": "00:00",
  "limitWeeklyUsd": 2000,
  "limitMonthlyUsd": 8000,

  "firstByteTimeoutStreamingMs": 30000,
  "streamingIdleTimeoutMs": 60000,
  "requestTimeoutNonStreamingMs": 120000,

  "proxyUrl": null,
  "proxyFallbackToDirect": false,

  "modelRedirects": {
    "claude-3-5-sonnet-20241022": "claude-3-5-sonnet-latest"
  },
  "allowedModels": null,

  "circuitBreakerFailureThreshold": 5,
  "circuitBreakerOpenDuration": 1800000,
  "circuitBreakerHalfOpenSuccessThreshold": 2
}

相关文档

Cubence - AI 中转平台
独家合作

Cubence · AI 服务中转平台

为 Claude Code、Codex、Gemini 等 AI 工具提供稳定高效的中转服务

专属优惠码
DING113CCH
-20%
立即访问
Previous
供应商类型详解
Next
智能调度详解