API key 从生成到吊销:前缀、校验位、只存哈希,以及吊销后多久才真正失效(Node.js)
做付费 API 的时候,发 key 往往是最早写完、也最早被忘掉的一块。crypto.randomBytes(32).toString("hex") 生成一串,存进表里,请求进来 WHERE api_key = ? 查一下,就能跑了。直到第一次有客户来说「我的 key 好像被同事提交到公开仓库了」,才发现好几件事没想过:库里存的是不是明文?吊销以后多久才真正失效?客户要换 key,旧的能不能多撑一天,让他慢慢部署?
这篇按一把 key 从生成到吊销的顺序,把这些问题过一遍。后半段是重点:多台机器各自加了缓存以后,「吊销」到底什么时候生效,以及拒绝缓存一个看起来很合理的写法,怎么让别人把正常客户挡在门外。
先交代背景:我是 UsageRail 的三个创始人之一。UsageRail 给卖 API 的团队发 key、按客户限流和算额度,再用开发者自己的 Stripe 账号做 API 按量计费。文中的 key 格式和后面几个坑都来自我们自己的实现,代码是为这篇文章另写的简化版,只用 Node.js 内置模块(node:crypto、node:zlib、node:sqlite),在 Node 26.3 上跑过,输出原样贴出。
一、一把 key 拆成五段
我们用的格式长这样:
acme_live_29Hv1QhZLoUOeQc5Tl8Pgf1UzDmv57MPIMMRC6sQ4UKQCB
从左到右:
acme:前缀,一般是产品名,2 到 10 个小写字母或数字;live:环境,live或test;29Hv1QhZ:8 位 key ID;LoUOeQc5…RC6sQ:32 位 secret,真正要保密的只有这一段;4UKQCB:6 位校验位。
前缀和环境是给人看的:客户手上有好几家的 key,看前缀就知道是哪家的;test key 被配进生产环境,看一眼日志就能发现。前缀固定了,密钥扫描和日志脱敏也好按它写正则。GitHub 2021 年把 token 改成 ghp_ 这类带前缀的格式,Stripe 用 sk_live_ 和 sk_test_ 区分环境,都是这个考虑。
key ID 明文存在库里,它不是秘密。校验时按它查那一行,不用拿哈希去比一整张表;客户找客服时报 key ID 就够了,不用把整把 key 贴过来。
校验位是前面所有字符的 CRC32,转成 base62 后补齐到 6 位。它不是安全措施,CRC32 谁都会算。它挡的是抄错一个字符的 key 和随手乱填的字符串,这类请求在格式检查那一步就回 401,不用查库。我们官网上有个在浏览器里跑的 API key 生成器,生成的就是这个格式,旁边可以粘一把 key 进去,改一个字符就能看到校验失败。
生成和解析的代码:
import { createHash, randomBytes } from "node:crypto";
import { crc32 } from "node:zlib";
const BASE62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
// 256 不是 62 的整数倍,直接 byte % 62 会让前 8 个字符出现得多一点。
// 248 = 62 × 4,大于等于 248 的字节丢掉不用
function randomBase62(length) {
let out = "";
while (out.length < length) {
for (const byte of randomBytes(length * 2)) {
if (byte < 248) out += BASE62[byte % 62];
if (out.length === length) break;
}
}
return out;
}
function toBase62(value, width) {
let out = "";
do {
out = BASE62[value % 62] + out;
value = Math.floor(value / 62);
} while (value > 0);
return out.padStart(width, "0");
}
export const checksum = (body) => toBase62(crc32(body), 6);
export function generateKey(prefix, env) {
const keyId = randomBase62(8);
const body = `${prefix}_${env}_${keyId}${randomBase62(32)}`;
return { key: body + checksum(body), keyId };
}
const KEY_RE = /^([a-z0-9]{2,10})_(live|test)_([0-9A-Za-z]{8})([0-9A-Za-z]{32})([0-9A-Za-z]{6})$/;
// 格式和校验位都对才返回 key ID,否则返回 null。这一步不碰数据库
export function parseKey(key) {
const m = KEY_RE.exec(key);
if (!m || checksum(key.slice(0, -6)) !== m[5]) return null;
return { env: m[2], keyId: m[3] };
}
export const sha256Hex = (text) => createHash("sha256").update(text).digest("hex");
有两处要注意。随机数必须来自 crypto.randomBytes,不能用 Math.random()。另外是 base62 的取模:一个字节有 256 种取值,256 不是 62 的整数倍,直接 byte % 62 的话,前 8 个字符出现的概率会比别的字符略高。代码里把 248 及以上的字节丢掉,248 正好是 62 的 4 倍。32 位 base62 大约是 190 bit 的随机性,比常说的 128 bit 下限高出不少。zlib.crc32 是 Node 较新的版本才内置的,老版本得自己写查表。
二、库里存什么
CREATE TABLE api_keys (
key_id TEXT PRIMARY KEY, -- 明文存,不是秘密
key_hash TEXT NOT NULL, -- SHA-256(完整 key),hex
customer_id TEXT NOT NULL,
name TEXT NOT NULL,
created_at INTEGER NOT NULL, -- 毫秒时间戳,Postgres 里用 timestamptz
expires_at INTEGER, -- 轮换时才设
revoked_at INTEGER,
last_used_at INTEGER
);
CREATE INDEX api_keys_by_customer ON api_keys (customer_id);
完整的 key 不进库。库里存的是 SHA-256(完整 key),原文只在创建时给客户看一次,之后谁也拿不回来,丢了只能换一把新的。这样即使库被拖走,对方拿到的哈希也不能直接拿去调你的 API。
这里用 SHA-256 而不是 bcrypt,是因为两者要防的东西不一样:慢哈希是给人设的弱密码准备的,190 bit 的随机串用多快的哈希都猜不出来;而 key 每个请求都要校验一次,换成慢哈希只会拖慢正常请求。
last_used_at 在出事时用得上:客户说 key 可能泄露了,先看它最近一次被用是什么时候。生产环境里别每个请求都写一次这一列,可以在内存里攒着,或者距上次更新超过一分钟再写。
还有一条很容易漏:key 原文不能进日志。请求日志里记 key ID,错误上报时把 Authorization 头去掉。
三、校验的顺序
完整的 store.mjs,后面几节都用它:
import { readFileSync } from "node:fs";
import { DatabaseSync } from "node:sqlite";
import { timingSafeEqual } from "node:crypto";
import { generateKey, parseKey, sha256Hex } from "./keys.mjs";
const HOUR = 3600_000;
const MAX_ACTIVE_KEYS = 10;
const CLOCK_MARGIN = 30_000; // 比过期时间早 30 秒判失效,抵消各台机器的时钟误差
export function openDb() {
const db = new DatabaseSync(":memory:");
db.exec(readFileSync(new URL("./schema.sql", import.meta.url), "utf8"));
return db;
}
// 「有效」= 没吊销,且没设过期或者还没到期
const ACTIVE = "revoked_at IS NULL AND (expires_at IS NULL OR expires_at > ?)";
export function createKey(db, customerId, name, now) {
const { n } = db.prepare(`SELECT count(*) AS n FROM api_keys WHERE customer_id = ? AND ${ACTIVE}`).get(customerId, now);
if (n >= MAX_ACTIVE_KEYS) throw new Error("key_limit_reached");
const { key, keyId } = generateKey("acme", "live");
db.prepare("INSERT INTO api_keys (key_id, key_hash, customer_id, name, created_at) VALUES (?, ?, ?, ?, ?)")
.run(keyId, sha256Hex(key), customerId, name, now);
return { key, keyId }; // 完整 key 只在这里出现一次
}
export function verifyKey(db, rawKey, now) {
const parsed = parseKey(rawKey ?? "");
if (!parsed) return { ok: false, reason: "bad_format" }; // 没查库
const row = db.prepare("SELECT * FROM api_keys WHERE key_id = ?").get(parsed.keyId);
const hash = Buffer.from(sha256Hex(rawKey), "hex");
if (!row || !timingSafeEqual(Buffer.from(row.key_hash, "hex"), hash)) {
return { ok: false, reason: "unknown_key" };
}
if (row.revoked_at !== null) return { ok: false, reason: "revoked", customerId: row.customer_id };
if (row.expires_at !== null && row.expires_at - CLOCK_MARGIN <= now) {
return { ok: false, reason: "expired", customerId: row.customer_id };
}
db.prepare("UPDATE api_keys SET last_used_at = ? WHERE key_id = ?").run(now, row.key_id);
return { ok: true, customerId: row.customer_id, keyId: row.key_id };
}
export function rotateKey(db, keyId, now, graceMs = 24 * HOUR) {
if (graceMs < HOUR || graceMs > 30 * 24 * HOUR) throw new Error("grace must be 1h..30d");
const old = db.prepare("SELECT * FROM api_keys WHERE key_id = ?").get(keyId);
// 已经在倒计时里的不再轮换:该换的是轮换出来的那把新 key
if (!old || old.revoked_at !== null || old.expires_at !== null) throw new Error("not_rotatable");
// 旧 key 在宽限期里还占名额,所以轮换可以临时超出上限,但只能多一把
const { n } = db.prepare(`SELECT count(*) AS n FROM api_keys WHERE customer_id = ? AND ${ACTIVE}`).get(old.customer_id, now);
if (n > MAX_ACTIVE_KEYS) throw new Error("key_limit_reached");
const { key, keyId: newKeyId } = generateKey("acme", "live");
db.exec("BEGIN");
db.prepare("UPDATE api_keys SET expires_at = ? WHERE key_id = ?").run(now + graceMs, keyId);
db.prepare("INSERT INTO api_keys (key_id, key_hash, customer_id, name, created_at) VALUES (?, ?, ?, ?, ?)")
.run(newKeyId, sha256Hex(key), old.customer_id, old.name, now);
db.exec("COMMIT");
return { key, keyId: newKeyId };
}
export function revokeKey(db, keyId, now) {
db.prepare("UPDATE api_keys SET revoked_at = ? WHERE key_id = ? AND revoked_at IS NULL").run(now, keyId);
}
verifyKey 的顺序是:格式和校验位 → 按 key ID 查那一行 → 比较哈希 → 吊销和过期。
- 格式不对就直接返回,一次数据库都不碰。
- 哈希比较用
timingSafeEqual。比的是哈希,计时攻击能拿到的东西其实很有限,但它没有成本,没理由不用。 - 过期判断提前 30 秒。几台机器的时钟不会完全一致,宁可早半分钟失效,也别让某台机器多放行。
- 哈希已经对上、只是吊销或过期了,返回里带上
customerId。这时候我们知道是谁,401 可以记在这个客户名下,客服查「为什么突然 401」时有据可查。
跑一下(run-basic.mjs 前半段):
新 key: acme_live_29Hv1QhZLoUOeQc5Tl8Pgf1UzDmv57MPIMMRC6sQ4UKQCB
库里存的: [Object: null prototype] {
key_id: '29Hv1QhZ',
key_hash: 'dc98bf23105567bc3fede80d6b342cce11cb80a1a8722047b9620064f3274ec8',
customer_id: 'cus_42'
}
正确的 key { ok: true, customerId: 'cus_42', keyId: '29Hv1QhZ' }
改了一个字符 { ok: false, reason: 'bad_format' }
真 ID + 假 secret { ok: false, reason: 'unknown_key' }
第三个 key 是拿真 key 的前 18 个字符(前缀加 key ID)配一段随机 secret,再按规则算好校验位拼出来的。格式检查照样放行,最后靠哈希比较才拦下,这就是校验位不算安全措施的原因。
四、轮换:新旧 key 并存一段时间
客户换 key 时最怕新 key 还没部署完,旧 key 已经失效。所以轮换是新建一把,同时给旧的设一个过期时间,默认 24 小时,可以设 1 小时到 30 天,见上面的 rotateKey。
轮换和名额要放在一起想。每个客户最多 10 把有效 key,旧 key 在宽限期里仍然有效,也仍然占名额。如果轮换受名额限制,已经用满 10 把的客户就没法轮换;如果完全不管,对同一把 key 反复轮换就能变出任意多把。代码里的折中是轮换可以临时超出上限,但只能多一把,已经在倒计时里的 key 也不能再轮换。
轮换后 23 小时,旧 key { ok: true, customerId: 'cus_42', keyId: '29Hv1QhZ' }
轮换后 23 小时,新 key { ok: true, customerId: 'cus_42', keyId: 'ARWEk4hP' }
轮换后 24 小时,旧 key { ok: false, reason: 'expired', customerId: 'cus_42' }
再轮换旧 key: not_rotatable
吊销后,新 key { ok: false, reason: 'revoked', customerId: 'cus_42' }
第 11 把: key_limit_reached
轮换 k0:成功
再轮换 k1: key_limit_reached
五、泄露以后:吊销到底多久生效
先说一个常见的误用:确认泄露时不要用轮换。轮换给旧 key 留了宽限期,泄露的 key 在这段时间里照样能用。应该直接吊销,再给客户建一把新的。
单机直接查库的话,revoked_at 一提交,下一个请求就会被拒。但生产环境很少这么跑,每个请求查一次库太贵,于是会在每个应用实例里加一层缓存。加了缓存,吊销的生效时间就变成了缓存的 TTL。
下面是一种很常见的写法:通过的结果按完整 key 的哈希缓存 60 秒,拒绝的结果也缓存 60 秒,免得有人拿乱填的 key 一直打数据库。
import { parseKey, sha256Hex } from "./keys.mjs";
import { verifyKey } from "./store.mjs";
// 每个应用实例在数据库前面挡一层缓存
export class CachedVerifier {
constructor(db, { ttl = 60_000, rejectTtl = 60_000, rejectBy = "id+hash" } = {}) {
Object.assign(this, { db, ttl, rejectTtl, rejectBy });
this.accepted = new Map(); // 完整 key 的哈希 -> 校验结果
this.rejected = new Map(); // 见 rejectKey()
}
rejectKey(keyId, hash) {
return this.rejectBy === "id" ? keyId : `${keyId}:${hash}`;
}
verify(rawKey, now) {
const parsed = parseKey(rawKey ?? "");
if (!parsed) return { ok: false, reason: "bad_format" };
const hash = sha256Hex(rawKey);
const hit = this.accepted.get(hash);
if (hit && now < hit.cachedUntil) return hit.result;
const rejectedUntil = this.rejected.get(this.rejectKey(parsed.keyId, hash));
if (rejectedUntil && now < rejectedUntil) return { ok: false, reason: "cached_reject" };
const result = verifyKey(this.db, rawKey, now);
if (result.ok) this.accepted.set(hash, { result, cachedUntil: now + this.ttl });
else this.rejected.set(this.rejectKey(parsed.keyId, hash), now + this.rejectTtl);
return result;
}
}
测试脚本 run-cache.mjs 用的是假时钟,不用真等一分钟:
import { checksum, generateKey } from "./keys.mjs";
import { createKey, openDb, revokeKey } from "./store.mjs";
import { CachedVerifier } from "./cache.mjs";
const t0 = Date.parse("2026-11-16T09:00:00Z");
const sec = (s) => t0 + s * 1000;
const db = openDb();
// 1. 吊销以后,缓存里的结果还能用多久
const leaked = createKey(db, "cus_42", "ci", sec(0));
const instance = new CachedVerifier(db, { ttl: 60_000 });
console.log("t=0 ", instance.verify(leaked.key, sec(0)).ok);
revokeKey(db, leaked.keyId, sec(1));
console.log("t=1 吊销");
console.log("t=30 ", instance.verify(leaked.key, sec(30)).ok);
console.log("t=61 ", instance.verify(leaked.key, sec(61)).ok);
// 2. 拒绝结果只按 key ID 缓存的后果
const fresh = createKey(db, "cus_7", "production", sec(100));
const forgedBody = fresh.key.slice(0, 18) + generateKey("acme", "live").key.slice(18, 50);
const forged = forgedBody + checksum(forgedBody);
for (const rejectBy of ["id", "id+hash"]) {
const node = new CachedVerifier(db, { rejectBy });
node.verify(forged, sec(100)); // 攻击者先发一个伪造的
const real = node.verify(fresh.key, sec(105)); // 5 秒后客户用真 key
console.log(`按 ${rejectBy.padEnd(7)} 缓存拒绝:真 key ->`, real);
}
输出:
t=0 true
t=1 吊销
t=30 true
t=61 false
按 id 缓存拒绝:真 key -> { ok: false, reason: 'cached_reject' }
按 id+hash 缓存拒绝:真 key -> { ok: true, customerId: 'cus_7', keyId: 'nNtYSE2p' }
前四行是吊销:第 1 秒就吊销了,这台实例到第 61 秒才开始拒绝。每台实例写缓存的时刻不一样,实例越多,全部失效的时间拖得越散。客户点了吊销,到这把 key 真正没用,中间隔着一个 TTL,这个数应该写进文档。
想缩短它,可以把 TTL 调短(查库变多),可以吊销时广播清缓存(多一套消息通道),也可以像我们的 SDK 那样,让每个实例在内存里放一份 key 列表(只有 key ID、哈希、状态和过期时间),每 15 秒增量同步一次,正常情况下吊销后约 20 秒全部生效。怎么选都行,但这个数你自己得清楚。
后两行是拒绝缓存的问题。只按 key ID 缓存拒绝结果,乍看很合理:这把 key 刚被拒过,60 秒内就别再查了。问题在于 key ID 不是秘密,它会出现在日志、控制台截图、客服工单里。有人拿到某个客户的 key ID,配一段随便的 secret,自己算好校验位发一次请求,这个 key ID 就进了拒绝缓存。接下来 60 秒,客户拿真 key 来也会被拒,对方每分钟发一次就能一直挡着。改成按「key ID + 哈希」记,伪造的请求只会挡住它自己那个组合。我们 SDK 里的拒绝缓存就是这么记的,代码注释里专门写了为什么不能只按 key ID。
六、几个容易漏的地方
删除过期 key 要留墓碑。 吊销和过期的 key 迟早要从表里清掉。如果各实例靠增量同步拿变更,直接 DELETE 掉的话,增量里看不到这次删除,手里有这把 key 的实例会一直留着它。我们的做法是删除时写一条墓碑,保留 30 天;实例的同步游标超过 7 天没更新,就不给增量,直接发全量。
从备份恢复数据库,吊销会被撤销。 恢复点之后吊销的 key,在恢复出来的库里又变回有效。我们把吊销、停用客户这类操作先写进一份只追加的重放日志,写成功了才改库;恢复以后先把日志补一遍,再启动服务。
新建 key 时通知客户本人。 key 不一定是客户自己建的,可能是同事,也可能是拿到他账号的人。我们在新 key 创建时给客户发邮件,不是他建的可以马上吊销。邮件只发给验证过邮箱的客户,不然任何人都能借这封信往任意地址发邮件。
吊销要随时能做。 账号欠费、只读或降级的时候,很多操作会被锁住,但吊销 key、停用客户这类收紧权限的操作不能锁,否则泄露的 key 收不回来。
最后
UsageRail 把 key 列表同步到每个实例,SDK 在你的 API 进程里校验已经同步到的 key,还没同步到的新 key 才去问服务端;客户可以在门户里自己建、轮换和吊销 key。自己实现的话,上面的简化代码可以当参考。换到 Postgres 要改数据库调用和时间类型,last_used_at 最好改成批量写。
作者:Super Lede,UsageRail 联合创始人。

浙公网安备 33010602011771号