tokens-reef/deploy/performance-testing/config/redis-optimization.md

Sub2API Redis 连接池优化配置

📊 当前配置分析

根据 backend/internal/repository/redis.go 分析，当前 Redis 配置支持：

opts := &redis.Options{
    Addr:         cfg.Redis.Address(),
    Password:     cfg.Redis.Password,
    DB:           cfg.Redis.DB,
    DialTimeout:  time.Duration(cfg.Redis.DialTimeoutSeconds) * time.Second,
    ReadTimeout:  time.Duration(cfg.Redis.ReadTimeoutSeconds) * time.Second,
    WriteTimeout: time.Duration(cfg.Redis.WriteTimeoutSeconds) * time.Second,
    PoolSize:     cfg.Redis.PoolSize,
    MinIdleConns: cfg.Redis.MinIdleConns,
}

🎯 推荐配置

小规模部署（< 1000 QPS）

# config.yaml
redis:
  dial_timeout_seconds: 5
  read_timeout_seconds: 3
  write_timeout_seconds: 3
  pool_size: 50
  min_idle_conns: 10

中等规模（1000-5000 QPS）

# config.yaml
redis:
  dial_timeout_seconds: 3
  read_timeout_seconds: 2
  write_timeout_seconds: 2
  pool_size: 100
  min_idle_conns: 20

大规模部署（5000-20000 QPS）

# config.yaml
redis:
  dial_timeout_seconds: 2
  read_timeout_seconds: 1
  write_timeout_seconds: 1
  pool_size: 200
  min_idle_conns: 50

超大规模（> 20000 QPS）

# config.yaml
redis:
  dial_timeout_seconds: 1
  read_timeout_seconds: 1
  write_timeout_seconds: 1
  pool_size: 500
  min_idle_conns: 100

🔧 配置参数详解

PoolSize

场景	推荐值	说明
小规模	50-100	单实例足够
中等	100-200	覆盖正常并发
大规模	200-500	需要配合应用水平扩展

计算公式：

PoolSize = 预期最大并发请求数 × 1.2 (缓冲)

MinIdleConns

场景	推荐值	说明
小规模	10-20	减少冷启动延迟
中等	20-50	保持热连接
大规模	50-100	高可用预热

原则：MinIdleConns = PoolSize * 0.2 ~ 0.3

超时配置

参数	推荐值	说明
DialTimeout	2-5秒	建连超时，过长会阻塞
ReadTimeout	1-3秒	读取超时，应小于请求超时
WriteTimeout	1-3秒	写入超时，应小于请求超时

重要：超时配置应小于上游 API 超时，避免级联超时

📈 性能调优步骤

1. 基准测试

# 使用 redis-benchmark
redis-benchmark -h localhost -p 6379 -n 100000 -c 50 -t get,set,hget,hset -d 100

# 测试 Pipeline 性能
redis-benchmark -h localhost -p 6379 -n 10000 -P 10 -t get,set

2. 监控关键指标

# Redis 连接使用率
sub2api_redis_connections{state="total"} / <pool_size> * 100

# Redis 操作延迟
rate(sub2api_http_request_duration_seconds{path="/metrics"}[5m])

# 缓存命中率
sub2api_cache_operations_total{result="hit"} / 
(sub2api_cache_operations_total{result="hit"} + sub2api_cache_operations_total{result="miss"})

3. 常见问题排查

问题：高 Redis 延迟

• 检查网络延迟：redis-cli --latency-history
• 检查慢查询：redis-cli SLOWLOG GET 10
• 优化 KEY 设计，减少大 Value

问题：连接池耗尽

• 增加 PoolSize
• 检查是否存在连接泄漏
• 考虑使用 Redis Cluster

问题：缓存命中率低

• 分析缓存 Key 访问模式
• 调整 TTL 配置
• 检查缓存失效策略

🚀 Redis 服务端优化

单机 Redis 配置

# redis.conf

# 网络优化
tcp-backlog 511
timeout 300
tcp-keepalive 300

# 内存优化
maxmemory 2gb
maxmemory-policy allkeys-lru

# 持久化优化（根据业务选择）
rdbcompression yes
rdbchecksum yes
save 900 1
save 300 10
save 60 10000

# AOF 优化
appendonly yes
appendfsync everysec
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb

# 客户端优化
client-output-buffer-limit normal 256mb 64mb 60
client-output-buffer-limit replica 256mb 64mb 60
client-output-buffer-limit pubsub 32mb 8mb 60

Redis Cluster 配置（大规模）

# redis-cluster.yaml
cluster-enabled: yes
cluster-config-file: nodes.conf
cluster-node-timeout: 15000
cluster-replica-validity-factor: 10
cluster-migration-barrier: 1
cluster-require-full-coverage: yes

📊 Sub2API 缓存策略分析

当前缓存层次

1. L1 缓存: go-cache (内存)

   • userGroupRateCache: 30秒 TTL
   • modelsListCache: 15秒 TTL

2. L2 缓存: Redis

   • API Key 认证缓存
   • 用户组速率限制缓存
   • 调度器快照缓存

缓存 Key 设计建议

# 推荐格式
{sub2api}:{module}:{entity}:{id}:{field}
{sub2api}:auth:apikey:{key_hash}
{sub2api}:ratelimit:user:{user_id}:{window}
{sub2api}:gateway:scheduler:{account_id}

缓存 TTL 建议

缓存类型	推荐 TTL	说明
API Key 认证	5-15分钟	平衡一致性和性能
用户组速率	30秒-1分钟	需要实时性
调度器快照	1-5分钟	允许一定延迟
模型列表	15-30秒	变化较频繁
计费数据	5-15分钟	允许批处理延迟

⚠️ 注意事项

1. 不要设置过大的 PoolSize：每个连接占用约 10KB 内存
2. 监控连接泄漏：确保连接被正确释放
3. 考虑读写分离：大量读操作可以分摊到从节点
4. 使用 Pipeline：批量操作减少 RTT
5. 避免大 Value：单 Key 建议 < 1MB

📊 性能基线参考

Redis 配置	1K QPS	5K QPS	10K QPS	20K QPS
50/10	5ms	15ms	40ms	100ms
100/20	3ms	8ms	20ms	50ms
200/50	2ms	5ms	12ms	30ms
500/100	1ms	3ms	8ms	20ms