LogoLaunchSaaS

缓存配置

为 Better Auth 和应用程序缓存配置缓存提供商

缓存配置

LaunchSaaS 支持多个缓存提供商,用于 Better Auth 二级存储和通用应用程序缓存。缓存通过减少对频繁访问数据(如会话和 API 密钥)的数据库查询来提高性能。

更新时间: 2026-01-13

概述

缓存系统提供:

  • Better Auth 集成 - 自动会话缓存
  • 多个提供商 - Redis、Upstash Redis、Cloudflare KV
  • 工厂模式 - 轻松切换提供商
  • 类型安全 - 完整的 TypeScript 支持
  • 优雅降级 - 如果缓存不可用,则回退到数据库

配置

1. 启用缓存提供商

编辑 src/configuration/features.ts:

const local: Features = {
  // ... 其他功能
  cache: {
    provider: "redis", // "redis" | "cloudflare-kv" | "disabled"
  },
};

2. 环境变量

标准 Redis

用于本地 Redis 或托管 Redis 服务(AWS ElastiCache、Azure Cache for Redis 等):

# 标准 Redis 连接
REDIS_URL=redis://localhost:6379

# 带身份验证
REDIS_URL=redis://username:password@host:6379

# 带 TLS
REDIS_URL=rediss://username:password@host:6379

Upstash Redis (REST API)

用于使用 HTTP REST API 的 Upstash Redis:

# Upstash Redis REST 端点
REDIS_REST_URL=https://your-endpoint.upstash.io
REDIS_REST_TOKEN=your-rest-token

当 REDIS_URL 和 REDIS_REST_URL 同时存在时,REST API 优先,以获得更好的边缘兼容性。

Cloudflare KV

用于 Cloudflare KV 存储:

CLOUDFLARE_ACCOUNT_ID=your-account-id
CLOUDFLARE_KV_NAMESPACE_ID=your-namespace-id
CLOUDFLARE_API_TOKEN=your-api-token

提供商比较

功能RedisUpstash RedisCloudflare KV
连接方式TCP(持久连接)HTTP REST APIHTTP REST API
延迟亚毫秒级~50-100ms~50-100ms
一致性强一致性强一致性最终一致性(60秒)
边缘支持否是是(原生)
Serverless有限完美完美
设置自托管/托管托管托管
成本服务器成本按请求付费按请求付费
最适合传统服务器Serverless/边缘Cloudflare 部署

使用场景

Better Auth 二级存储

启用缓存后,Better Auth 自动存储:

  • 会话数据 - 无需数据库查询即可快速查找会话
  • API 密钥 - 快速 API 密钥验证
  • 速率限制 - 高效的速率限制跟踪

无需额外代码 - Better Auth 自动处理。

自定义缓存

在代码中直接使用缓存提供商:

import { getCacheProvider } from "@/lib/cache";

const cache = getCacheProvider();

// 设置带 TTL(秒)
await cache.set("user-settings:123", JSON.stringify(settings), 3600);

// 获取值
const cached = await cache.get("user-settings:123");
const settings = cached ? JSON.parse(cached) : null;

// 删除
await cache.delete("user-settings:123");

提供商设置指南

Redis 设置

本地开发

# 使用 Docker
docker run -d -p 6379:6379 redis:7-alpine

# 配置
REDIS_URL=redis://localhost:6379

AWS ElastiCache

# 从 AWS 控制台获取端点
REDIS_URL=rediss://your-cluster.cache.amazonaws.com:6379

Azure Cache for Redis

# 从 Azure 门户获取连接字符串
REDIS_URL=rediss://your-cache.redis.cache.windows.net:6380

Upstash Redis 设置

  1. 创建数据库,访问 console.upstash.com
  2. 复制 REST 凭据,从数据库详情获取
  3. 配置环境:
UPSTASH_REDIS_REST_URL=https://your-endpoint.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-rest-token
  1. 在 features.ts 中启用:
cache: {
  provider: "upstash";
}

Upstash Redis 非常适合 serverless 部署(Vercel、Netlify、Cloudflare Workers),因为它使用 HTTP 而不是持久 TCP 连接。

Cloudflare KV 设置

  1. 创建 KV 命名空间,在 Cloudflare 仪表板中
  2. 创建 API 令牌,具有 KV 权限
  3. 配置环境:
CLOUDFLARE_ACCOUNT_ID=abc123
CLOUDFLARE_KV_NAMESPACE_ID=xyz789
CLOUDFLARE_API_TOKEN=your-token

架构

提供商接口

所有缓存提供商实现 CacheProvider 接口:

interface CacheProvider {
  get(key: string): Promise<string | null>;
  set(key: string, value: string, ttl?: number): Promise<void>;
  delete(key: string): Promise<void>;
  isConnected(): Promise<boolean>;
  disconnect(): Promise<void>;
}

工厂模式

缓存工厂管理提供商初始化:

// 在 src/instrumentation.ts 中自动初始化
await CacheProviderFactory.initializeProvider();

// 获取单例实例
const cache = CacheProviderFactory.getProvider();

Better Auth 集成

Better Auth 使用缓存作为二级存储(在 src/lib/auth/auth.ts 中配置):

export const auth = betterAuth({
  // ... 其他配置
  secondaryStorage: getSecondaryStorage(),
});

性能优势

启用缓存时

会话查找: ~5-10ms (缓存命中)
API 密钥验证: ~5-10ms (缓存命中)
速率限制检查: ~5-10ms (缓存命中)

未启用缓存时

会话查找: ~50-100ms (数据库查询)
API 密钥验证: ~50-100ms (数据库查询)
速率限制检查: ~50-100ms (数据库查询)

结果: 身份验证操作快 5-10 倍

故障排除

缓存无法连接

检查 instrumentation 日志:

# 启动开发服务器
pnpm dev

# 查找缓存初始化日志
# ✓ Cache provider redis initialized successfully
# ✗ Failed to initialize cache provider: [error]

Upstash 连接问题

验证 REST 凭据:

// 测试连接
const response = await fetch(`${process.env.REDIS_REST_URL}/get/test-key`, {
  headers: {
    Authorization: `Bearer ${process.env.REDIS_REST_TOKEN}`,
  },
});

Cloudflare KV 问题

检查 API 令牌权限:

  • Worker Scripts: Read
  • Workers KV Storage: Read & Write

绕过缓存

临时禁用缓存:

// 在 src/configuration/features.ts 中
cache: {
  provider: "disabled",
}

应用程序将正常工作,仅使用数据库。

最佳实践

1. TTL 策略

根据数据易变性设置适当的 TTL:

// 频繁变化数据的短 TTL
await cache.set("online-users", data, 60); // 1 分钟

// 用户会话的中等 TTL
await cache.set("session:xyz", session, 3600); // 1 小时

// 很少变化数据的长 TTL
await cache.set("app-config", config, 86400); // 24 小时

2. 缓存键

使用一致的分层命名:

// 好的
"user:123:settings";
"session:abc-def-123";
"rate-limit:api:192.168.1.1";

// 避免
"userSettings123";
"sess_abc";
"rl_192.168.1.1";

3. 错误处理

始终优雅地处理缓存故障:

try {
  const cached = await cache.get(key);
  if (cached) return JSON.parse(cached);
} catch (error) {
  console.error("Cache error:", error);
  // 回退到数据库
}

4. 缓存失效

数据更改时使缓存失效:

// 更新用户后
await updateUser(userId, data);
await cache.delete(`user:${userId}:settings`);

生产检查清单

  • 根据基础设施选择适当的缓存提供商
  • 设置生产缓存实例(Redis/Upstash/Cloudflare KV)
  • 在生产环境中配置环境变量
  • 为缓存服务启用监控/告警
  • 测试缓存故障转移(禁用缓存,验证应用仍能工作)
  • 为团队记录缓存键模式
  • 设置缓存指标仪表板(可选)

迁移指南

从无缓存迁移到 Redis

  1. 选择提供商,根据基础设施:
    • 传统服务器 → redis
    • Serverless/边缘 → upstash
    • Cloudflare → cloudflare-kv
  2. 设置缓存实例(Redis/Upstash/Cloudflare KV)
  3. 配置环境变量
  4. 在功能中启用: 
    cache: {
  provider: "redis";
} // 或 "upstash" 或 "cloudflare-kv"
  5. 重启应用程序
  6. 验证日志显示缓存初始化
  7. 监控会话性能改进

切换提供商

无需数据迁移 - 缓存是临时的:

  1. 更新 features.ts,使用新提供商
  2. 设置新环境变量
  3. 删除旧环境变量
  4. 重启应用程序

旧缓存数据自动丢弃。

参考资料

下一步

身份验证

配置 Better Auth

环境配置

设置环境变量

部署

部署到生产环境

On this page

缓存配置概述配置1. 启用缓存提供商2. 环境变量标准 RedisUpstash Redis (REST API)Cloudflare KV提供商比较使用场景Better Auth 二级存储自定义缓存提供商设置指南Redis 设置本地开发AWS ElastiCacheAzure Cache for RedisUpstash Redis 设置Cloudflare KV 设置架构提供商接口工厂模式Better Auth 集成性能优势启用缓存时未启用缓存时故障排除缓存无法连接Upstash 连接问题Cloudflare KV 问题绕过缓存最佳实践1. TTL 策略2. 缓存键3. 错误处理4. 缓存失效生产检查清单迁移指南从无缓存迁移到 Redis切换提供商参考资料下一步