# Redis缓存配置

<cite>
**本文引用的文件**   
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)
</cite>

## 更新摘要
**所做更改**   
- 更新了连接池与连接工厂部分，强调密码认证的安全增强
- 新增了安全配置章节，详细说明密码管理和环境变量注入
- 更新了故障排查指南，包含密码认证相关的常见问题
- 增强了生产环境安全最佳实践建议

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [安全配置](#安全配置)
9. [故障排查指南](#故障排查指南)
10. [结论](#结论)
11. [附录](#附录)

## 简介
本文件面向Redis缓存配置模块，聚焦以下主题：连接池配置、序列化策略（JSON）、过期时间管理、键生成策略、缓存穿透防护与热点数据缓存方案、集群与哨兵模式配置、监控指标收集。文档基于仓库中实际存在的Redis配置类与配置文件进行说明，并提供可操作的实践建议与图示，帮助读者快速理解并落地最佳实践。

**重要更新**：本项目已全面启用Redis密码认证，所有模块均使用统一的安全配置策略，确保连接安全性。

## 项目结构
本项目为多模块Spring Boot工程，Redis相关配置集中在基础模块的公共配置类中，应用通过统一的RedisTemplate/CacheManager对外暴露缓存能力。关键位置如下：
- 基础配置模块：提供Redis连接、序列化、缓存管理器装配等通用能力
- 应用模块：通过application.yml注入Redis连接参数，按需启用缓存功能

```mermaid
graph TB
subgraph "基础模块"
RC["RedisConfig<br/>连接与序列化"]
JC["JacksonConfig<br/>日期与空值处理"]
end
subgraph "应用模块"
APP_YML["application.yml<br/>Redis连接参数<br/>含密码认证"]
AUTH_YML["application.yml<br/>Redis连接参数<br/>含密码认证"]
APP_CACHE["业务缓存使用<br/>@Cacheable/@CacheEvict"]
end
RC --> APP_CACHE
JC --> RC
APP_YML --> RC
AUTH_YML --> RC
```

**图表来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)

## 核心组件
- Redis连接与序列化装配：统一创建RedisConnectionFactory、RedisTemplate、StringRedisTemplate与CacheManager，确保全链路使用一致的序列化器与键前缀
- JSON序列化策略：基于Jackson，集中配置日期格式、时区、空值处理、忽略未知字段等
- 过期时间管理：按业务维度设置默认TTL或Key级TTL，避免长尾热点导致内存膨胀
- 键生成策略：统一命名空间、模块前缀、实体标识与属性组合，保证跨服务一致性
- 缓存穿透防护：空值缓存+布隆过滤器（可选）+限流降级
- 热点数据缓存：本地缓存+分布式缓存双层保护，结合随机过期与预热机制
- 集群与哨兵：根据部署环境选择单机、哨兵或集群模式，统一在配置中心管理
- 监控指标：暴露连接池状态、命中率、慢查询、序列化开销等指标
- **安全认证**：统一的密码认证机制，支持环境变量注入和生产环境安全配置

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)

## 架构总览
下图展示从应用层到Redis的调用路径与关键配置点，包括连接工厂、序列化器、缓存管理器与业务缓存注解的使用关系。

```mermaid
sequenceDiagram
participant App as "业务代码"
participant CacheMgr as "CacheManager"
participant RT as "RedisTemplate"
participant Conn as "RedisConnectionFactory"
participant Auth as "密码认证"
participant Redis as "Redis服务器"
App->>CacheMgr : 获取缓存(键, 类型)
CacheMgr->>RT : 读取/写入(序列化后)
RT->>Conn : 获取连接
Conn->>Auth : 密码验证
Auth-->>Conn : 验证通过
Conn-->>RT : 返回连接
RT->>Redis : 执行命令
Redis-->>RT : 返回结果
RT-->>CacheMgr : 反序列化后的对象
CacheMgr-->>App : 返回数据
```

**图表来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

## 详细组件分析

### 连接池与连接工厂
- 连接工厂：根据application.yml中的host、port、password、database、timeout等参数构建RedisConnectionFactory；支持单机、哨兵、集群三种拓扑
- 连接池：针对Lettuce/Jedis（以实际实现为准）配置最大连接数、最小空闲、最大等待时间、超时重试等，避免高并发下连接耗尽
- 健康检查：开启连接保活与心跳检测，降低断线重连抖动
- **安全增强**：所有模块均已启用密码认证，确保连接安全性

**更新** 已全面启用密码认证，crm-app和crm-auth模块均使用相同的密码策略，提供一致的安全保障。

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)

### 序列化策略（JSON）
- 序列化器：采用Jackson序列化器，统一对Key与Value进行JSON编码，便于可读性与跨语言兼容
- 日期与时区：全局配置ISO-8601或自定义格式，统一时区，避免跨时区解析差异
- 空值处理：配置是否序列化null字段，避免冗余数据；对Optional与集合做规范化处理
- 扩展性：注册自定义序列化/反序列化器，支持枚举、金额、大对象压缩等场景

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

### 过期时间管理
- 默认TTL：为不同业务域设置合理默认过期时间，防止僵尸数据
- Key级TTL：热点Key可设置较短TTL配合刷新策略，冷数据延长TTL
- 过期事件：谨慎开启过期监听，避免风暴式回调影响主流程

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

### 缓存键生成策略
- 命名规范：模块前缀 + 业务域 + 实体标识 + 条件参数哈希，保证唯一且可读
- 分隔符：统一使用":"作为层级分隔，便于批量删除与统计
- 长度控制：对过长参数进行哈希或截断，避免超长Key

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

### 缓存穿透防护
- 空值缓存：对不存在的数据写入短TTL空值，限制DB冲击
- 布隆过滤器：对高频查询ID集预加载，拦截非法请求
- 限流降级：对异常热点Key进行限流与熔断，保障整体可用性

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

### 热点数据缓存方案
- 双层缓存：本地缓存（如Caffeine）+ 分布式缓存（Redis），热点读优先命中本地
- 随机过期：为热点Key添加随机抖动，避免同时失效引发雪崩
- 预热策略：启动或低峰期预加载热点数据，缩短冷启动延迟

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

### 集群与哨兵模式配置
- 单机模式：适用于开发测试或小规模生产
- 哨兵模式：主从切换自动发现，适合中等规模与高可用需求
- 集群模式：分片扩容，适合大规模数据与高吞吐场景
- 配置要点：节点列表、密码、TLS、超时、重试次数、槽位映射等

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)

### 监控指标收集
- 连接池指标：活跃连接、空闲连接、等待队列长度、超时次数
- 缓存指标：命中率、缺失率、读写耗时分布、序列化耗时
- 慢查询：记录慢操作与Top Key，定位热点与问题Key
- 告警阈值：连接池耗尽、命中率骤降、慢查询突增等

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)

## 依赖关系分析
Redis配置模块依赖Spring Boot的Redis抽象与Jackson序列化库，并通过application.yml注入运行时参数。业务层通过CacheManager与RedisTemplate访问缓存，保持解耦。

```mermaid
graph LR
YML["application.yml<br/>含密码配置"] --> CFG["RedisConfig"]
CFG --> CFY["RedisConnectionFactory<br/>带密码认证"]
CFG --> RT["RedisTemplate"]
CFG --> CM["CacheManager"]
RT --> JCK["Jackson序列化器"]
CM --> RT
```

**图表来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

## 性能考量
- 连接池调优：根据QPS与平均响应时间估算最大连接数，避免过大导致内存压力
- 序列化优化：避免大对象直接入缓存，必要时压缩或拆分存储
- 过期策略：热点Key短TTL+随机抖动，冷数据长TTL，减少扫描与淘汰成本
- 网络优化：开启TCP_NODELAY、合理设置超时与重试，降低网络抖动影响
- 监控驱动：基于命中率与慢查询持续调优，避免"凭感觉"配置

## 安全配置

### 密码认证机制
本项目已全面启用Redis密码认证，所有模块均使用统一的安全配置策略：

- **统一密码策略**：crm-app和crm-auth模块使用相同的密码配置，确保系统间的一致性
- **环境变量注入**：生产环境推荐使用环境变量注入敏感信息，避免硬编码
- **连接加密**：支持TLS加密传输，确保数据传输安全

### 配置示例
```yaml
spring:
  data:
    redis:
      host: your-host
      port: 6379
      database: 0
      password: ${REDIS_PASSWORD}  # 使用环境变量
```

### 安全最佳实践
- **生产环境**：必须使用环境变量或密钥管理服务注入密码
- **权限控制**：为不同应用分配独立的Redis数据库和权限
- **审计日志**：启用Redis访问日志，记录认证失败和异常操作
- **定期轮换**：定期更换Redis密码，遵循安全基线要求

**章节来源**
- [application.yml](file://crm-app/src/main/resources/application.yml)
- [application.yml](file://crm-auth/src/main/resources/application.yml)

## 故障排查指南
- 连接失败：检查host/port/password/database、防火墙与TLS配置；查看连接池日志与重试次数
- **认证失败**：确认密码配置正确，检查Redis服务器密码设置；验证网络连接和端口可达性
- 序列化异常：核对实体类字段与注解，确认日期格式与时区一致；检查空值与未知字段策略
- 缓存未命中：验证键生成规则与命名空间；检查TTL是否过短；确认缓存注解使用是否正确
- 热点击穿：观察空值缓存是否生效；检查布隆过滤器与限流开关；评估是否需要本地缓存
- 集群/哨兵异常：检查节点拓扑与健康状态；关注主从切换与槽位重平衡期间的延迟

**更新** 新增认证失败的排查步骤，重点关注密码配置和网络连通性。

**章节来源**
- [RedisConfig.java](file://crm-base/src/main/java/com/crm/base/config/RedisConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

## 结论
通过统一的Redis配置与序列化策略，项目实现了稳定、可扩展的缓存基础设施。结合合理的键生成、过期管理与穿透防护，可在高并发与复杂部署环境下保持高性能与高可用。**特别重要的是，全面的密码认证机制确保了连接安全性，为生产环境提供了可靠的安全保障。** 建议在生产环境引入完善的监控与告警体系，持续优化连接池、序列化与缓存策略。

## 附录
- 常用配置项清单（示例）
  - 连接参数：host、port、password、database、timeout、connect-timeout、read-timeout
  - 连接池：max-active、max-idle、min-idle、max-wait、test-on-borrow
  - 序列化：日期格式、时区、空值处理、忽略未知字段
  - 缓存：默认TTL、键前缀、命名空间
  - 集群/哨兵：nodes、master-name、password、tls-enabled
- 最佳实践清单
  - 所有Key统一前缀与分层，便于批量清理与统计
  - 热点Key加随机过期，避免雪崩
  - 大对象拆分或压缩，减少内存占用
  - 开启慢查询与命中率监控，定期复盘
  - **生产环境必须启用密码认证和环境变量注入**
  - **定期轮换密码并监控认证失败日志**