这篇写给把自己的项目接上云服务(对象存储、数据库、CDN、云函数)之后,发现密钥被写进了代码的独立开发者;也写给替别人做发布流水线的 AI 智能体——它们最容易把「能跑」当成「可以提交」。
约 8 分钟读完;需要你会用 Node.js 和命令行;不懂云厂商的鉴权体系也能跟,只需要知道:调用云 API 时要带一对「账号 + 密码」字符串,泄漏了别人就能用你的账号花钱。
下面这张表列出四类读者各自能拿走什么,按你的目的直接跳到对应小节。
| 读者 | 带走什么 | 拿它做什么 | 从哪节开始读 |
|---|---|---|---|
| 密钥已经写进代码、准备清理的开发者 | 一份六步轮换清单 | 照第 2 节从「盘点」开始逐条做 | 2 |
| 想把密钥改成「环境变量 + 本地文件」的人 | 一个 18 行的读取函数 | 直接抄第 3 节,改路径与字段名 | 3 |
| 负责持续集成流水线(CI:自动构建、测试、发布)的人 | 四条防回退判据 | 把第 5 节的检查加进提交前检查 | 5 |
| 想让 AI 智能体不再把密钥写进代码的人 | 一张正反向验证表 | 用第 5 节的表验收它加的检查有没有用 | 5 |
只需要 Node.js 18 以上和一条命令行;不需要装额外依赖,文中用到的都是 Node 自带的文件与路径模块。
不适合已经在用云厂商密钥托管服务(由平台代管、代码里完全不出现密钥)的读者:这篇讲的是自建项目的最小可行做法。
先说结论:密钥进过版本历史,就等于泄漏;把那一行改成环境变量救不了它,唯一有效的动作是作废旧的、换一个新的。 后面所有步骤都是为了这件事做干净。
四个待解决的问题与对应判据如下。
| 要解决的问题 | 不处理的后果 | 本文给的判据 |
|---|---|---|
| 六处代码各自写死了一对密钥 | 改一处漏五处,旧的仍然有效 | 全仓搜不到密钥形态的字符串 |
| 换新密钥后本地怎么跑 | 又写死一份,回到原点 | 环境变量优先、外部文件兜底(读不到环境变量时改读本地文件)、都缺就抛错 |
| 怎么防止下次再写回去 | 靠记性,下个月必然复发 | 一条能在提交前跑的检查,且通过正反向验证 |
| 怎么确认新密钥真的能用 | 「配置好了」但调用失败 | 五个真实调用全部成功,才算换完 |
因为绝大多数人第一步做的是「把硬编码删掉、改成环境变量」,然后认为处理完了——但泄漏并没有停止。
版本历史是不可变的:删掉当前文件里的那一行,之前那次提交里仍然原样保存着它。任何人克隆仓库、翻一次历史,就能拿到这对密钥。删仓库、改历史、强制推送都属于「重写历史」,在有协作者或多个克隆的情况下并不可靠,也不是必要动作。
正确的处理顺序只有一种:先在云控制台作废旧密钥,再造新密钥。作废是立即生效的,之后任何持有旧密钥的调用都会被拒绝——泄漏的字符串从此变成一串无效字符。
顺序反了会怎样:先造新的、还在用旧的跑测试,旧的就一直有效;等哪天忘了作废,等于什么都没做。
因为这六步有严格先后,跳步会导致「改完本地跑不起来,于是又把密钥写回去」。
六步分别是:盘点 → 造新 → 搬出 → 接读取 → 缺就抛 → 作废旧的并重编译发布。逐条说明:
| 步骤 | 做什么 | 做完的标志 |
|---|---|---|
| 1 盘点 | 全仓搜密钥形态的字符串(云厂商的密钥有固定前缀,比如腾讯云是 AKID 开头的一长串) |
列出所有命中文件,本次是 6 个 |
| 2 造新 | 在云控制台新建一对密钥,只给需要的最小权限 | 拿到新的一对字符串,先存在密码管理器里 |
| 3 搬出 | 把新密钥写进用户目录下的凭据文件(在仓库之外),并确保它被忽略 | git status 里看不到这个文件 |
| 4 接读取 | 代码统一走一个读取函数:环境变量优先,读不到再读凭据文件 | 六个调用点都改成调用这个函数 |
| 5 缺就抛 | 两处都拿不到时直接抛错,不要回退到任何默认值 | 故意删掉凭据文件跑一次,进程立刻报「凭据缺失」 |
| 6 作废 | 回控制台作废旧密钥;把所有依赖它的产物重新编译发布 | 旧密钥调用被拒,新产物全部用新密钥跑通 |
第 6 步里的「重新编译」容易被漏:如果打包产物里曾经把密钥内联进去,只改源码不重新构建,线上跑的还是旧的那份。
因为「环境变量优先」这句话说起来简单,但六个调用点各写一遍就会出现六种行为——有的报错、有的返回空、有的悄悄用了默认值。
// creds.ts —— 唯一的凭据入口:环境变量优先,凭据文件兜底,都缺就抛
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
type Creds = { id: string; key: string };
let cache: Creds | null = null;
export function getTencentCreds(): Creds {
if (cache) return cache;
const envId = process.env.TENCENT_SECRET_ID;
const envKey = process.env.TENCENT_SECRET_KEY;
if (envId && envKey) {
cache = { id: envId, key: envKey }; // 场景一:CI / 容器里由环境变量注入
return cache;
}
const file = path.join(os.homedir(), ".teo-credentials.json");
if (!fs.existsSync(file)) {
throw new Error(`凭据缺失: ${file}`); // 不回退,不猜
}
const raw = JSON.parse(fs.readFileSync(file, "utf8"));
if (!raw.secretId || !raw.secretKey) {
throw new Error(`凭据字段缺失: ${file}`);
}
cache = { id: raw.secretId, key: raw.secretKey }; // 场景二:本机开发
return cache;
}
这个函数只做三件事:读环境变量、读用户目录下的 JSON、都失败就抛。cache 是进程内缓存,避免每个请求都读一次磁盘。
优先级画出来是一条直线,没有例外分支:
graph TD
A[调用方要一对密钥] --> B{环境变量里有吗?}
B -- 有 --> C[用它]
B -- 没有 --> D{用户目录的凭据文件在吗?}
D -- 在 --> E[读它并校验字段]
D -- 不在 --> F[抛错并写明缺哪个文件]
E --> G[字段齐全才返回]
六个文件各自写死一对字符串:数据库连接、云函数部署、日志查询、静态托管、初始化脚本、部署步骤定义,每处一份。
先看写死的版本,六个文件各有一份:
// 原来的做法(示意):每个模块自己带一份
const secretId = "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const secretKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
六个文件都改成一行调用,凭据从哪来由 getTencentCreds() 统一决定,现在的写法如下:
// 现在的做法:调用点只关心「我要一对密钥」
import { getTencentCreds } from "./creds";
const { id, key } = getTencentCreds();
两种做法的差别如下。
| 对比项 | 六个文件各写死 | 一个读取函数 |
|---|---|---|
| 换密钥要改几处 | 6 处,漏一处就还在用旧的 | 0 处(改凭据文件或环境变量) |
| 凭证缺失时 | 用空字符串继续跑,报一个看不懂的鉴权错误 | 立即抛错,写明缺哪个文件 |
| CI 与本地 | 写死的是同一份,本地密钥会进 CI | 环境变量优先,CI 不需要文件 |
上面给了读取函数,这里把数据流补完整,避免「配置在那、代码读这」对不上:
~/.teo-credentials.json(在仓库外,被忽略),或者由 CI 注入两个环境变量。getTencentCreds(),此时才真正读盘,结果进缓存。{ id, key },传给云服务客户端库的构造参数。这就是「凭据在哪、什么时候被读、读了哪两个字段」的完整链路。读者要自查时,只需要在六个调用点各打断点,看第一次读发生在哪。
因为「以后注意」不是机制。写一条检查很容易,难的是证明它真的会拦住人、且不会天天误报。
四条判据分别检查什么、命中后怎么处理,如下。
| 判据 | 检查什么 | 命中时该怎么做 |
|---|---|---|
| 禁止入仓 | 源码里出现密钥形态的字符串(如 AKID 开头的一长串) |
拒绝提交,提示改用读取函数 |
| 缺失即抛 | 删掉凭据文件跑一次启动 | 进程必须立刻失败,不能带病运行 |
| 历史作废 | 旧密钥在新环境调用一次 | 必须被拒绝(鉴权失败),不能成功 |
| 真连一次 | 用新密钥做一次真实调用(不用 mock) | 返回真实数据,不是「配置好了」 |
第二条和第四条容易被合并成一条「跑一下看看」——但它们检验的东西不同:第二条检验「失败时是否安静地继续」,第四条检验「成功时是否真的连上了」。两条都要有。
检查本身也需要验证,否则会出现「检查写了但从来不命中」。做法是正反向各跑一次:
只做正向,会得到一条「凡是出现 AKID 就报错」的粗暴规则,把文档和示例全拦下,最后大家选择跳过检查;只做反向,检查可能永远不命中。
因为轮换的失败方式很安静:tsc 通过、脚本能启动,但线上第一次调用才炸。所以要一次把五条全跑完。
五项验证与通过标准如下。
| 验证项 | 通过标准 | 本次实测 |
|---|---|---|
| 类型检查 | 零新增错误 | 通过,0 错误 |
| 语法检查 | 三个脚本逐个 node --check |
三个都通过 |
| 云 API 鉴权 | 列出一个真实资源(如加速域名列表) | 返回正常结果 |
| 日志查询 | 用新密钥查到最近一条日志 | 查到 |
| 数据库读取 | 用新密钥读两张集合,条数与预期一致 | 293 条 / 8 条,与预期一致 |
配套的两个反例也要跑:把凭据文件临时改名后启动,必须报「凭据缺失」;用旧密钥发起一次调用,必须被拒。两条都符合,才说明「缺了就停」和「旧的真废了」都成立。
密钥泄漏的处理顺序不能反:先作废旧密钥,再造新密钥,再把六处硬编码收成一个「环境变量优先、文件兜底、缺就抛」的读取入口,最后用四条判据把它锁死——禁止入仓、缺失即抛、旧密钥必须被拒、新密钥必须真连一次。判据本身也要正反向验证,否则它只会变成一条被大家跳过的检查。
这套流程与云厂商无关:盘点、作废、外置、读取、缺失即抛、检查这六步对任何凭据都成立,只有密钥前缀和调用客户端是厂商特有的。
当前做法有三处边界:
一是凭据文件是明文 JSON。它只在用户目录下、不进仓库,但同机其他进程仍可读。下一步可以换成系统钥匙串(macOS 钥匙串 / Windows 凭据管理器),读取函数只换实现、不改调用点。
二是权限粒度是「一把钥匙开所有门」。六个调用点现在共用同一对密钥,一旦某个脚本被利用,影响面是整个账号。下一步可以按用途拆成多对(只读日志、只部署、只读写数据库),每对单独放。
三是检查只覆盖源码,不覆盖打包产物。如果哪天构建时又把密钥内联进产物,源码检查不会发现。下一步可以在构建后扫描产物目录,用同一套形态规则再跑一遍。
在终端里跑一条搜索:git grep -n "AKID"。只要有命中,先别改代码——去云控制台把那对密钥作废,再回来按第 2 节的六步做。
这些内容来自一个真实项目的云凭据治理:一次盘点发现六个文件各自写死了同一对密钥,且这对密钥已经跟随多次提交进入了版本历史。处理过程是先作废旧密钥、再把六处收成一个读取入口,最后补上一条禁入仓检查并用正反向样例验证过。文中的验证项目都是当时的真实调用结果,不是示意。