零停机轮换聚合站 key：让旧 key 排空的同时新调用照常走
本文介绍如何在 LLM API 聚合站上实现零停机 key 轮换。核心是分阶段切换：先签发新 key 并配置到客户端，再将新流量切换至新 key，同时让旧 key 继续服务直至在途请求完成，最后安全吊销旧 key。适用于 Claude Code 等长会话场景，避免轮换导致中断。
为什么需要零停机轮换
在聚合站使用 API key 时，定期轮换是安全最佳实践。但直接吊销旧 key 会导致正在进行的请求失败，尤其是 Claude Code 这类长会话工具，可能中断工作流。零停机轮换的目标是：新调用立即使用新 key，旧 key 上的在途请求继续完成，最后才吊销旧 key。
轮换前的准备
- 确认聚合站支持同时持有多个有效 key（通常可以）。
- 在客户端（如 Claude Code 配置、环境变量、代码中的 API key 设置）中准备好切换新 key 的路径。
- 记录旧 key 的标识（如名称或末尾字符），方便后续操作。
第一步：签发新 key
在聚合站控制台创建一个新 API key。建议命名清晰（例如带日期或用途），并立即复制保存。新 key 的权限应与旧 key 一致，确保能访问所需模型。
第二步：将新流量切换到新 key
更新客户端配置，使新发起的请求使用新 key。根据使用方式不同，操作如下：
- 环境变量：修改
API_KEY环境变量为新 key，重启客户端或新开终端。 - 配置文件：更新 Claude Code 的配置文件（如
~/.claude/config.json）中的 API key 字段。 - 代码：在代码中替换 key 值，重新部署或重启服务。
切换后，新请求将走新 key，旧 key 仅处理切换前已发起的在途请求。
第三步：让旧 key 上的在途请求跑完
切换后不要立即吊销旧 key。等待一段时间，确保所有使用旧 key 的请求已完成。等待时长取决于业务请求的典型持续时间：
- 短请求（几秒）：等待几分钟即可。
- 长会话（如 Claude Code 交互）：建议等待会话结束或超时时间（例如 30 分钟以上）。
可以通过聚合站控制台的用量日志观察旧 key 的最后活动时间，确认无新请求后再进行下一步。
第四步：吊销旧 key
确认旧 key 无活动后，在控制台将其吊销或删除。吊销后，任何使用旧 key 的请求将立即失败，因此务必确保没有遗漏的在途请求。
验证与回滚
- 切换后，用新 key 发起一个测试请求，确认能正常调用模型。
- 如果新 key 出现问题，可临时回滚到旧 key（在吊销前），并排查原因。
注意事项
- 聚合站按官方价 ×1.3 扣费，贡献 key 按 ×1.1/×1.2 返 USDC，轮换不影响计费规则。
- 无 KYC 的充值方式（Base 上的 USDC）不影响 key 管理流程。
- 避免在高峰时段轮换，以减少潜在影响。
- 定期轮换 key 并遵循最小权限原则。