Remix Redis 会话存储实战:用 `createRedisSessionStorage` 搭建多实例共享的 Session 体系

原创2026-09-09 12:01:511,882 阅读
文章标签:Web框架后端前端UI组件认证鉴权异步编程

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

  1. 若传入的 Cookie 值非空,先拼出完整键 keyPrefix + id,调用 client.get 读取;
  2. 若命中,JSON.parse 反序列化后,通过 createSession(id, data) 还原会话(packages/session/src/lib/session.ts);
  3. 若未命中或 Cookie 为空,则依据 useUnknownIds 决定沿用传入 ID 还是生成新 ID;
  4. 新 ID 由 crypto.randomUUID() 生成(session.ts)。

注意:如果 Redis 中存的是非法 JSON,JSON.parse 会抛出 SyntaxError——单测专门覆盖了这一情形(redis-storage.test.ts)。

save:脏检查驱动的写入策略

Session 类内部维护了 dirty、destroyed、deleteId 等状态,save 依据这些状态决定动作(redis-storage.ts):

  1. ID 轮换:若会话调用了 regenerateId(true),session.deleteId 指向旧 ID,先 client.del 旧键,防止旧会话残留;
  2. 销毁:若 session.destroyed,删除当前键并返回 ''(空字符串,表示客户端应清除 Cookie);
  3. 脏写入:若 session.dirty,序列化 session.data 后按 ttl 配置走 setEx / set + expire / 纯 set 三种路径,返回 session.id 供写入 Cookie;
  4. 无变化:返回 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 接口。

登录后查看全文
remix