Node 后端实战 · JWT 双密钥轮转与 token 版本号多租户 SaaS 如何不停机换密钥、一键踢全设备各位看官做多租户 SaaS 后端认证是地基里的地基。地基没打牢上面盖再多业务功能都是危房。我这个后端跑在 Cloudflare Workers 上认证这一块前后改了好几版踩的坑不算少。今天不铺开讲整个鉴权体系就单挑两个最容易被忽视、但一旦出事就是大事故的点JWT 密钥怎么轮换才不停机以及怎么让一个用户的全部旧 token 瞬间失效改密码、退出所有设备。这两个需求听起来简单真落到无状态 JWT 边缘 KV 的架构上有不少反直觉的地方。下面把我实际用的方案、代码、以及为什么这么设计一次讲透。先说技术选型jose HS256Workers 上签发校验 JWT我选的是jose这个库——它基于 Web Crypto在 Workers 运行时里是一等公民不用额外 polyfill。算法用HS256 对称签名而不是很多人下意识选的 RS256。原因很实在RS256 要管公私钥对公钥短但私钥长Workers 上做非对称签名开销也大而 HS256 一个字符串密钥搞定密钥短、验签快、好轮换。多租户 SaaS 里签发量不小对称签名更划算。我的 token 里塞了这些业务声明claims字段类型含义substring用户 IDsubjecttidstring | null租户 ID平台超管为 nullrolestring角色租户管理员/员工/平台超管等type“access” | “refresh”token 类型区分访问令牌与刷新令牌jtistring唯一标识用于单设备吊销黑名单tvnumbertoken 版本号用于全设备登出mrpnumber强制改密标志1必须改密后才放行并且我刻意用了双 token 结构维度access tokenrefresh token有效期1 小时ACCESS_TTL36007 天REFRESH_TTL604800用途调业务接口匿名端点换发新令牌中间件受保护路由只允许它进入仅/refresh接受别处一律拒绝access 短命降低泄露风险refresh 长命减少反复登录refresh 是匿名端点只能用来换发绝不能当业务令牌用——这点后面代码会强制校验。痛点一密钥怎么轮换才不停机JWT 一旦签发服务端没有存着它校验全靠那把密钥。于是麻烦来了密钥泄露要换、合规要定期轮转可线上几十万活跃 token 都是旧密钥签的你直接换密钥所有用户瞬间掉线。我的解法是双密钥候选列表。验签时不只试一把密钥而是依次试「当前密钥 上一轮密钥」// lib/jwt.ts —— 验签遍历多密钥支持平滑轮换exportconstverifyTokenasync(token:string,secrets:string[]):PromiseJwtPayload{letlastErr:unknown;for(constsecretofsecrets){if(!secret)continue;try{const{payload}awaitjwtVerify(token,encodeKey(secret),{algorithms:[HS256]});return{/* ...还原 claims... */};}catch(e){lastErre;// 这把密钥验不过试下一把}}throwerr(AUTH_INVALID,lastErrinstanceofError?lastErr.message:invalid token);};取密钥候选的地方把两个环境变量都拉上JWT_SECRET_PREV为空时自动过滤掉// 当前密钥 上一轮密钥constsecretsOf(env:Bindings):string[][env.JWT_SECRET,env.JWT_SECRET_PREV].filter((s):sisstringBoolean(s));轮换操作本身是可逐步照做的用wrangler secret putWorkers 的密钥不走代码仓库走环境变量步骤命令 / 操作说明1wrangler secret put JWT_SECRET_PREV填入旧密钥先把旧密钥挪到 PREV 槽此时两把都能验签2wrangler secret put JWT_SECRET填入新密钥新签发的 token 全部用新密钥旧 token 仍能被 PREV 验过3观察 1~2 个 access 有效期≥1h确认线上无异常、旧 token 基本自然过期4wrangler secret put JWT_SECRET_PREV填入空串或删掉彻底废弃旧密钥轮换完成关键就在第 1 步先让 PREV 顶上旧密钥再换 JWT_SECRET。这段重叠期内新旧 token 都能验用户无感知。等旧 token 自然过期得差不多了再清掉 PREV。整套流程零停机。痛点二怎么让旧 token「瞬间失效」这是无状态 JWT 最反直觉的地方token 发出去就不在服务端手里了根本没有删 token这回事。那用户改了密码、或者点了退出所有设备难道要让那台丢了的手机还能用旧 token 访问 7 天我的方案是token 版本号tv KV 比对。登录签发时把用户当前的版本号写进 token// routes/auth.ts —— 登录签发tv 来自 KVconsttvawaitgetTv(c.env.KV,user.id);constaccessTokenawaitsignToken({sub:user.id,tid:user.tenantId,role:user.role,type:access,jti:crypto.randomUUID(),tv,mrp},c.env.JWT_SECRET,JWT.ACCESS_TTL,);每次请求中间件拿 token 里的tv跟 KV 里的最新值比对不上就失效// middleware/auth.ts —— tv 比对实现全设备登出consttvawaitgetTv(c.env.KV,claims.sub);if(tv!claims.tv)throwerr(AUTH_EXPIRED,token superseded);而退出所有设备和改密码本质都是把 KV 里的版本号自增一下// routes/auth.ts —— 退出所有设备authRoutes.post(/logout-all,authMiddleware,async(c){constuserc.get(user);awaitincrTv(c.env.KV,user.id);// 版本号 1所有旧 token 的 tv 立即对不上returnok(c,{success:true});});incrTv写在 KV 封装层里// lib/kv.ts —— tv 自增全设备登出exportconstincrTvasync(kv:KVNamespace,userId:string):Promisenumber{constnext(awaitgetTv(kv,userId))1;awaitsetTv(kv,userId,next);returnawaitgetTv(kv,userId);// 写后读返回实际值};同一套机制改密码也会触发incrTv所以旧密码换完所有设备的会话一并失效——这正是用户期望的行为。这里有个单设备 vs 全设备的粒度区分别混了失效手段存储介质粒度触发场景bl:jti黑名单KVTTL剩余有效期单设备/单 refresh单设备退出登录、refresh 换发时吊销旧 jtitv:userId版本号KV无 TTL 长期全设备改密码、退出所有设备exp自然过期token 自带单 token时间到了自动失效简单说jti 黑名单管这一台tv 版本号管这个人。两者配合单设备和全设备吊销都能精确控制。两个真实踩过的边界坑坑一KV 没有 CASincrTv 不是严格原子的。Cloudflare KV 不支持 compare-and-swap高并发下读-改-写可能漏加。我的处理是写后读返回实际值并在注释里写清楚了语义并发下返回值不小于实际值宁可不精确也绝不会低估——宁可多踢一次不能少踢导致该失效的 token 还活着。安全语义优先计数精确性靠边。坑二强制改密别把用户逼进死局。系统有个mrp1强制改密标志管理员重置密码后要求首登必改。中间件里mrp1会拦截除改密/登出外的所有接口返回 423。但问题来了如果强制改密还要求验旧密码而那个临时密码压根没传达给用户用户就卡死在过不了 423 又不知道旧密码的死循环里。所以我在change-password里做了豁免强制改密场景下免验旧密码。这样管理员重置后用户拿临时密码进来直接设新密码即可不会被自己的安全机制关在门外。安全设计最怕这种为了安全反而把人锁外面的副作用这个细节值得记一笔。小结回过头看这套认证设计里真正扛事的就是三样东西双密钥候选 PREV 槽位——让密钥轮换零停机tv 版本号 KV 比对——让无状态 JWT 也能主动踢人jti 黑名单——在 tv 之上补一层单设备精度。它们都不复杂但每一个都对应一个真实会发生的故障场景。架构决策不是比谁花哨是比谁把边界情况想得周全。各位看官如果也在 Workers 上做认证这套可以直接抄密钥和版本号这两把锁建议从第一天就上。发财的小手点个小赞咱们下一篇接着聊多租户的数据隔离。相关阅读Node 后端实战 · 为什么用 Cloudflare Workers D1 扛起了整个多租户 SaaS 后端架构决策全景复盘Node 后端实战 · Cloudflare Workers 踩坑实录TOML、D1 默认 local、CORS 与部署排障Node 后端实战 · D1 那些坑100 参数上限逼出的批量写入重构Mac 本地部署 AI 生图从零跑通 FLUX 与 Z-Image 的完整步骤附完整脚本NodeJS Koa 后端用户会话管理JWT, Session长短Token本文一次性讲明白node 后端和浏览器前端有关 RSA 非对称加密的完整实践 前后端匹配的代码演示Nodejs 实现 Mysql 数据库的全量备份的代码演示安装和配置 Nginx 和 Mysql —— 一步一步配置 Ubuntu Server 的 NodeJS 服务器详细实录6PVE 虚拟机安装 Ubuntu Server V24 系统 —— 一步一步安装配置基于 Ubuntu Server 的 NodeJS 服务器详细实录1本文由 FungLeo 主导Deepseek 优化校阅转发请注明首发地址谢谢大家