Better Auth Redis Storage 实战指南:用 Redis 为会话缓存与限流构建次级存储
Better Auth Redis Storage 实战指南:用 Redis 为会话缓存与限流构建次级存储
导读
@better-auth/redis-storage 是 Better Auth 官方提供的 Redis 次级存储(secondary storage)实现,用于将会话缓存与速率限制的计数器存放到 Redis 中,从而在多实例部署下获得共享、分布式的认证状态。本文以该包源码为主线,讲解其安装接入、配置项语义、核心 API 与底层 Redis 命令映射、原子性保证以及在大规模清理场景下的工程取舍,帮助读者在生产环境中正确、安全地使用它。
一、为什么需要 secondary storage:Redis 在 Better Auth 中的定位
Better Auth 的主数据库用于持久化用户、会话等核心业务数据,但会话令牌的快速读取与限流计数这类高频、短生命周期数据,如果全部落到主数据库,会给数据库带来不必要的压力。为此,Better Auth 在核心层抽象了 SecondaryStorage 接口,允许将这类数据放入 Redis、内存等更快的存储中。
接口定义位于 packages/core/src/db/type.ts,共六个方法:
get(key):按 key 读取值;getAndDelete(key):原子地读取并删除一个 key;increment(key, ttl):对 key 原子加一,返回自增后的值;key 不存在时以值1创建,并仅在该次创建时应用ttl(单位为秒),后续自增不会延长过期时间,从而保证计数器在一个固定窗口后过期;set(key, value, ttl?):写入值,可选 TTL;delete(key):删除 key。
@better-auth/redis-storage 正是该接口的一个开箱即用的 Redis 实现,对应仓库包 packages/redis-storage。它的场景非常明确:会话缓存与速率限制。
二、安装与最小接入
安装命令:
npm install @better-auth/redis-storage
根据 packages/redis-storage/package.json,该包以 ESM 形式发布("type": "module",入口 dist/index.mjs),并且把 ioredis(^5.0.0)与 @better-auth/core 声明为 peer dependency,因此还需要确保项目中安装了 Redis 客户端:
npm install ioredis
最小接入方式如下(完整示例见 src/redis-storage.ts 的 JSDoc):
import { Redis } from "ioredis";
import { redisStorage } from "@better-auth/redis-storage";
import { betterAuth } from "better-auth";
const redis = new Redis({
host: "localhost",
port: 6379,
});
const auth = betterAuth({
// ...其余配置
secondaryStorage: redisStorage({ client: redis }),
});
接入后,会话令牌的读写与限流计数即由 Redis 承载。包对外只导出一个工厂函数和一个配置类型(见 src/index.ts):
export { type RedisStorageConfig, redisStorage } from "./redis-storage";
三、配置项详解:client 与 keyPrefix
RedisStorageConfig 只有两个字段(定义见 src/redis-storage.ts):
| 配置项 | 类型 | 说明 | 默认值 |
|---|---|---|---|
client |
Redis(ioredis 实例) |
必填,所有 Redis 命令都通过该实例发出 | 无 |
keyPrefix |
string |
可选,写入 Redis 的所有 key 的前缀 | "better-auth:" |
在实现内部,前缀通过 prefixKey 函数拼接到每个 key 上(源码):
const prefixKey = (key: string): string => `${keyPrefix}${key}`;
也就是说,会话令牌 session-abc 实际会以 better-auth:session-abc 的形式存入 Redis。生产环境中建议为不同环境(如 dev / staging / prod)配置不同的前缀,避免共享 Redis 实例时不同环境之间互相污染;例如传入 keyPrefix: "better-auth:prod:"。
需要注意:keyPrefix 会被当作 SCAN 的 MATCH 模式的一部分参与 glob 匹配,因此源码中对前缀中的 glob 元字符(* ? [ ] \)做了转义处理(源码),确保 clear() 不会误删带其他前缀的 key(详见第六节)。
四、核心 API 与底层 Redis 命令映射
工厂函数返回的对象实现了 SecondaryStorage 接口,并额外扩展了 listKeys 与 clear 两个运维方法。各方法与 Redis 命令的对应关系如下。
4.1 get / set / delete:直接命令映射
get(key)→client.get(prefixKey(key)):读字符串值;set(key, value, ttl?):当ttl > 0时使用SETEX(一次调用同时设置值与过期时间),否则使用普通SET(源码);delete(key)→client.del(prefixKey(key))。
4.2 getAndDelete:GETDEL 优先,Lua 兼容降级
getAndDelete 需要“读取并删除”的原子性。现代 Redis(6.2+)提供了原生的 GETDEL 命令,实现优先尝试它(源码):
async getAndDelete(key: string) {
const prefixedKey = prefixKey(key);
if (supportsGetDel) {
try {
return await client.call("GETDEL", prefixedKey);
} catch (error) {
if (!isUnknownCommandError(error)) throw error;
supportsGetDel = false;
}
}
return client.eval(getAndDeleteScript, 1, prefixedKey);
}
这里有一个值得注意的工程细节:
- 模块级变量
supportsGetDel会在第一次遇到unknown command 'GETDEL'错误时置为false,此后永久降级,避免每个请求都重复探测; - 降级路径使用一段 Lua 脚本保证原子性(源码):
local value = redis.call("GET", KEYS[1])
if value ~= false then
redis.call("DEL", KEYS[1])
end
return value
- 只有“未知命令”错误才触发降级;其他错误(如
Authentication required)会原样抛出。对应的测试覆盖在 test/redis-storage.test.ts。
源码中留有 TODO 注释,计划在下一个 breaking 分支中要求 Redis >= 6.2 并移除这段 Lua 兼容逻辑(源码)。因此如果生产 Redis 版本较低(< 6.2),该降级路径会保证功能可用。
4.3 increment:INCR + 首次创建时才设置 EXPIRE
限流计数要求“自增”是分布式的原子操作,且计数窗口必须是固定窗口(从第一次请求开始计时,不能被后续请求无限续期)。实现用一段 Lua 脚本完成(源码):
local value = redis.call("INCR", KEYS[1])
if value == 1 then
redis.call("EXPIRE", KEYS[1], ARGV[1])
end
return value
语义解读:
INCR原子自增;当返回值为1时说明这是该窗口的第一次自增(key 刚被创建),此时才调用EXPIRE设置 TTL;- 后续自增返回
2、3、…,不再触碰 TTL,因此计数窗口从第一个请求开始固定计时,不会被延长——这正是SecondaryStorage接口对increment的约定(见 packages/core/src/db/type.ts 的注释)。
此外,increment 在调用 Redis 之前会校验 TTL(源码):
if (!Number.isInteger(ttl) || ttl <= 0) {
throw new TypeError("Redis storage increment ttl must be a positive integer");
}
即 TTL 必须是正整数;0、负数、小数、NaN、Infinity 都会在触碰 Redis 之前抛出 TypeError。测试用 it.each 逐一验证了这些非法值(test/redis-storage.test.ts)。
4.4 测试对原子语义的固定
test/redis-storage.test.ts 中的用例验证了“TTL 只在创建时设置一次”的语义:连续三次 increment("rate:1", 60) 依次返回 1、2、3,而 TTL 始终为 60 不变。这意味着固定窗口限流的正确性由 Lua 脚本与测试双重保障。
五、与限流器的集成:increment 是如何被消费的
increment 的消费方是 Better Auth 的限流器。在 packages/better-auth/src/api/rate-limiter/index.ts 中,当 rateLimit.storage 配置为 "secondary-storage" 时,限流器的 consume 直接调用 secondaryStorage.increment(key, window):
const increment = ctx.options.secondaryStorage?.increment;
if (!increment) {
throw new BetterAuthError(
"Secondary-storage rate limiting requires SecondaryStorage.increment.",
);
}
return {
consume: async (key, rule) => {
// increment 在首次使用时以 ttl = window 创建计数器且永不延长,
// 因此计数器在窗口开启后固定时间过期;自增后的值即窗口内请求数。
const count = await increment(key, ttlFor(rule.window));
if (count <= rule.max) {
return { allowed: true, retryAfter: null };
}
return { allowed: false, retryAfter: rule.window };
},
};
这段代码清晰地展示了分布式限流的模式:“检查并自增”在请求阶段一步完成,不存在先读后写之间的竞态窗口(源码注释见 index.ts),这正是 SecondaryStorage.increment 必须原子实现的原因。将限流存储从进程内内存切换到 Redis 后,多个实例共享同一份计数器,限流即可在多节点部署下全局生效。
六、运维能力:listKeys 与 clear 的工程取舍
除了 SecondaryStorage 接口要求的方法,该实现还提供了两个扩展方法:listKeys()(列出前缀下所有 key)与 clear()(清空前缀下所有 key)。二者都基于 SCAN 游标分页而非阻塞式的 KEYS 命令实现——KEYS 会单次阻塞地遍历整个 keyspace,在数据量大时会卡住 Redis 服务,而 SCAN 每次只处理一个游标批次,不会阻塞(源码注释见 src/redis-storage.ts)。
6.1 SCAN 的实现细节
- 每轮调用
client.scan(cursor, "MATCH",${escapedPrefix}*, "COUNT", 100),SCAN_COUNT = 100只是给服务端的提示而非硬性限制(源码); - 只有非空批次才会
yield,保证clear()在空存储时不会发出非法的零参数DEL(Redis 会拒绝零参数的 DEL); - SCAN 可能在多页中重复返回同一个 key,因此
listKeys使用Set去重(源码)。
6.2 前缀转义的必要性
SCAN 的 MATCH 参数是 glob 模式,若前缀中包含 * ? [ ] \ 等元字符而未转义,就会匹配到无关 key,导致 clear() 删除本存储之外的数据。源码通过 keyPrefix.replace(/[\\*?[\]]/g, "\\$&") 构造转义后的匹配模式,而存储的 key 仍使用原始前缀(源码),这样 listKeys 中 key.slice(keyPrefix.length) 剥离前缀的长度依然正确。测试用例 ba[1]: 前缀验证了转义行为(test/redis-storage.test.ts)。
6.3 clear() 的语义边界(务必阅读)
源码用大段注释明确了两条重要语义(src/redis-storage.ts),使用前务必理解:
- 非原子:
clear()逐页 SCAN、逐页 DEL。若中途 Redis 报错或连接断开,promise 会在部分页已被删除后 reject——reject 意味着“可能已经删了一部分”,而不是“什么都没删”。测试用例用只读副本的READONLY错误固定了这一契约(test/redis-storage.test.ts)。 - best-effort:SCAN 期间其他客户端并发写入/删除的 key 可能漏扫或重复出现,因此
clear()成功返回并不代表在并发写入下存储一定为空。如果需要“彻底清空”(例如撤销所有会话或所有限流计数),应重复调用直到成功;clear()是幂等的,空存储调用是 no-op。
七、会话缓存场景:与数据库的一致性保证
会话数据写入 Redis 后,Better Auth 会在撤销、删除等操作时同步清理次级存储。仓库中的集成测试 packages/better-auth/src/db/secondary-storage.test.ts 验证了多组关键行为:
- 登录后会话写入次级存储:
signInWithTestUser()后,store 中出现 2 个 key(会话 token 与active-sessions-{userId}列表);撤销会话后 store 清空(L76-L116); - 数据库保留与次级存储删除的关系:当
session.storeSessionInDatabase: true且preserveSessionInDatabase: true时,会话行保留在数据库中用于审计,但会从次级存储删除,且保留行被标记为已过期,从而保证 introspection 等活性检查判定该 token 无效(L207-L299); - 删除用户时的级联清理:
deleteUser会同时删除数据库与次级存储中的会话(L377-L417); - 钩子 veto 时缓存不误删:若
databaseHooks.session.delete.before返回false否决删除,次级存储中的缓存会话得以保留(L340-L375)。
这组测试说明:Redis 次级存储不只是“读多写少的缓存”,它和主数据库之间有着严密的生命周期联动,任何删除操作都会双写清理,避免出现“数据库已删、Redis 还残留可用的会话令牌”这类安全问题。
八、验证与测试:在本地跑通 Redis Storage 测试
该包使用 Vitest 编写测试,测试文件为 packages/redis-storage/test/redis-storage.test.ts。测试通过 mock 的 ioredis 客户端注入到 redisStorage 工厂中,因此不需要真实 Redis 实例即可运行。在仓库根目录下执行:
pnpm --filter @better-auth/redis-storage test
即可运行全部用例,覆盖:GETDEL 优先与 Lua 降级、错误透传、increment 的原子自增与 TTL 语义、TTL 参数校验、SCAN 分页清空、前缀转义、空存储清空、中途失败的非原子契约、listKeys 去重等关键行为(vitest.config.ts)。
九、生产使用建议
综合源码与测试,给出以下实操要点:
- Redis 版本:优先使用 Redis 6.2+,享受原生
GETDEL的零脚本路径;低版本会自动降级为 Lua,功能不受影响; - 前缀隔离:多环境共用 Redis 实例时务必自定义
keyPrefix;前缀含特殊字符时无需担心——实现已做 glob 转义; - 限流窗口语义:
increment的 TTL 只在首次自增时设置,窗口从第一个请求开始固定计时,不会被“续命”;限流阈值判断(count <= max)发生在自增之后; - clear() 的谨慎使用:它不是事务,也不保证并发一致性;需要彻底清空时循环调用直到成功;在生产环境执行前,先确认前缀没有误配导致清空范围过大;
- 会话生命周期:撤销会话、删除用户、管理员移除用户、匿名用户删除等操作都会联动清理 Redis 中的会话数据(对应测试见 secondary-storage.test.ts),无需手动处理残留。
十、小结
@better-auth/redis-storage 是一个麻雀虽小、五脏俱全的官方次级存储实现:它用最少的配置(一个 ioredis 客户端加一个可选前缀)把 Better Auth 的会话缓存与限流计数搬进 Redis,并通过 GETDEL、Lua 脚本、SCAN 分页等手段在原子性、性能与运维便利之间做了细致权衡。理解其底层命令映射与语义边界,是在生产环境正确使用它的前提。后续若需深入了解 SecondaryStorage 接口与其他存储实现,可继续阅读 packages/core/src/db/type.ts 与 Better Auth 数据库概念的文档目录 docs/content/docs/concepts。