把密钥从代码里搬出去:六步轮换与四条防回退判据 | 杨元超的世界

读者是谁

这篇写给把自己的项目接上云服务(对象存储、数据库、CDN、云函数)之后,发现密钥被写进了代码的独立开发者;也写给替别人做发布流水线的 AI 智能体——它们最容易把「能跑」当成「可以提交」。

约 8 分钟读完;需要你会用 Node.js 和命令行;不懂云厂商的鉴权体系也能跟,只需要知道:调用云 API 时要带一对「账号 + 密码」字符串,泄漏了别人就能用你的账号花钱。

下面这张表列出四类读者各自能拿走什么,按你的目的直接跳到对应小节。

读者 带走什么 拿它做什么 从哪节开始读
密钥已经写进代码、准备清理的开发者 一份六步轮换清单 照第 2 节从「盘点」开始逐条做 2
想把密钥改成「环境变量 + 本地文件」的人 一个 18 行的读取函数 直接抄第 3 节,改路径与字段名 3
负责持续集成流水线(CI:自动构建、测试、发布)的人 四条防回退判据 把第 5 节的检查加进提交前检查 5
想让 AI 智能体不再把密钥写进代码的人 一张正反向验证表 用第 5 节的表验收它加的检查有没有用 5

环境准备

只需要 Node.js 18 以上和一条命令行;不需要装额外依赖,文中用到的都是 Node 自带的文件与路径模块。

不适合已经在用云厂商密钥托管服务(由平台代管、代码里完全不出现密钥)的读者:这篇讲的是自建项目的最小可行做法。

0 本文讲什么

先说结论:密钥进过版本历史,就等于泄漏;把那一行改成环境变量救不了它,唯一有效的动作是作废旧的、换一个新的。 后面所有步骤都是为了这件事做干净。

四个待解决的问题与对应判据如下。

要解决的问题 不处理的后果 本文给的判据
六处代码各自写死了一对密钥 改一处漏五处,旧的仍然有效 全仓搜不到密钥形态的字符串
换新密钥后本地怎么跑 又写死一份,回到原点 环境变量优先、外部文件兜底(读不到环境变量时改读本地文件)、都缺就抛错
怎么防止下次再写回去 靠记性,下个月必然复发 一条能在提交前跑的检查,且通过正反向验证
怎么确认新密钥真的能用 「配置好了」但调用失败 五个真实调用全部成功,才算换完

1 为什么必须轮换,而不是只删那一行

为什么需要这一节

因为绝大多数人第一步做的是「把硬编码删掉、改成环境变量」,然后认为处理完了——但泄漏并没有停止。

版本历史是不可变的:删掉当前文件里的那一行,之前那次提交里仍然原样保存着它。任何人克隆仓库、翻一次历史,就能拿到这对密钥。删仓库、改历史、强制推送都属于「重写历史」,在有协作者或多个克隆的情况下并不可靠,也不是必要动作。

正确的处理顺序只有一种:先在云控制台作废旧密钥,再造新密钥。作废是立即生效的,之后任何持有旧密钥的调用都会被拒绝——泄漏的字符串从此变成一串无效字符。

顺序反了会怎样:先造新的、还在用旧的跑测试,旧的就一直有效;等哪天忘了作废,等于什么都没做。

2 全貌:六步轮换清单

为什么需要这一节

因为这六步有严格先后,跳步会导致「改完本地跑不起来,于是又把密钥写回去」。

六步分别是:盘点 → 造新 → 搬出 → 接读取 → 缺就抛 → 作废旧的并重编译发布。逐条说明:

步骤 做什么 做完的标志
1 盘点 全仓搜密钥形态的字符串(云厂商的密钥有固定前缀,比如腾讯云是 AKID 开头的一长串) 列出所有命中文件,本次是 6 个
2 造新 在云控制台新建一对密钥,只给需要的最小权限 拿到新的一对字符串,先存在密码管理器里
3 搬出 把新密钥写进用户目录下的凭据文件(在仓库之外),并确保它被忽略 git status 里看不到这个文件
4 接读取 代码统一走一个读取函数:环境变量优先,读不到再读凭据文件 六个调用点都改成调用这个函数
5 缺就抛 两处都拿不到时直接抛错,不要回退到任何默认值 故意删掉凭据文件跑一次,进程立刻报「凭据缺失」
6 作废 回控制台作废旧密钥;把所有依赖它的产物重新编译发布 旧密钥调用被拒,新产物全部用新密钥跑通

第 6 步里的「重新编译」容易被漏:如果打包产物里曾经把密钥内联进去,只改源码不重新构建,线上跑的还是旧的那份。

3 怎么做:一个读取函数,六个调用点

为什么需要这一节

因为「环境变量优先」这句话说起来简单,但六个调用点各写一遍就会出现六种行为——有的报错、有的返回空、有的悄悄用了默认值。

// 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 不需要文件

4 这份配置怎么进到代码里

上面给了读取函数,这里把数据流补完整,避免「配置在那、代码读这」对不上:

  1. 新密钥写进 ~/.teo-credentials.json(在仓库外,被忽略),或者由 CI 注入两个环境变量。
  2. 任一模块启动时第一次调用 getTencentCreds(),此时才真正读盘,结果进缓存。
  3. 调用点拿到 { id, key },传给云服务客户端库的构造参数。
  4. 之后的每次调用都复用缓存,不会重复读文件。

这就是「凭据在哪、什么时候被读、读了哪两个字段」的完整链路。读者要自查时,只需要在六个调用点各打断点,看第一次读发生在哪。

5 四条防回退判据,以及怎么证明它们有用

为什么需要这一节

因为「以后注意」不是机制。写一条检查很容易,难的是证明它真的会拦住人、且不会天天误报。

四条判据分别检查什么、命中后怎么处理,如下。

判据 检查什么 命中时该怎么做
禁止入仓 源码里出现密钥形态的字符串(如 AKID 开头的一长串) 拒绝提交,提示改用读取函数
缺失即抛 删掉凭据文件跑一次启动 进程必须立刻失败,不能带病运行
历史作废 旧密钥在新环境调用一次 必须被拒绝(鉴权失败),不能成功
真连一次 用新密钥做一次真实调用(不用 mock) 返回真实数据,不是「配置好了」

第二条和第四条容易被合并成一条「跑一下看看」——但它们检验的东西不同:第二条检验「失败时是否安静地继续」,第四条检验「成功时是否真的连上了」。两条都要有。

检查本身也需要验证,否则会出现「检查写了但从来不命中」。做法是正反向各跑一次:

只做正向,会得到一条「凡是出现 AKID 就报错」的粗暴规则,把文档和示例全拦下,最后大家选择跳过检查;只做反向,检查可能永远不命中。

6 验证:五项实测,全过才算换完

为什么需要这一节

因为轮换的失败方式很安静:tsc 通过、脚本能启动,但线上第一次调用才炸。所以要一次把五条全跑完。

五项验证与通过标准如下。

验证项 通过标准 本次实测
类型检查 零新增错误 通过,0 错误
语法检查 三个脚本逐个 node --check 三个都通过
云 API 鉴权 列出一个真实资源(如加速域名列表) 返回正常结果
日志查询 用新密钥查到最近一条日志 查到
数据库读取 用新密钥读两张集合,条数与预期一致 293 条 / 8 条,与预期一致

配套的两个反例也要跑:把凭据文件临时改名后启动,必须报「凭据缺失」;用旧密钥发起一次调用,必须被拒。两条都符合,才说明「缺了就停」和「旧的真废了」都成立。

总结

密钥泄漏的处理顺序不能反:先作废旧密钥,再造新密钥,再把六处硬编码收成一个「环境变量优先、文件兜底、缺就抛」的读取入口,最后用四条判据把它锁死——禁止入仓、缺失即抛、旧密钥必须被拒、新密钥必须真连一次。判据本身也要正反向验证,否则它只会变成一条被大家跳过的检查。

这套流程与云厂商无关:盘点、作废、外置、读取、缺失即抛、检查这六步对任何凭据都成立,只有密钥前缀和调用客户端是厂商特有的。

还能怎么改进

当前做法有三处边界:

一是凭据文件是明文 JSON。它只在用户目录下、不进仓库,但同机其他进程仍可读。下一步可以换成系统钥匙串(macOS 钥匙串 / Windows 凭据管理器),读取函数只换实现、不改调用点。

二是权限粒度是「一把钥匙开所有门」。六个调用点现在共用同一对密钥,一旦某个脚本被利用,影响面是整个账号。下一步可以按用途拆成多对(只读日志、只部署、只读写数据库),每对单独放。

三是检查只覆盖源码,不覆盖打包产物。如果哪天构建时又把密钥内联进产物,源码检查不会发现。下一步可以在构建后扫描产物目录,用同一套形态规则再跑一遍。

你下一步能做什么

在终端里跑一条搜索:git grep -n "AKID"。只要有命中,先别改代码——去云控制台把那对密钥作废,再回来按第 2 节的六步做。

这些内容来自哪里

这些内容来自一个真实项目的云凭据治理:一次盘点发现六个文件各自写死了同一对密钥,且这对密钥已经跟随多次提交进入了版本历史。处理过程是先作废旧密钥、再把六处收成一个读取入口,最后补上一条禁入仓检查并用正反向样例验证过。文中的验证项目都是当时的真实调用结果,不是示意。

相关文章