密钥轮换与泄漏演练：vibe 项目第三方 API 密钥的换血手册

密钥这东西，不出事时人人觉得它只是个字符串，出事时才发现它是一张能刷爆账单、拖走数据的通行证。本篇不讲密钥该存哪、能不能喂给 AI——那是凭据管理指南的领地。本篇只讲两件事：没出事时怎么定期换血，出事时怎么在限定时间内止血。换句话说，前一篇管“放”，本篇管“换”和“救”。

一、轮换不是换密码，是换血

很多人把轮换理解成“把旧密钥删了、生成个新的、改一处配置”。单人项目里这套做法有三个坑：第一，正在跑的任务、定时任务、用户手里的旧版本可能还在用旧密钥，一删就断线；第二，改配置的那一刻如果新密钥配错了，你连回滚的旧密钥都没了；第三，没人记得这次换了哪些服务、哪些环境，出了问题只能全量排查。所以轮换的正确心智是换血：新旧两把钥匙并存一段时间，新血先跑起来、确认没问题，旧血再退场，全程不断线、可回滚、有清单。

双活窗口是这套方法的核心：同一服务在一段时间内接受新旧两把密钥，客户端先切一部分流量到新密钥，观察无异常再全切，最后给旧密钥留一段“只读观察期”，确认零调用后再吊销。没有双活支持的供应商怎么办，后面第六节专门讲；先不要因为某个供应商不支持，就把整个轮换计划放弃。

二、先盘点，再定节奏

动手换之前，先拉一张密钥清单，字段越少越好：服务名、用途、环境（生产、测试）、持有人（是你还是某个自动化任务）、上次轮换时间、下次到期时间、泄漏后的最大损失。最大损失这一列最重要：能刷爆账单的支付与模型调用密钥、能读用户数据的数据库与存储密钥，排在第一档；只能读公开数据的只读密钥，排在末档。第一档每九十天轮换一次，第二档每半年一次，末档每年检查一次即可；节奏写死在日历里，不要靠“想起来再换”。

清单里还要标出“影子密钥”：那些你以为删了、其实还躺在旧服务器环境变量、旧 CI 配置、某个同事转发的聊天记录里的密钥。盘点时用供应商后台的“最近调用来源”反查：后台显示某把密钥上周还有调用，而你的清单里说它已停用，那就是影子密钥，先收进清单再谈轮换。

三、轮换六步：一次只换一把

第一步，生成新密钥并只放进密钥管理处，不改任何运行配置；生成动作本身要留审计记录，谁、何时、为哪个服务生成。第二步，灰度接入：先让一个非关键路径（比如测试环境、或生产的一个低频定时任务）用新密钥跑二十四小时，确认调用成功率、延迟、账单都没有异常。第三步，全量切换：把其余路径逐一切到新密钥，每切一批就看一次监控，不要一次性全切。第四步，旧密钥观察期：旧密钥保留七到十四天，但把它的权限能降就降（比如只读），并在供应商后台盯着它的调用量；调用量归零才算真正无人用。第五步，吊销旧密钥并在清单上打勾，吊销动作也要留记录。第六步，复盘一句话：这次换了什么、有没有断线、下次注意什么，写进清单备注。一次只换一把密钥，换完一把再换下一把；同时换五把，出问题你连哪把惹的祸都定位不了。

四、泄漏分级：先定级，再动手

泄漏发生时最忌讳的是边查边慌。先用一分钟定级：一级是生产密钥进了公开仓库、公开聊天、公开日志，默认按“已被人拿走”处理；二级是密钥进了私有但多人的地方（比如共享文档、小群聊天），按“可能已被无关人员看到”处理；三级是只在自己设备上的临时暴露（比如屏幕共享一闪而过），按“低概率但需确认”处理。定级决定速度：一级立即吊销、不先查调用记录；二级先吊销再查；三级可以先查调用记录、确认无异常调用后再轮换。顺序反了（一级先查半天记录再吊销），损失窗口就被自己拉长了。

五、泄漏时间线：十五分钟、六十分钟、二十四小时

零到十五分钟：吊销或冻结涉事密钥，切换到备用密钥恢复服务，在清单上记下发现时间、发现人、密钥名、疑似暴露渠道。这一步不要等“确认是否真的被盗用”，一级泄漏默认已盗用。十五到六十分钟：查供应商后台的调用记录，重点看异常地域、异常时间段、异常调用量和账单突增；同时检查同仓库、同文档里是否还有其他密钥一并暴露，常常是成串暴露。六十分钟到二十四小时：完成新密钥全量切换，通知受影响的用户（如果用户数据可能被读到，不要含糊其辞，写清影响范围和已采取措施），写一份事后复盘：暴露原因、发现延迟、止血耗时、下次改进。二十四小时后还拖着不吊销的旧密钥，等于把门敞着等人进来。

一个可直接抄的例子：周二上午十点发现模型调用密钥进了公开仓库提交。十点零五分在供应商后台吊销该密钥并启用备用密钥，服务短暂报错三分钟后恢复；十点三十分查调用记录，发现一笔来自陌生地域的两千次调用，账单多出约四十美元；十一点确认同一提交里没有其他密钥；当天下午完成新密钥切换并写复盘，复盘里唯一改进项是“提交前加密钥扫描钩子”。没有这条时间线，同样的事故很容易拖成一下午。

六、供应商不支持双活怎么办

有些小供应商一次只认一把密钥，生成新的瞬间旧的就失效，没有双活窗口。这时不要硬套双活流程，改用“短窗口切换法”：选在用户最少的时段，先在测试环境验证新密钥，把生产切换脚本准备好（包括一键回滚到旧密钥的方案——如果供应商允许重新生成同名密钥或保留旧密钥到切换完成），切换后立刻跑一遍核心链路冒烟测试，确认通过再收工；切换前先把旧密钥的调用量、账单基线记下来，切换后半小时内盯着监控。窗口期控制在十五分钟内，提前在状态页或群里告知用户“短暂维护”。不支持双活不是不轮换的理由，只是把窗口压短、把准备做厚。

七、演练剧本：四十五分钟跑一次

泄漏演练不要等真出事才第一次做。剧本很简单：准备一把专用的演练密钥（真实可用、权限最小、只读公开数据），故意把它写进一个私有测试仓库的提交里，然后按第五节时间线走一遍：计时吊销、计时切换、计时查调用记录、计时写复盘。演练的通过标准是四条：十五分钟内完成吊销与切换，调用记录查得到异常项，复盘里至少有一条可落地的改进，演练密钥事后已吊销且不在任何清单里残留。每季度跑一次，跑完把耗时写进清单备注；耗时从四十五分钟降到二十分钟以内，说明这套流程真的长在你手上了。

演练时最容易踩的坑是拿生产密钥演练，或者演练完忘了吊销演练密钥——演练密钥本身就成了新的泄漏源。演练密钥必须单独生成、单独标记、演练结束立即吊销，三条缺一不可。

八、六个反模式，见一个改一个

轮换时直接删旧密钥，等于主动制造断线事故。所有服务共用一把密钥，一处泄漏等于全站失守；按服务、按环境拆分是轮换的前提。密钥写进代码仓库还指望“仓库是私有的就没事”，私有仓库的协作者、前员工、误公开的截图都是暴露渠道。泄漏后先查“有没有被盗用”再吊销，把止血时间拱手让人。轮换记录只记在脑子里，半年后没人说得清哪把换过、哪把没换。最后是演练只走过场：演练密钥没吊销、复盘没改进项，这种演练不如不做，因为它给了你“已经准备好了”的假安全感。

九、备用密钥与账单熔断：止血之外的第二道防线

轮换和泄漏流程之外，还有两件要提前备好的东西：备用密钥和账单熔断。备用密钥不是“另一把长期有效的密钥”，而是一把权限收紧、平时零调用、只在主密钥吊销那一刻启用的钥匙；平时零调用的好处是，供应商后台一旦出现它的调用记录，你立刻知道这是切换动作，而不是日常流量。备用密钥同样要进清单、同样要定期轮换，否则主密钥换了三轮、备用密钥还是三年前那把，等于留了一个从不换锁的后门。账单熔断则是另一回事：在供应商后台给第一档密钥设好预算告警和用量上限，调用量突增到阈值就短信或邮件告警，超过硬上限就自动停用或降级。泄漏事故里最常见的损失不是数据被读走，而是陌生调用在几小时内刷出数千美元账单；告警设在平时用量的两倍处，宁可误报一次，也不要在账单日才发现。

给 agent 的需求可以写成两条：第一档密钥必须配备用密钥，备用密钥平时调用量必须为零、每季度验证一次可用性；第一档密钥必须配预算告警，阈值为平时峰值的两倍，告警通道要走短信或邮件，不要只走站内通知——出事时你可能正好登不上站内系统。

十、人员变动时：离职、换协作者先换钥匙

单人项目也会有协作者：临时帮忙的开发者、外包做过集成的朋友、离职的兼职运营。只要有人曾经接触过密钥，他离开时就要把他接触过的密钥轮换一遍，不管分手多愉快、多信任。这不是不信任，而是把“人走了、密钥还在外面”这个状态清零。操作顺序是：先列出该人员接触过的服务清单，再按第三章六步逐把轮换，最后把他的账号权限、仓库权限、供应商后台协作者身份一并收回，并把这次轮换记进清单备注。顺序不能反：先收回账号权限再轮换密钥，中间可能出现服务用旧密钥跑着、而你已经进不去供应商后台的尴尬；先轮换、再收权限，全程不断线。

同样道理适用于你自己的设备变动：旧手机出售、旧电脑送人之前，先把上面存过的密钥全部轮换一遍，再清除设备。设备上的密钥残留和人员手里的密钥残留，本质是同一类风险：密钥的知情人变多了，而清单没有同步变。清单的知情人一列，值得每季度核对一次：这把密钥还有谁知道、还有谁能拿到，答不上来的，先轮换再说。

十一、复盘模板：每次轮换与泄漏都留一页

复盘不用写成长文，一页纸、六个空就够：事件或轮换名称、发生或执行时间、影响范围（哪些服务、哪些环境、是否涉及用户数据）、时间线（发现、吊销、切换、恢复各在几点）、根因一句话、下次改进一到两条。轮换的复盘重点在“有没有断线、哪一步耗时最长”；泄漏的复盘重点在“发现延迟多久、止血耗时多久、账单损失多少”。复盘写完要放进清单备注，而不是单独存在某个文档里吃灰；下次轮换同一服务时，先翻它的上次复盘，上一轮踩过的坑，这一轮就不要再踩。复盘里不要写责任人姓名来追责，写流程缺口：是清单漏了影子密钥，还是告警阈值设得太松，还是演练太久没跑；对事不对人，复盘才写得下去。

十二、最小可行流程：一个人、半天能搭起来的版本

如果你的项目只有你一个人、服务不到十个，不要被前面的章节吓住，最小可行流程半天就能搭起来。上午做三件事：拉一张密钥清单表格，标出第一档密钥；给第一档密钥设好预算告警；把泄漏时间线打印或存到手机备忘录里。下午做两件事：给第一档密钥各配一把备用密钥并验证一次可用性；在日历上把九十天轮换提醒和季度演练提醒都设好。做完这五件事，你就已经超过了大多数单人项目的密钥管理水平；之后每季度按演练剧本跑一次、按节奏轮换一轮，流程会自己越滚越顺。流程的敌人不是规模小，而是永远停在“以后再说”。半天搭起来的流程还有一个好处：它是你自己的流程，出了问题你知道去哪改；抄来的大公司流程再完整，落不了地也等于没有。先让最小流程跑起来，跑顺了再往上加告警、加演练、加复盘，一步一步加，比一开始就搭一套用不上的重流程要稳得多。记住，密钥管理的目标不是流程好看，而是出事时你能在十五分钟内说出“哪把密钥、影响多大、已经吊销没有”这三句话。

十三、检查清单：贴在密钥清单首页

先把这份清单贴在密钥清单首页，发布新功能前先过一遍，缺项先补流程再上线。清单是否覆盖全部服务、全部环境，有没有影子密钥未收录；第一档密钥是否在九十天节奏内；最近一次轮换是否走了六步、有没有跳步；最近一次演练是否在三个月内、耗时多少；泄漏时间线是否打印或保存在离线可达的地方（泄漏时可能恰恰登不上线上文档）。五项全打勾，密钥这块才算从“凭感觉”变成了“有流程”；缺任何一项，先补流程再谈新功能，因为密钥事故的账单和信任成本，从来不是按功能排期的。