Better Auth Redis 二级存储实战与源码解析better-auth/redis-storage 完整指南【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth本指南围绕 Better Auth 官方 Redis 二级存储包better-auth/redis-storage展开讲解它如何承载 Better Auth 的会话缓存与限流计数等二级存储职责并沿着 CHANGELOG 的演进记录逐层拆解其源码实现、配置参数与测试契约。读完你既能直接上手接入 Redis也能理解SCAN枚举、Lua 原子脚本等底层原理掌握在生产环境安全使用它的全部要点。一、定位Better Auth 的 SecondaryStorage 与 Redis 存储Better Auth 在核心类型中定义了SecondaryStorage接口见 packages/core/src/db/type.ts用于存放会话、验证码等高频读写、可容忍丢失的临时数据。当配置了secondaryStorage后Better Auth 会默认不再把 session 表与 verification 表写入数据库见 packages/core/src/db/get-tables.ts从而减轻主数据库压力会话存储与限流计数都可以落到 Redis 这类高性能缓存中。better-auth/redis-storage就是这个接口的官方 Redis 实现基于ioredis。官方文档将其作为 Redis 二级存储的首选方案见 docs/content/docs/concepts/database.mdx 中 Redis Storage 一节它同样适用于把rateLimit等插件的数据层放到 Redis 上做分布式限流。二、安装与最小接入安装包本身非常轻量源码仅两个文件index.ts 导出入口与 redis-storage.ts 核心实现npm install better-auth/redis-storage从 package.json 可以看到它的运行时依赖关系依赖类型说明better-auth/corepeerDependency提供SecondaryStorage类型契约版本随主仓库同步ioredispeerDependency^5.0.0Redis 客户端由使用方自行安装并传入实例接入示例完整可运行import { Redis } from ioredis; import { redisStorage } from better-auth/redis-storage; const redis new Redis({ host: localhost, port: 6379, }); const auth betterAuth({ // 会话、验证码等临时数据全部落到 Redis secondaryStorage: redisStorage({ client: redis }), // 可选让限流计数也使用 Redis实现多实例共享的分布式限流 rateLimit: { enabled: true, storage: secondary-storage, }, });说明rateLimit插件的storage: secondary-storage配置依赖secondaryStorage已启用increment方法正是为此而设计详见下文。三、配置项RedisStorageConfig 完整说明RedisStorageConfig定义在 redis-storage.ts只有两个字段参数类型必填默认值作用clientRedisioredis 实例是—所有 Redis 操作均通过该客户端发出keyPrefixstring否better-auth:所有键的统一前缀用于隔离多租户/多应用数据// 使用自定义前缀避免与业务数据互相污染 redisStorage({ client: redis, keyPrefix: my-app:auth:, });从源码看prefixKey会对每个键做keyPrefix key拼接redis-storage.ts也就是说所有实际写入 Redis 的键都带上前缀而对外暴露的key则保持不带前缀的逻辑名。这个前缀不仅在get/set/delete时生效更在listKeys()/clear()的SCAN匹配与去前缀逻辑中承担关键角色见下文第四节。四、接口契约SecondaryStorage 的六个方法redisStorage()的返回值满足SecondaryStorage接口并额外扩展了listKeys与clear两个方法。对照 type.ts 的类型定义逐方法说明其语义方法签名语义get(key) unknown读取键值getAndDelete(key) unknown原子地读取并删除用于验证码等一次性数据increment(key, ttl) number原子地自增计数并返回新值键不存在时以1创建并设置ttl秒TTL 只在创建时设置、后续自增不续期set(key, value, ttl?) void写入ttl为正数时使用SETEX否则使用SETdelete(key) void删除单键listKeys/clear扩展方法列出/清空当前前缀下的全部键关键点increment是接口的硬性要求注释明确写到二级存储限流需要在一次分布式安全的操作中完成计数这正是rateLimit插件依赖它的原因。五、源码深挖每个方法背后的 Redis 实现5.1 getAndDeleteGETDEL 优先 Lua 兜底redis-storage.ts 中getAndDelete优先使用 Redis 6.2 的原生GETDEL命令通过client.call(GETDEL, key)调用成功则直接返回不产生额外的网络往返若抛出unknown command类错误如 Redis 版本 6.2则降级为 Lua 脚本实现同等的取值并删除原子语义并把supportsGetDel置为false后续调用不再重试原生命令其他错误如Authentication required直接向上抛出不做降级避免掩盖真实故障。兜底的 Lua 脚本redis-storage.tslocal value redis.call(GET, KEYS[1]) if value ~ false then redis.call(DEL, KEYS[1]) end return value这个探测-降级-缓存结果的模式保证了一致性先探测一次失败后同一进程内不再发起无意义的失败调用。5.2 increment固定窗口限流的原子计数increment使用 Lua 脚本实现自增 仅在创建时设置过期时间redis-storage.tslocal value redis.call(INCR, KEYS[1]) if value 1 then redis.call(EXPIRE, KEYS[1], ARGV[1]) end return value其核心设计意图正是 CHANGELOG 中 1.6.17 条目描述的修复由 Redis 二级存储支撑的限流窗口不再因持续流量而延长窗口的过期时间在窗口开启时一次性设定。也就是说只有第一次INCR返回 1说明窗口刚刚打开才设置EXPIRE后续自增不会重置 TTL从而保证限流窗口是固定时长的而不是滑动续期。此外increment在调用 Redis 之前还会校验ttl必须是正整数否则直接抛出TypeErrorredis-storage.ts避免把非法参数发给 Redis。5.3 setSETEX 与 SET 的分流redis-storage.ts 中ttl ! undefined ttl 0时走client.setex(key, ttl, value)一次往返完成写值设过期否则走client.set(key, value)写入永不过期的键。会话缓存场景下建议始终传入 TTL避免 Redis 中堆积过期键。5.4 listKeys 与 clear用 SCAN 替代 KEYS这是 CHANGELOG 1.6.26 条目记录的一次重要修复也是整个包最值得关注的安全与性能细节。旧实现使用KEYS命令而KEYS会同步遍历整个键空间在数据量巨大时直接阻塞 Redis 服务新实现改用SCAN游标分批遍历redis-storage.tsasync function* scanBatches(): AsyncGeneratorstring[] { let cursor 0; do { const [nextCursor, batch] await client.scan( cursor, MATCH, ${escapedPrefix}*, COUNT, SCAN_COUNT, // SCAN_COUNT 100每批采样 100 个键 ); cursor nextCursor; if (batch.length 0) yield batch; } while (cursor ! 0); }其中有两处容易被忽略的细节前缀的 glob 转义redis-storage.tsSCAN的MATCH参数是 glob 模式若keyPrefix含有* ? [ ] \等元字符未转义时会误匹配前缀之外的键导致clear()误删其他业务数据。实现通过keyPrefix.replace(/[\\*?[\]]/g, \\$)将元字符转义为字面量而实际存储键仍使用未转义的原始前缀因此keyPrefix.length仍是listKeys去前缀时正确的截取长度。空库安全scanBatches只产出非空批次clear()对空库是安全的 no-op不会发出参数为空的DELRedis 会拒绝零参数DEL并报ERR wrong number of arguments。listKeys()在聚合批次时用Set去重SCAN 可能跨页重复返回同一键并裁掉前缀后返回逻辑键名redis-storage.tsclear()则逐批DELredis-storage.ts。必须注意clear()的非原子语义源码注释与测试都明确约定clear()是尽力而为的——遍历过程中若 Redis 报错或连接中断前面已删除的批次不会回滚Promise 以 reject 结束此时未知子集的键可能已经没了。同时由于 SCAN 是弱一致枚举并发写入时一次成功的clear()也不代表库一定为空。因此需要确保完全清空如撤销全部会话或限流计数的调用方应当重试直到成功。六、测试契约行为即文档测试文件 redis-storage.test.ts基于 vitest mock 的 ioredis 客户端无需真实 Redis 实例把上述每个行为都固化为契约值得逐条对照测试用例锁定的行为uses GETDEL when it is supported支持 GETDEL 时只调call(GETDEL, ...)不触发 Luafalls back to Lua when GETDEL is unavailable首次 unknown command 后降级 Lua且只探测一次rethrows GETDEL errors that are not unknown-command非 unknown 错误直接抛出不降级increments atomically and sets the ttl only on creation首次increment设 TTL60后续自增到 2、3 不重置 TTLclears every prefixed key by paging through SCANclear()全程不调用KEYS按游标分页DELdoes not call DEL when clearing an empty store空库清空是 no-op不发出零参数 DELpropagates a mid-iteration failure, leaving earlier pages deleted明确固化中途失败、前面批次已删的非原子契约lists keys via SCAN, stripping the prefix and deduping跨页重复键去重、前缀剥离、顺序不保证escapes glob metacharacters in the prefix前缀ba[1]:转义为ba\[1\]:*后再做 SCAN 匹配rejects invalid ttl ... before mutating Redisttl 为 0/-1/1.5/NaN/Infinity 时直接抛错且不触达 Redis运行测试的命令见 package.jsonpnpm --filter better-auth/redis-storage test七、CHANGELOG 演进解读这个包是怎么变成现在这样的对照 CHANGELOG.md 的版本记录可以还原该包的两条关键演进主线其余绝大多数条目为随better-auth/core的依赖同步升级本包自身无功能变更1.6.17 —— 引入原子incrementPR #9993背景Redis 二级存储支撑的限流窗口原先可被持续流量续期延长导致限流形同虚设修复窗口过期时间在窗口开启时一次性设定后续自增不再续期落地SecondaryStorage接口新增increment方法type.tsRedis 实现用 Lua 脚本原子完成自增 仅创建时设 TTL。1.6.26 —— SCAN 取代 KEYS前缀转义与空库安全PR #10507listKeys()与clear()改为SCAN游标分页枚举避免大键空间下KEYS阻塞 Redis 服务对keyPrefix中的 glob 元字符做转义防止clear()误删前缀之外的键空库时clear()为安全的 no-op。到当前版本1.7.3package.json该包与better-auth/core保持同版本号发布节奏使用方升级主包时需同步升级此包以保证接口契约一致。八、生产实践要点小结固定窗口限流依赖increment的仅创建时设 TTL语义限流窗口时长固定、不会被流量续期计数与过期在一个 Lua 脚本内原子完成多实例部署下天然一致。前缀隔离多环境、多租户共用一个 Redis 时务必设置独立keyPrefix默认better-auth:同时注意前缀中不要出现* ? [ ] \等字符或者信任实现已做好的转义处理。版本匹配better-auth/redis-storage与better-auth/core同版本发布升级时两者需保持一致。清库语义clear()非原子、尽力而为需要彻底清空时应重试对 Redis 6.2 的环境getAndDelete会自动降级 Lua无需额外配置。只读仓库提醒以上均为查看、安装与配置方式如需修改包行为请在自己的项目中 fork 或封装不要改动当前仓库。九、继续深入包源码redis-storage.ts、index.ts单元测试行为契约redis-storage.test.ts接口定义与限流语义packages/core/src/db/type.ts官方数据库概念文档含 node-redis 与 Upstash Redis 的自实现示例docs/content/docs/concepts/database.mdx表结构裁剪逻辑配置二级存储后自动跳过 session/verification 建表packages/core/src/db/get-tables.ts版本演进记录CHANGELOG.md【免费下载链接】better-authThe most comprehensive authentication framework项目地址: https://gitcode.com/GitHub_Trending/be/better-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
