密钥别进仓库：配置与凭据分离原则

给 AI 编码工具配 API key 时，很多人顺手把 token 写进了项目的 config.toml——工具能跑、一切正常，直到某天把这个文件 commit 进仓库推到远端，密钥从此躺在提交历史里。公开仓库的爬虫抓到新提交的凭据只要几分钟，冒用的账单却要等月度账单才看见。密钥入库在常见错误清单里排位靠前，代价却是清单里最贵的一档。这篇按误区文的惯例，先摆三种常见说法再逐条对照，然后给配置与凭据分离的具体配法，以及泄露之后的标准动作；八个错误的完整清单见config.toml 八个常见错误一篇。

说法一：仓库是私有的，放着没事

第一种说法拿私有仓库当保险箱。对照看，私有仓库的风险比直觉高：仓库可能因为协作扩容而开放成员、可能被误转公开、可能因 token 范围过大而连带其他系统，而凭据一旦进了提交历史，改一个文件撤不回历史里的旧值。私有只是门槛，不是隔离——「现在私有」与「永远私有」之间没有任何机制保证。凡是凭据，按「终将可见」的标准存放，心态就对了：私有仓库里的密钥只是暴露概率低一点，暴露的后果一点没少。

说法二：配置写一处，换了机器才方便

第二种说法图省事：配置连同凭据写进项目文件，克隆下来就能跑，多方便。对照看，方便的代价是凭据跟着代码到处走：进版本库、进同事机器、进 CI 环境、进备份。省下的那五分钟配置时间，买回的是凭据生命周期的彻底失控——你无法回答「这个 token 现在存在于几台机器上」。config.toml 的分层机制本来就为这件事留了位置：项目层放团队共享的结构，全局层放你个人的凭据，两层各管各的，见config.toml 分层一篇。

说法三：加了 gitignore 就安全了

第三种说法依赖 ignore 规则。对照看，gitignore 只防「还没进去的」，防不了「已经进去的」：规则加晚一步，之前的提交历史里照样有；换台机器忘了同步规则，照样提交。而且 ignore 是黑名单思路——你得料到所有可能装凭据的文件名，料漏一个就漏一个口子。更稳的思路是反过来做白名单：默认什么都不提交，只允许明确列出的文件入库。两类思路的差别，正是泄密项目与干净项目的分界。

分离怎么落地：个人配置不提交，共享走白名单

具体配法三步。第一步，凭据挪出项目层：token、API key 全部写进用户主目录的全局配置，项目 config.toml 里只留结构不留值，agent 运行时两层合并，效果不变。第二步，仓库侧做白名单：在 ignore 规则里先排除全部、再放行明确需要的文件，模板、示例配置用不带真值的占位文件入库。第三步，团队共享的部分写成模板：提交一份 config.example.toml，字段齐全、值全为占位，同事按模板往自己的全局层里填自己的凭据——共享的是结构，凭据各归各。agent 工具链里凭据注入的通用机制，见凭据注入一篇；代码仓库泄露的高发场景与 case，见代码泄露一篇。

已经提交了怎么办：按泄露处理，轮换兜底

发现密钥进了提交历史，按「已泄露」对待，动作按顺序做。第一件事不是删文件，是去服务方后台作废这个 token、换发新的——凭据一旦可见，撤回历史只是掩耳盗铃，爬虫可能早就抓走了。第二件事才是清理：从当前文件移除、改写提交历史或直接作废整个仓库的可见性，看项目情况选。第三件事查账：核对这个 token 在暴露窗口期内的调用记录，异常调用就是冒用的证据。第四件事补机制：把分离的配法补齐，把这次教训写进团队约定。记住一个不对称：轮换一个 key 只要几分钟，追一张冒用账单的周期以月计——泄露后的处置，轮换永远是第一优先。

密钥分离速查

• 凭据写全局层，项目 config.toml 只留结构不留值
• ignore 是黑名单思路，入库白名单才稳：默认不提交，放行要列名
• 共享走 config.example.toml 模板，值全用占位符
• 发现入库先作废轮换，再清理历史，最后核对调用账
• 轮换成本几分钟，冒用追查以月计，先后顺序别反

关于密钥管理的常见疑问

• 全局配置里的凭据，多项目共用一个 key 合适吗？：方便但粒度粗——一个 key 泄露，所有项目一起换。条件允许时按项目或按用途分 key，出事时影响面小，作废轮换也不用全线停摆。
• 提交历史里的旧密钥，删掉文件再提交一次够吗？：不够。历史提交里的旧值仍然可见，能检出历史的人就能拿到。正确顺序是先作废轮换，历史清理只作为补充动作。
• MCP 服务条目里的认证信息怎么放？：与主配置同理——条目结构留在配置文件里，token 值放全局层或环境变量，条目里用引用；把凭据连同服务条目一起提交，等于把接入篇里说过的泄露路径原样走一遍。

想把自己项目的入库风险摸一遍，可以让 DeepSeek 列出仓库里所有含 token、key、secret 字样的文件与提交记录，再用豆包把需要作废轮换的凭据整理成一张带优先级的清单，照单处理。