Remix Redis 会话存储实战:用 `createRedisSessionStorage` 搭建多实例共享的 Session 体系
Remix Redis 会话存储实战:用 createRedisSessionStorage 搭建多实例共享的 Session 体系
本指南围绕 Remix 官方仓库中的 @remix-run/session-storage-redis 包展开,系统讲解如何借助 Redis 在多个应用服务器实例之间共享 Session 状态。读完本文,你将掌握 createRedisSessionStorage 的安装方式、完整配置项(keyPrefix、ttl、useUnknownIds)的语义与默认值、底层 read/save 的读写链路,以及如何通过单元测试与集成测试验证存储行为。
为什么需要 Redis 会话存储
Web 应用中的 Session 用于"在多次请求之间为特定用户持久化数据"。当应用以多实例(横向扩容)方式部署时,每个实例的进程内内存各不相同,用户请求被负载均衡分发到不同实例后,Session 数据必须存放在一个所有实例都能访问的共享位置——Redis 正是最常用的选择之一。
本仓库中,packages/session 提供了与运行时无关的 Session 抽象(Session 类与 SessionStorage 接口),而 packages/session-storage-redis 是它的 Redis 后端实现,核心导出 createRedisSessionStorage。它的设计目标非常聚焦:当应用服务器需要通过 Redis 共享会话状态时,使用这个包。相关源码位于 packages/session-storage-redis/src/lib/redis-storage.ts。
安装与依赖
仓库内该包名为 @remix-run/session-storage-redis(见 packages/session-storage-redis/package.json)。在 Remix 应用中安装:
npm i remix
从依赖声明看,包的运行时依赖只有 @remix-run/session(workspace 内部包),而 redis 客户端(^5.10.0)被声明为可选的 peerDependency——这意味着 redis 客户端库需要由使用者自行安装:
npm i redis
源码中并没有硬编码绑定某个 Redis 客户端实现,而是定义了一个最小客户端契约(详见下文"最小客户端契约"一节),因此只要满足该契约,任何 Redis 客户端(如 node-redis、ioredis 等)都可以传入。
快速上手
文档给出的最小使用示例非常简洁,核心分为三步:创建并连接 Redis 客户端 → 调用 createRedisSessionStorage 创建存储 → 在请求处理中使用:
import { createClient } from 'redis'
import { createRedisSessionStorage } from 'remix/session-storage/redis'
let redis = createClient({ url: process.env.REDIS_URL })
await redis.connect()
let sessionStorage = createRedisSessionStorage(redis, {
keyPrefix: 'session:',
ttl: 60 * 60 * 24,
})
其中:
REDIS_URL通过环境变量注入,例如redis://localhost:6379;keyPrefix为所有 Session 键加上统一前缀,避免与 Redis 中其他业务数据冲突;ttl单位为秒,示例中60 * 60 * 24表示会话数据 24 小时后自动过期。
需要说明的是,包源码自身的导出入口是 packages/session-storage-redis/src/index.ts,它重新导出了 createRedisSessionStorage 以及两个类型:RedisSessionStorageClient、RedisSessionStorageOptions。在仓库的测试与内部使用中,直接以 ./redis-storage.ts 的方式引用实现模块。
Options 配置项详解
createRedisSessionStorage(client, options) 接受两个参数:第一个是满足 RedisSessionStorageClient 契约的客户端,第二个是可选的 RedisSessionStorageOptions。三个配置项的定义与默认值(见 redis-storage.ts):
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
keyPrefix |
string |
'session:' |
Session 键的前缀,最终 Redis 中的键为 keyPrefix + sessionId |
ttl |
number(秒) |
undefined(不设置过期) |
会话存活时间;配置后键自动过期,前提是客户端实现了 setEx 或 expire |
useUnknownIds |
boolean |
false |
是否复用客户端传来的、但存储中不存在的 Session ID |
keyPrefix:键的命名空间隔离
keyForSession(id) 的实现是简单的字符串拼接 keyPrefix + id(redis-storage.ts)。单元测试验证了这一点:使用 keyPrefix: 'my-app:' 保存后,Redis 侧(测试中的 Map 模拟)应存在 'my-app:' + session.id 这个键(见 redis-storage.test.ts)。在多应用共用同一个 Redis 实例的场景下,用应用名做前缀(如 my-app:、admin:)是最直接的隔离手段。
ttl:秒级过期策略
- 单位为秒,且内部会做归一化:
Math.max(1, Math.floor(value))(redis-storage.ts),即小数秒向下取整、最小为 1 秒。测试中用ttl: 60.9验证了最终写入 Redis 的过期时间为60秒(见 redis-storage.test.ts)。 - 若配置了
ttl但客户端既没有setEx也没有expire,构造函数会立即抛出错误:Redis client must implement setEx() or expire() when ttl is configured(redis-storage.ts),这是对契约的运行时强制校验。 - 写入时优先使用原子的
setEx(key, ttl, value);若客户端只实现了expire,则退化为set(key, value)之后再调用expire(key, ttl)(redis-storage.ts)。从源码结构看,优先setEx是为了避免"写入后、设过期前"进程崩溃导致的无过期残留。
useUnknownIds:是否认领陌生的 Session ID
当客户端传来一个 Session ID,但在 Redis 中查不到对应数据时:
useUnknownIds: false(默认):不信任该 ID,创建一个全新 ID 的会话。这可以防止攻击者猜测/伪造 ID 影响会话行为。useUnknownIds: true:认领该 ID,以它作为新会话的 ID 继续使用,适用于"客户端 ID 由外部系统签发、需要保持同步"等特殊场景。
对应实现见 redis-storage.ts,单测与集成测试中均有对称的两个用例验证(redis-storage.test.ts)。
底层实现原理:read 与 save 的完整链路
createRedisSessionStorage 返回的对象只暴露两个异步方法 read(cookie) 与 save(session),它们与 packages/session/src/lib/session-storage.ts 中定义的 SessionStorage 接口完全对齐。整个实现只有约 140 行(redis-storage.ts),逻辑非常清晰。
最小客户端契约
存储层并不依赖某个具体 Redis 客户端,只要求传入的对象具备以下方法(redis-storage.ts):
| 方法 | 必选 | 签名 | 用途 |
|---|---|---|---|
get |
是 | (key) => Promise<string | null> | string | null |
读取序列化后的会话值 |
set |
是 | (key, value) => Promise<unknown> | unknown |
写入会话值 |
del |
是 | (key) => Promise<unknown> | unknown |
删除会话值 |
setEx |
否 | (key, ttlSeconds, value) => Promise<unknown> |
带过期写入(优先) |
expire |
否 | (key, ttlSeconds) => Promise<unknown> |
为已有键续期/设置过期 |
redis(node-redis v5)的 createClient 返回对象天然满足该契约,因此可以直接传入。
read:从 Cookie 值还原 Session
- 若传入的 Cookie 值非空,先拼出完整键
keyPrefix + id,调用client.get读取; - 若命中,
JSON.parse反序列化后,通过createSession(id, data)还原会话(packages/session/src/lib/session.ts); - 若未命中或 Cookie 为空,则依据
useUnknownIds决定沿用传入 ID 还是生成新 ID; - 新 ID 由
crypto.randomUUID()生成(session.ts)。
注意:如果 Redis 中存的是非法 JSON,JSON.parse 会抛出 SyntaxError——单测专门覆盖了这一情形(redis-storage.test.ts)。
save:脏检查驱动的写入策略
Session 类内部维护了 dirty、destroyed、deleteId 等状态,save 依据这些状态决定动作(redis-storage.ts):
- ID 轮换:若会话调用了
regenerateId(true),session.deleteId指向旧 ID,先client.del旧键,防止旧会话残留; - 销毁:若
session.destroyed,删除当前键并返回''(空字符串,表示客户端应清除 Cookie); - 脏写入:若
session.dirty,序列化session.data后按ttl配置走setEx/set+expire/ 纯set三种路径,返回session.id供写入 Cookie; - 无变化:返回
null,表示不需要下发 Set-Cookie。
Session 生命周期与 Redis 的配合
packages/session 的 Session 类提供了 set、get、unset、flash、destroy、regenerateId 等方法(packages/session/src/lib/session.ts),这些方法本身不接触存储,只是标记 dirty 等状态;真正的数据落库全部发生在 save 阶段。这种"内存改状态、save 落库"的分工,使得存储后端(内存、文件、Cookie、Redis)可以自由替换。
一个值得注意的细节:默认情况下(regenerateId() 不带参数),旧的 Session 数据会继续留在 Redis 中,直到 TTL 过期;只有传入 true(regenerateId(true))才会在 save 时删除旧数据。两个场景在单测与集成测试中都有覆盖(redis-storage.test.ts)。这在登录/权限变更场景中尤为重要:既可以利用"轮换 ID 防会话固定攻击",又可以按需清理旧数据。
测试与验证:如何确认存储行为
仓库为该包提供了两层测试,是理解其行为的绝佳参考。
单元测试(无外部依赖)
redis-storage.test.ts 使用一个基于 Map 的模拟客户端(createMapRedisClient)验证纯逻辑,覆盖了:未知 ID 处理、跨请求持久化、销毁清理、未修改不写 Cookie、flash 数据只在下一个请求可见、ID 轮换时的旧数据保留/删除、keyPrefix 键拼接、ttl 归一化(60.9 → 60)、setEx/expire 双路径、缺 setEx/expire 时抛错、非法 JSON 抛 SyntaxError。这组用例几乎穷尽了 createRedisSessionStorage 的所有分支,是阅读实现时的最佳索引。
集成测试(真实 Redis)
redis-storage.integration.test.ts 使用真实的 redis 客户端连接 Redis,测试套件通过两个环境变量控制开关:
SESSION_REDIS_URL:Redis 连接地址(如redis://localhost:6379);SESSION_REDIS_INTEGRATION=1:显式开启集成测试(默认跳过)。
SESSION_REDIS_URL=redis://localhost:6379 SESSION_REDIS_INTEGRATION=1 pnpm --filter @remix-run/session-storage-redis test
每个用例执行前会 client.flushDb() 清空 Redis,其中 sets key expiration when ttl is configured 用例会直接通过 client.ttl('session:' + id) 断言键确实带上了过期时间(redis-storage.integration.test.ts)。
完整实战示例:在请求管线中使用
把以上知识串起来,一个完整的"读改写"会话处理流程如下:
import { createClient } from 'redis'
import { createRedisSessionStorage } from 'remix/session-storage/redis'
let redis = createClient({ url: process.env.REDIS_URL })
await redis.connect()
// 生产环境建议:keyPrefix 用应用名隔离,ttl 按业务会话时长设定
let sessionStorage = createRedisSessionStorage(redis, {
keyPrefix: 'shop:session:',
ttl: 60 * 60 * 24 * 7, // 7 天
})
export async function handleRequest(cookieHeader: string | null) {
// 1. 从 Cookie 头取出 session 值(实际项目中通常配合 cookie 解析中间件)
let cookie = cookieHeader?.split('=')[1] ?? null
// 2. 读取会话
let session = await sessionStorage.read(cookie)
// 3. 业务操作:读写数据、flash 提示、登录后轮换 ID
let views = Number(session.get('views') ?? 0) + 1
session.set('views', views)
// 登录成功后建议调用 session.regenerateId(true) 防止会话固定攻击
// 4. 保存会话,得到要写入 Set-Cookie 的值
let setCookie = await sessionStorage.save(session)
return { views, setCookie }
}
要点回顾:
- 读:
read(cookie)若 Cookie 为空,返回全新会话,不会写 Redis; - 改:
session.set(...)只是标记 dirty,真正的 Redis 写操作发生在save; - 存:
save返回session.id时应写入 Set-Cookie;返回null时不设置;返回''时清除 Cookie(会话已销毁); - 过期:配置
ttl后,Redis 键自动过期,无需额外的清理任务; - 多实例:由于会话数据存于 Redis,任意实例都能读到同一份会话,扩容时无需开启 sticky session。
如需继续深入,可对照阅读以下源码与测试:核心实现、单元测试、集成测试、Session 抽象、SessionStorage 接口。