在 AI API 中转服务中，稳定性是第一优先级。用户调用你的接口，期望的是永远能拿到结果——即使某个上游供应商临时故障、限流、甚至下线。词元圈通过一套完整的 Key 池管理与智能路由系统，实现了 99.7% 的服务可用率。本文将深入拆解这套系统的设计思路与技术实现。

为什么需要 Key 池管理

传统的 API 中转服务通常采用"一个渠道一个 Key"的简单模式。这种方式存在明显的单点故障风险：

上游限流：供应商对单个 API Key 设置 RPM/TPM 限制，一旦触发 429 错误，该渠道所有请求都会失败
余额耗尽：某个 Key 的额度用完，整个渠道就断了，需要人工介入充值或切换
Key 失效：上游因违规检测、安全策略等原因封禁 Key，服务直接中断
负载不均：所有请求打到同一个 Key 上，无法利用多 Key 的聚合容量

Key 池的核心思想很简单：把每个渠道的多个上游 Key 看作一个资源池，由路由器统一调度。这样一来，单个 Key 的异常不会影响整体服务。

数据模型设计

词元圈的 Key 池系统基于 channel_keys 表构建，每个渠道可以关联多个上游 Key：

CREATE TABLE channel_keys (
  id            SERIAL PRIMARY KEY,
  channel_id    INTEGER NOT NULL,
  api_key       TEXT NOT NULL,
  weight        INTEGER DEFAULT 1,        -- 权重，用于加权轮询
  daily_limit   NUMERIC,                  -- 每日请求上限
  monthly_limit NUMERIC,                  -- 每月请求上限
  health_status VARCHAR(16) DEFAULT 'healthy',  -- healthy/degraded/unhealthy
  consecutive_failures INTEGER DEFAULT 0, -- 连续失败次数
  last_used_at  INTEGER,
  created_at    INTEGER DEFAULT EXTRACT(epoch FROM now())::integer
);

几个关键设计决策：

权重字段：不同 Key 可能来自不同的付费计划，权重高的 Key 应该承担更多流量。比如企业版 Key 权重设为 5，个人版设为 1
双重限额：日限额防止突发消耗，月限额控制长期成本。两个维度独立检查
三级健康状态：不是简单的"可用/不可用"二元判断，degraded 状态表示可用但有风险，路由时降低其优先级

智能路由算法

路由的核心是一个多层决策树，按优先级依次执行：

第一层：渠道匹配

根据请求中的 model 参数，在 model_map 中查找对应的渠道列表。一个模型可能映射到多个渠道（比如 deepseek-v4 同时走 DeepSeek 官方和 SiliconFlow），这就为 failover 提供了基础。

第二层：加权随机选择

在候选 Key 列表中，按 weight 字段进行加权随机选择（Weighted Round-Robin）。这比简单的轮询更灵活：

function weightedRandomSelect(keys) {
  const totalWeight = keys.reduce((sum, k) => sum + k.weight, 0);
  let random = Math.random() * totalWeight;
  for (const key of keys) {
    random -= key.weight;
    if (random <= 0) return key;
  }
  return keys[keys.length - 1];
}

权重为 5 的 Key 被选中的概率是权重为 1 的 Key 的 5 倍。这样高配 Key 自然承接更多流量，但不会完全压垮低配 Key。

第三层：健康检查过滤

在选择之前，先过滤掉不健康的 Key：

healthy：正常参与路由，无额外限制
degraded：降低权重后参与路由（实际权重 = 原权重 × 0.3）
unhealthy：完全跳过，不参与本轮选择

第四层：限额检查

选中 Key 后，检查其日限额和月限额。如果已超限，标记为 degraded 并重新选择。

失败检测与自动恢复

这是整个系统最关键的部分。词元圈的 relay 层在每次请求完成后，会根据响应状态更新 Key 的健康状态：

async function updateKeyHealth(keyId, response) {
  if (response.status === 429 || response.status === 402) {
    // 限流或余额不足
    await incrementFailures(keyId);
  } else if (response.status >= 500) {
    // 上游服务器错误
    await incrementFailures(keyId);
  } else if (response.ok) {
    // 成功，重置失败计数
    await resetFailures(keyId);
  }
}

async function incrementFailures(keyId) {
  const key = await getKey(keyId);
  const newCount = key.consecutive_failures + 1;

  let newStatus = 'degraded';
  if (newCount >= 3) newStatus = 'unhealthy';

  await updateKey(keyId, {
    consecutive_failures: newCount,
    health_status: newStatus
  });
}

连续失败 3 次即标记为 unhealthy。被标记后，系统启动一个 5 分钟的恢复定时器：

async function scheduleRecovery(keyId) {
  setTimeout(async () => {
    await updateKey(keyId, {
      health_status: 'degraded',   // 先降级为 degraded
      consecutive_failures: 0
    });
    // 如果 degraded 状态下再次成功，自动恢复为 healthy
  }, 5 * 60 * 1000);
}

恢复不是直接跳回 healthy，而是先到 degraded 试探。如果试探期间请求成功，再升级为 healthy。这种渐进式恢复避免了"抖动"问题——如果上游只是短暂恢复又挂了，degraded 状态可以快速再次降级。

请求重试策略

当一个 Key 失败时，relay 层不会立即返回错误给用户，而是自动尝试下一个可用 Key：

async function retryWithFallback(channelId, request) {
  const keys = await getHealthyKeys(channelId);
  const sorted = keys.sort((a, b) => {
    // healthy > degraded > unhealthy
    const order = { healthy: 0, degraded: 1, unhealthy: 2 };
    return order[a.health_status] - order[b.health_status];
  });

  for (const key of sorted) {
    try {
      const response = await callUpstream(key.api_key, request);
      await updateKeyHealth(key.id, response);
      return response;
    } catch (err) {
      await updateKeyHealth(key.id, { status: 500 });
      continue; // 尝试下一个 Key
    }
  }

  // 所有 Key 都失败，尝试备用渠道
  return await tryFallbackChannel(request);
}

整个重试过程对用户透明。用户感知到的只是"响应稍微慢了一点"，而不是"服务挂了"。

多渠道 Failover

Key 池解决的是单渠道内的高可用，但真正的容灾需要跨渠道 failover。词元圈的模型路由支持一个模型映射到多个渠道：

// model_map 示例
{
  "deepseek-v4": [
    { "channel_id": 1, "priority": 1 },  // DeepSeek 官方
    { "channel_id": 5, "priority": 2 },  // SiliconFlow
    { "channel_id": 8, "priority": 3 }   // 其他备选
  ]
}

当一个渠道的所有 Key 都不可用时，自动切换到下一个优先级的渠道。这种两级容错（Key 级 + 渠道级）确保了极高的可用性。

监控与可观测性

词元圈后台为每个 Key 提供了完整的监控视图：

实时健康状态：绿/黄/红三色标识，一眼看清
请求量统计：每日/每月请求数，配合限额预警
错误详情：最近一次错误的 HTTP 状态码和错误信息
费用追踪：每个 Key 的累计消费金额

管理员可以在后台随时调整 Key 的权重、限额，添加新 Key 或禁用异常 Key，所有变更实时生效，无需重启服务。

实际效果

上线 Key 池系统后，词元圈的服务质量有了显著提升：

可用率：从 98.5% 提升到 99.7%，用户几乎感知不到上游故障
故障恢复时间：从人工介入的 10-30 分钟，缩短到自动切换的秒级
运维成本：不再需要 7×24 值班盯着上游状态
容量弹性：通过增加 Key 数量线性扩展吞吐能力

总结

Key 池管理与智能路由是 API 中转服务的基础设施。词元圈的实现遵循了几个核心原则：加权调度保证资源合理分配，多级健康检查实现精准故障检测，渐进式恢复避免状态抖动，两级容错确保极端场景下的可用性。这套系统已经稳定运行，支撑着词元圈每天数万次的 API 调用。

如果你正在构建类似的 API 网关或中转服务，Key 池是一个值得优先实现的特性。它的复杂度不高，但对系统可靠性的提升是质的飞跃。

技术博客

热门标签

Key 池管理与智能路由：构建高可用 API 中转服务的核心