# 移除 Redis 依赖改造为内存缓存设计文档 ## 1. 背景 当前项目中 Redis 不仅用于通用缓存，还承担了以下业务能力： - 登录态缓存 - 验证码缓存 - 密码错误次数统计 - 防重提交 - 接口限流 - 系统参数缓存 - 数据字典缓存 - 在线用户监控 - 缓存监控页 本次改造目标是移除 Redis 依赖，并将以上依赖 Redis 的能力改造为基于单实例后端 JVM 内存的实现。 ## 2. 设计约束 - 后端部署模型明确为单实例 - 不引入 Redis 兼容层、中间件替代品或额外持久化方案 - 不引入 Caffeine、Guava 等新的缓存框架 - 不改变现有业务 key 前缀和主要调用方式 - 不做多实例共享、重启恢复、降级兜底等额外设计 - 保留缓存监控功能，但改为展示内存缓存信息 ## 3. 参考实现 本次设计参考 git 远端分支 `origin/892-without-redis` 的处理方向，但仅借鉴其“保留业务缓存入口、底层改为内存存储”的思路，不引入与当前 JDK 1.8 / Spring Boot 2 技术栈无关的框架升级改造。 ## 4. 总体方案 ### 4.1 核心思路 保留现有 `com.ruoyi.common.core.redis.RedisCache` 作为统一业务缓存入口，将其底层实现从 `RedisTemplate` 改为进程内缓存存储。 这样可以保证以下调用方的业务逻辑基本不变： - `TokenService` - `SysLoginService` - `SysRegisterService` - `SysPasswordService` - `SameUrlDataInterceptor` - `SysConfigServiceImpl` - `DictUtils` - `SysUserOnlineController` - `CacheController` ### 4.2 存储结构 在 `ruoyi-common` 中新增本地缓存存储组件，职责如下： - 使用 `ConcurrentHashMap` 保存缓存数据 - `CacheEntry` 保存： - 实际缓存值 `value` - 过期时间戳 `expireAtMillis` - 读操作时判断是否过期 - 过期数据在读取、扫描 key、统计快照时清理 ### 4.3 保留的缓存门面能力 `RedisCache` 对外继续保留以下常用方法，以降低改造面： - `setCacheObject` - `getCacheObject` - `deleteObject` - `hasKey` - `expire` - `getExpire` - `keys` - `setCacheMap` - `getCacheMap` - `setCacheMapValue` - `getCacheMapValue` - `setCacheList` - `getCacheList` - `setCacheSet` - `getCacheSet` 另外补充两个内存实现需要的能力： - `increment(key, timeout, unit)`：支持限流计数 - `getCacheStats()`：支持缓存监控页展示统计信息 ## 5. 功能映射设计 ### 5.1 登录态缓存 - `TokenService` 继续使用 `LOGIN_TOKEN_KEY + token` 作为缓存 key - 登录成功时将 `LoginUser` 写入本地缓存，并设置与当前 token 配置一致的过期时间 - 鉴权时仍通过 JWT 中的 token 标识查找缓存中的 `LoginUser` - token 临近过期时继续刷新本地缓存 TTL - 退出登录、强退用户时继续删除对应缓存 key 该设计保持当前认证链路不变，仅将状态存储位置从 Redis 改为 JVM 内存。 ### 5.2 验证码缓存 - `CaptchaController` 继续将验证码写入 `CAPTCHA_CODE_KEY + uuid` - TTL 保持分钟级 - `SysLoginService` 与 `SysRegisterService` 校验验证码后继续删除对应 key ### 5.3 密码错误次数统计 - `SysPasswordService` 继续使用 `PWD_ERR_CNT_KEY + username` - 每次密码校验失败，错误次数自增并重置锁定窗口 TTL - 达到最大错误次数时维持现有异常行为 - 登录成功后清理错误次数缓存 ### 5.4 防重提交 - `SameUrlDataInterceptor` 继续使用 `REPEAT_SUBMIT_KEY + 请求地址 + token/header` - 缓存值仍为请求参数快照和时间戳 - TTL 继续使用注解 `interval` 指定的毫秒值 - 比较逻辑不变，仍按“参数一致且时间窗口内重复提交”拦截 ### 5.5 限流 - `RateLimiterAspect` 删除对 `RedisTemplate` 和 Lua 脚本的依赖 - 改为调用 `RedisCache.increment(key, timeout, unit)` 实现固定窗口内计数 - 当计数值超过注解配置的阈值时，继续抛出当前业务异常 限流范围明确为当前单实例应用内，不做跨实例聚合。 ### 5.6 系统参数缓存 - `SysConfigServiceImpl` 保持现有 key 规则 `SYS_CONFIG_KEY + configKey` - 读取优先查本地缓存，未命中时查库并回填缓存 - 新增、修改、删除、刷新操作保持现有清理逻辑 ### 5.7 数据字典缓存 - `DictUtils` 保持现有 key 规则 `SYS_DICT_KEY + dictType` - 字典写入、读取、删除、批量清理逻辑不变 ### 5.8 在线用户 - `SysUserOnlineController` 继续通过 `LOGIN_TOKEN_KEY*` 扫描缓存 key - 缓存中的 `LoginUser` 继续转换为在线用户列表 - 强退用户仍通过删除指定 token key 实现 在线用户监控的可见范围定义为“当前单实例内未过期的登录 token”。 ### 5.9 缓存监控 保留 `/monitor/cache` 相关接口和前端页面，但数据源改为本地缓存统计： - 缓存类型：`IN_MEMORY` - 运行模式：`single-instance` - 总键数 - 命中次数 - 未命中次数 - 过期清理次数 - 写入次数 同时保留以下能力： - 按缓存分类查看 key - 查看缓存值 - 按分类清理缓存 - 按 key 清理缓存 - 清空全部缓存 ## 6. 前端适配设计 本次前端改造仅针对缓存监控页，不扩展到其它模块。 ### 6.1 缓存监控首页 页面保留原入口，但将 Redis 专属展示改为内存缓存语义： - `Redis版本` 改为 `缓存类型` - `运行模式` 显示 `单实例` - `dbSize` 语义改为 `总键数` - 图表改为展示： - 命中次数 - 未命中次数 - 过期清理次数 - 写入次数 ### 6.2 缓存列表页 - 保持现有接口路径和交互方式 - 展示的数据仍按缓存 key 前缀分类 - 支持查看值与清理操作 ## 7. 依赖与配置调整 ### 7.1 删除依赖 从 Maven 依赖中移除： - `spring-boot-starter-data-redis` - `commons-pool2` ### 7.2 删除配置 从 `ruoyi-admin/src/main/resources/application.yml` 中删除： - `spring.redis` 整段配置 ### 7.3 删除基础设施代码 删除或停用以下 Redis 专属配置类： - `RedisConfig` - `FastJson2JsonRedisSerializer` ## 8. 兼容边界 以下行为是本次改造后的明确边界： - 服务重启后，登录态、验证码、限流计数、在线用户、密码错误次数等内存数据全部丢失 - 缓存监控统计为当前进程内累计统计，不代表外部系统状态 - 不支持多实例共享缓存 以上边界与“单实例后端”约束一致，属于本次设计的预期结果。 ## 9. 测试与验收 ### 9.1 后端测试重点 - 本地缓存对象读写 - TTL 过期行为 - `keys` 模糊匹配 - 删除和批量删除 - 原子递增计数 - token 登录态写入、读取、刷新、删除 - 限流行为 - 验证码写入与校验 - 在线用户列表与强退 - 系统参数缓存与字典缓存读取、刷新 - 缓存监控接口返回结构 ### 9.2 前端验收重点 - 缓存监控页正常打开 - 基本信息展示为内存缓存语义 - 图表能正确展示内存统计数据 - 缓存列表页能查看 key、查看值、清理缓存 ## 10. 实施拆分 由于本次涉及后端与前端改造，实施阶段需要分别输出两份实施计划文档： - 后端实施计划 - 前端实施计划 实施计划将在本设计确认后单独编写并保存到 `doc/` 目录。