# 缓存配置

<cite>
**Referenced Files in This Document**   
- [docker-compose.yml](file://docker-compose.yml)
- [config.yaml](file://manifest/config/config.yaml)
- [cache.go](file://utility/cache/cache.go)
- [redis.go](file://utility/limiter/redis.go)
- [cache.go](file://internal/consts/cache.go)
</cite>

## 目录
1. [Docker Compose Redis服务配置](#docker-compose-redis服务配置)
2. [Redis在kami_backend中的使用场景](#redis在kami_backend中的使用场景)
3. [Redis配置优化建议](#redis配置优化建议)
4. [Redis集群模式部署方案](#redis集群模式部署方案)
5. [监控和维护最佳实践](#监控和维护最佳实践)

## Docker Compose Redis服务配置

在当前项目中，Redis服务并未直接定义在`docker-compose.yml`文件中。项目主要通过外部配置文件`manifest/config/config.yaml`来配置Redis连接参数。Redis作为外部依赖服务运行，kami_backend应用通过配置文件中的参数连接到Redis实例。

Redis配置包含以下关键参数：
- **地址**: `127.0.0.1:6379` - Redis服务器的IP地址和端口
- **数据库**: `db: 4` - 使用Redis的第4个数据库实例
- **连接超时**: `dialTimeout: "30s"` - TCP连接超时时间为30秒
- **读取超时**: `readTimeout: "30s"` - 读操作超时时间为30秒
- **写入超时**: `writeTimeout: "30s"` - 写操作超时时间为30秒
- **空闲超时**: `idleTimeout: "60s"` - 连接最大空闲时间为60秒
- **最大连接生命周期**: `maxConnLifetime: "90s"` - 连接最长存活时间为90秒
- **等待超时**: `waitTimeout: "60s"` - 等待连接池连接的超时时间为60秒
- **最大活跃连接数**: `maxActive: 100` - 连接池最大活跃连接数为100

**Section sources**
- [config.yaml](file://manifest/config/config.yaml#L27-L57)

## Redis在kami_backend中的使用场景

Redis在kami_backend中扮演着关键角色，主要用于多种缓存和限流场景。通过分析代码实现，Redis的主要使用场景包括：

### 会话存储
Redis被用作分布式会话存储，通过`token`配置中的`cacheModel: "redis"`设置，系统将用户会话信息存储在Redis中，支持多实例间的会话共享。这种设计确保了在负载均衡环境下用户会话的一致性。

### 限流器
系统实现了基于Redis的限流机制，通过`utility/limiter/redis.go`中的`SimpleKeyLimiter`结构体实现。该限流器利用Redis的键值存储特性，通过计算特定前缀的键数量来实现请求频率控制。当请求次数超过预设阈值时，系统将拒绝后续请求，有效防止服务过载。

### 缓存数据
Redis被广泛用于各种业务数据的缓存，包括：
- **追踪信息缓存**: 通过`PrefixTrace`前缀存储分布式追踪的Span上下文，实现跨服务调用的追踪能力恢复
- **账户状态缓存**: 缓存苹果账户、京东账户等第三方账户的临时状态信息
- **查询结果缓存**: 缓存频繁查询的账户余额、订单状态等信息，减少对后端服务的直接调用
- **字典数据缓存**: 缓存系统配置、参数字典等静态数据，提高访问效率

**Section sources**
- [cache.go](file://utility/cache/cache.go#L0-L126)
- [redis.go](file://utility/limiter/redis.go#L0-L44)
- [cache.go](file://internal/consts/cache.go#L0-L14)

## Redis配置优化建议

基于当前系统的使用场景和性能需求，提出以下Redis配置优化建议：

### 最大内存设置
建议明确设置Redis的最大内存限制，防止内存无限增长导致系统不稳定。根据当前业务规模，建议设置：
```yaml
maxmemory: 2gb
```
此设置可确保Redis在内存使用达到2GB时触发淘汰策略，避免影响宿主机其他服务。

### 淘汰策略
针对不同的数据类型，建议采用合适的淘汰策略：
- **会话数据**: 使用`allkeys-lru`策略，优先淘汰最近最少使用的会话
- **临时状态数据**: 使用`volatile-ttl`策略，优先淘汰剩余生存时间最短的数据
- **缓存数据**: 使用`allkeys-random`策略，随机淘汰数据

推荐配置：
```yaml
maxmemory-policy allkeys-lru
```

### 持久化模式选择
根据业务对数据持久化的需求，建议采用以下配置：

#### 开发环境
使用RDB快照模式，每15分钟保存一次快照，平衡性能和数据安全：
```yaml
save 900 1
save 300 10
save 60 10000
```

#### 生产环境
建议同时启用RDB和AOF两种持久化方式：
- RDB提供定期快照，用于快速恢复
- AOF提供每秒同步，确保数据丢失最小化

AOF配置建议：
```yaml
appendonly yes
appendfsync everysec
no-appendfsync-on-rewrite yes
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb
```

### 连接池优化
当前配置中`maxActive: 100`可能过高，建议根据实际并发量调整：
- **低并发场景**: 设置为50-80
- **高并发场景**: 可保持100或适当增加
- 同时设置`maxIdle: 20`以保持一定数量的空闲连接

**Section sources**
- [config.yaml](file://manifest/config/config.yaml#L27-L57)

## Redis集群模式部署方案

虽然当前配置使用单实例Redis，但为支持高可用和水平扩展，建议采用Redis集群模式部署：

### 集群架构
```mermaid
graph TB
subgraph "Redis Cluster"
Master1[Redis Master 1]
Slave1[Redis Slave 1]
Master2[Redis Master 2]
Slave2[Redis Slave 2]
Master3[Redis Master 3]
Slave3[Redis Slave 3]
end
kami_backend --> Master1
kami_backend --> Master2
kami_backend --> Master3
Master1 --> Slave1
Master2 --> Slave2
Master3 --> Slave3
style Master1 fill:#f9f,stroke:#333
style Master2 fill:#f9f,stroke:#333
style Master3 fill:#f9f,stroke:#333
```

**Diagram sources**
- [config.yaml](file://manifest/config/config.yaml#L27-L57)

### Docker Compose配置
```yaml
version: '3.8'
services:
  redis-node-1:
    image: redis:7-alpine
    command: redis-server --port 6379 --cluster-enabled yes --cluster-config-file nodes.conf --cluster-node-timeout 5000 --appendonly yes
    volumes:
      - redis-data-1:/data
    ports:
      - "6379:6379"
      - "16379:16379"
    networks:
      - redis-network
      
  redis-node-2:
    image: redis:7-alpine
    command: redis-server --port 6380 --cluster-enabled yes --cluster-config-file nodes.conf --cluster-node-timeout 5000 --appendonly yes
    volumes:
      - redis-data-2:/data
    ports:
      - "6380:6380"
      - "16380:16380"
    networks:
      - redis-network
      
  redis-node-3:
    image: redis:7-alpine
    command: redis-server --port 6381 --cluster-enabled yes --cluster-config-file nodes.conf --cluster-node-timeout 5000 --appendonly yes
    volumes:
      - redis-data-3:/data
    ports:
      - "6381:6381"
      - "16381:16381"
    networks:
      - redis-network
      
  redis-trib:
    image: redis:7-alpine
    depends_on:
      - redis-node-1
      - redis-node-2
      - redis-node-3
    command: >
      sh -c "
      sleep 10 &&
      redis-cli --cluster create 
      redis-node-1:6379 redis-node-2:6380 redis-node-3:6381 
      --cluster-replicas 1
      "
    networks:
      - redis-network

volumes:
  redis-data-1:
  redis-data-2:
  redis-data-3:

networks:
  redis-network:
    driver: bridge
```

### 配置说明
1. **三主三从架构**: 3个主节点负责数据读写，3个从节点提供数据冗余和故障转移
2. **数据分片**: 使用Redis Cluster的哈希槽机制，将16384个哈希槽均匀分配到3个主节点
3. **高可用**: 每个主节点配置一个从节点，当主节点故障时自动选举从节点为主
4. **持久化**: 启用AOF持久化，每秒同步一次，确保数据安全
5. **网络配置**: 暴露数据端口和集群总线端口，支持节点间通信

**Section sources**
- [config.yaml](file://manifest/config/config.yaml#L27-L57)

## 监控和维护最佳实践

### 监控指标
建立全面的Redis监控体系，重点关注以下指标：

```mermaid
flowchart TD
A[Redis监控指标] --> B[内存使用]
A --> C[连接数]
A --> D[命中率]
A --> E[延迟]
A --> F[持久化]
B --> B1["used_memory: 实际使用内存"]
B --> B2["used_memory_rss: 操作系统分配内存"]
B --> B3["mem_fragmentation_ratio: 内存碎片率"]
C --> C1["connected_clients: 客户端连接数"]
C --> C2["blocked_clients: 阻塞客户端数"]
D --> D1["keyspace_hits: 命中次数"]
D --> D2["keyspace_misses: 未命中次数"]
D --> D3["hit_rate: 命中率"]
E --> E1["latency: 命令执行延迟"]
E --> E2["rdb_last_bgsave_time_sec: RDB保存耗时"]
F --> F1["aof_enabled: AOF是否启用"]
F --> F2["aof_rewrite_in_progress: AOF重写状态"]
```

**Diagram sources**
- [config.yaml](file://manifest/config/config.yaml#L27-L57)

### 维护策略
1. **定期备份**: 每日执行RDB快照备份，并将备份文件存储到安全位置
2. **内存优化**: 定期分析大键，使用`SCAN`命令替代`KEYS`，避免阻塞
3. **连接管理**: 设置合理的`timeout`参数，及时清理空闲连接
4. **版本升级**: 定期升级Redis版本，获取性能改进和安全补丁
5. **容量规划**: 监控内存增长趋势，提前规划容量扩展

### 告警设置
配置关键告警规则：
- 内存使用率超过80%
- 命中率低于90%
- 平均延迟超过10ms
- 主从复制延迟超过10秒
- 连接数接近最大限制

**Section sources**
- [config.yaml](file://manifest/config/config.yaml#L27-L57)