# 基础连接(本地 Redis)
REDIS_URL=redis://localhost:6379

# TLS 连接(托管服务如 Upstash)
REDIS_URL=rediss://username:password@hostname:6379

# 配置开关
ENABLE_RATE_LIMIT=true          # 启用限流功能
SESSION_TTL=300                 # 会话过期时间(秒)
STORE_SESSION_MESSAGES=false    # 是否存储请求 messages 到 Redis

const redisOptions: RedisOptions = {
  enableOfflineQueue: false,      // 快速失败,不排队
  maxRetriesPerRequest: 3,        // 单个命令最多重试 3 次
  retryStrategy(times) {
    if (times > 5) return null;   // 停止重试,触发降级
    return Math.min(times * 200, 2000); // 指数退避,最多 2s
  },
};

// TLS/SNI 配置(rediss:// 协议自动启用)
if (useTls) {
  redisOptions.tls = { host: url.hostname }; // 显式 SNI 修复
}

-- 原子操作:检查并发限制 -> 添加到 ZSET -> 设置过期时间
local count = redis.call('zcard', provider_key)
if count >= max_sessions then
  return { 0, count }
end
redis.call('zadd', provider_key, timestamp, session_id)
redis.call('expire', provider_key, ttl)
return { 1, count + 1 }

// 活跃 Sessions 缓存
getActiveSessionsCache(key?: string): SessionData[] | null
setActiveSessionsCache(data: SessionData[], key?: string): void
clearActiveSessionsCache(): void

// Session 详情缓存
getSessionDetailsCache(sessionId: string): SessionDetail | null
setSessionDetailsCache(sessionId: string, data: SessionDetail): void
clearSessionDetailsCache(sessionId: string): void

// 全局操作
clearAllSessionCache(): void
getCacheStats(): { activeSessions: Stats; sessionDetails: Stats }

// 启动定期清理任务（默认 60 秒间隔）
startCacheCleanup(intervalSeconds: number = 60): void

// 停止清理任务
stopCacheCleanup(): void

// 启动时
register() {
  startCacheCleanup(60);  // 启动缓存清理
  
  // 注册关闭钩子
  process.once("SIGTERM", shutdownHandler);
  process.once("SIGINT", shutdownHandler);
}

// 关闭时
async shutdownHandler(signal: string) {
  stopCacheCleanup();     // 停止缓存清理
  await closeRedis();     // 关闭 Redis 连接
}

// 注册任务
const abortController = AsyncTaskManager.register(
  taskId,
  asyncPromise,
  "stream-processing"
);

// 取消任务
AsyncTaskManager.cancel(taskId);

// 获取活跃任务数
AsyncTaskManager.getActiveTaskCount();

-- 原子操作流程:
-- 1. 清理 5 分钟前的过期 session
-- 2. 检查 session 是否已追踪(避免重复计数)
-- 3. 检查并发数是否超限
-- 4. 追踪新 session 并设置兜底 TTL

-- 原子操作流程:
-- 1. 清理窗口外的过期记录
-- 2. 添加当前消费(member = "timestamp:cost")
-- 3. 计算窗口内总消费
-- 4. 设置 6 小时兜底 TTL

// enableOfflineQueue: false - Redis 断线时立即失败,不排队
// maxRetriesPerRequest: 3 - 单命令最多重试 3 次
// retryStrategy - 指数退避,5 次后停止重试

if (times > 5) {
  logger.error("Redis retry exhausted, fail-open");
  return null; // 触发降级
}

// src/lib/session-tracker.ts
const pipeline = redis.pipeline();
pipeline.zrem("global:active_sessions", sessionId);
pipeline.zrem(`key:${keyId}:active_sessions`, sessionId);
pipeline.zrem(`provider:${providerId}:active_sessions`, sessionId);
pipeline.del(`session:${sessionId}:concurrent_count`);
await pipeline.exec();

// 日志示例(降级事件)
logger.warn({
  action: "redis_unavailable_fail_open",
  context: "rate_limit",
  error: error.message,
});

// 指标记录(自行接入 Prometheus)
redisCommandDuration.observe(duration);
redisFailOpenCounter.inc({ context: "session" });

# docker-compose.yml
redis:
  image: redis:7-alpine
  command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy allkeys-lru
  volumes:
    - redis-data:/data

REDIS_URL=rediss://default:your-token@region.upstash.io:6379

if (useTls) {
  redisOptions.tls = { host: url.hostname }; // 修复 SNI
}