一把聚合站 key 给多个应用用：按客户端命名与轮换怎么做

把同一个 API key 复制到所有项目里，是很多人起步时的默认做法。它省事，但一旦某台服务器被入侵、某个前端打包文件被反编译出 .env，或者某个开源脚本把 key 提交到了公开仓库，你需要换 key 的地方就会变成一片战场。更现实的问题是：泄漏之后你甚至不知道是哪台机器泄漏的。

下面这套做法不依赖聚合站的任何特殊功能，只用 key 本身，就能把风险限制在单个应用范围内。

为什么不该所有项目共用一个 key

共用 key 有三个具体代价：

• 无法归因：账单异常、调用量暴涨、触发风控时，看不出是哪个应用造成的。
• 无法精准止损：发现异常后只能全站换 key，所有服务同时停机。
• 权限无法差异化：一个只会做文本摘要的后台任务，和一个对外暴露的聊天前端，拥有完全相同的调用能力。

聚合站的价值在于一个 key 能调多个模型。但这不等于你应该只用一个 key。前者是「一个入口覆盖多模型」，后者是「一个凭证覆盖多应用」——这两件事应该分开看。

按客户端拆 key 的粒度

拆得太细会管理不过来，太粗又失去意义。一个实用的划分依据是：独立部署、独立信任边界、独立失败影响面。

常见的合理切分：

• 每个生产服务一份 key（后端 API、批处理任务、定时脚本分开）。
• 开发 / 测试环境单独一份，和预发布、生产都不同。
• 个人本机调试一份，且不进入任何仓库。
• 如果某次实验或临时 demo 会交给外部人员，单独发一份，用完即废。

不需要切的：同一个服务内部的不同模块。它们共享同一份运行环境和同一套泄密风险，拆开只是增加运维成本。

命名规范：让 key 自带上下文

聚合站通常允许给 key 起名字（或备注）。名字是你以后唯一的线索，所以它应该回答三个问题：谁用、在哪跑、干什么。

推荐结构（用连字符或点号分隔，避免空格）：

<应用或服务名>-<环境>-<用途>

例如：

• chatbot-prod-web
• batch-summarizer-prod-worker
• data-pipeline-staging
• local-devtools-alice
• demo-2024-roadshow-temp

几条纪律：

• 不要用日期当名字：你几乎不会记得 3 月 12 日那份 key 是给谁用的。
• 不要用无意义编号：key1、key2 在事故现场帮不上忙。
• 名字里不要出现模型名：同一份 key 通常可以调多个模型，把 key 和模型绑死会在换模型时制造额外轮换。
• 临时用途在名字里标出来：temp、demo 这类词能提醒你事后清理。

如果聚合站支持备注或标签，把负责人、创建原因一并写上，比记在个人笔记里可靠。

轮换：先并存，再切换，最后吊销

轮换不是「删掉旧的、建一个新的」——那会带来一段停机窗口。正确顺序是让新旧 key 短暂共存。

1. 新建：按命名规范创建新 key，先不要动旧的。
2. 部署：把新 key 装进目标应用的密钥管理（环境变量、密钥管理服务、K8s Secret 等），不要硬编码进代码。
3. 验证：确认新 key 能正常调用，并观察该应用的日志与用量归属于新 key 的名字。
4. 切换：让应用读新 key。如果是滚动发布，新旧实例会短暂并存——这正是需要并存期的原因。
5. 观察：等待一个完整的业务周期（比如一整天的定时任务都跑过一轮），确认旧 key 的调用量归零。
6. 吊销：确认无流量后再删除旧 key。

第 5 步最容易被跳过。定时任务、低频批处理、只有月末才触发的对账脚本，都可能在你吊销旧 key 之后的第 15 天才暴露问题。

泄漏处置：按影响面分级

发现 key 泄漏时，先判断它属于哪一类，再决定动作幅度：

| 情况 | 建议动作 |
| --- | --- |
| 提交进了私有仓库但未推送 | 立即从历史中移除，轮换该 key |
| 出现在公开仓库 / 公开日志 | 视为已泄漏，立刻吊销，再慢慢轮换 |
| 只在一台可信任的服务器上 | 尽快轮换，不必紧急停机 |
| 出现在前端打包产物或公开分发文件中 | 立刻吊销，并改为经后端代理调用 |

关键判断是：这个 key 属于哪个应用，影响面就是哪个应用。这正是按客户端拆 key 的回报——你不需要把整个账号的所有服务一起停掉。

不要把 key 交到客户端手里

浏览器、移动 App、桌面客户端、公开的 Notebook——这些环境里的任何凭证都应视为公开。如果你需要让前端用上聚合站的能力，正确做法是：

• 前端调用你自己的后端。
• 后端持有聚合站的 key，做鉴权、限流、审计。
• 后端再转发请求到聚合站。

这样聚合站的 key 永远不出你的服务器，前端泄漏的只是你自己的会话凭证，可以被单独撤销，且不消耗聚合站额度。

日常维护清单

不需要复杂工具，定期做这几件事就够：

• 每月对账：列出所有 key，逐个确认它还在被使用、属于哪个应用、由谁负责。
• 清理孤儿 key：没有调用量的 key 要么是忘了关，要么是配置错了，两种都该处理。
• 人员变动时轮换：有人离开团队时，轮换他接触过的那几份 key，而不是全站轮换。
• 换模型不换 key：聚合站的意义就是一 key 多模型，模型切换属于配置变更，不要顺手做成 key 轮换。
• 记录轮换历史：谁在什么时候为什么换过 key，写下来。事故复盘时这是最省时间的一份材料。

小结

按客户端拆 key，本质是把「一个凭证的失败」限制在「一个应用的范围内」。命名规范让你在事故现场三秒内定位责任人，并存式轮换让你换 key 不用停机，而永远不把聚合站 key 交给前端，则从源头砍掉了最常见的一类泄漏。

这套方法和你用哪家聚合站无关，也和充值方式、是否 KYC 无关。它只是一种工程习惯：让每个凭证都有明确的主人，让每次轮换都不需要赌运气。