M3-06 Cache Module 基础版 #34

New Issue

wangdl · 2026-05-22T21:09:50+08:00

wangdl commented

2026-05-22 21:09:50 +08:00

目标

设计知习统一缓存模块，为全系统提供 Redis 缓存策略，覆盖配置缓存、权限缓存、服务状态缓存和 Dashboard 统计缓存。

本 Issue 只做模块架构设计，不直接实现代码。

背景说明

多个模块需要缓存以提高性能：Config 模块的配置数据、Admin Auth 的权限数据、Workspace Experience 的 Dashboard 聚合数据等。如果不统一管理缓存策略（key 命名规范、过期时间、失效策略），后期会出现缓存混乱和脏数据问题。

Cache 模块基于 Redis + @nestjs/cache-manager，提供统一的缓存接口和策略管理。

模块职责

本模块负责：
- 统一缓存接口（基于 @nestjs/cache-manager）
- 缓存 Key 命名规范定义
- 缓存过期策略（TTL 管理）
- 缓存失效策略（主动失效 + 被动过期）
- 缓存穿透保护（空值缓存）
- 缓存预热策略（服务启动时加载热点数据）
本模块不负责：
- 各业务模块的具体缓存内容（由各模块自行决定缓存什么）
- Redis 运维（走 Server Monitor）

第一阶段重点缓存对象

请判断以下缓存是否合理，并设计过期时间：

配置数据（Config Module）：TTL 建议
Admin 权限数据（Admin Auth）：TTL 建议
服务商/模型路由配置（AI Gateway）：TTL 建议
敏感词库（Content Safety）：TTL 建议
Dashboard 统计数据（Workspace Experience）：TTL 建议
用户基础信息（User & Account）：是否需要缓存，请判断
知识库元数据（Workspace & KnowledgeBase）：是否需要缓存，请判断

需要注意的风险

不要缓存用户隐私敏感内容太久
不要缓存 AI 回答（会导致引用过期）
不要让缓存绕过权限校验
不要在 M1 阶段缓存 RAG 检索结果

基础设施依赖

Redis：是（核心依赖）
MySQL：否（缓存层不直接操作数据库）

API 设计

Internal Provider（供各模块调用）：
- CacheService.get(key)
- CacheService.set(key, value, ttl)
- CacheService.del(key)
- CacheService.wrap(key, factory, ttl)（缓存穿透保护）
AAPI：
- 缓存状态查看（命中率、key 数量）
- 手动清除指定缓存

交付检查

是否需要 Prisma migration：否
是否需要 MySQL：否
是否需要 Redis：是
是否需要 BullMQ：否
是否需要 Admin 视图：是

验收标准

统一缓存接口设计（基于 @nestjs/cache-manager 封装）
Key 命名规范文档
第一阶段缓存对象清单 + TTL 策略
缓存穿透保护方案
Admin 缓存管理视图设计
集成测试覆盖缓存读写和失效

禁止事项

禁止缓存 AI 回答内容
禁止缓存包含用户隐私的数据超过合理时间
禁止缓存绕过权限校验
禁止在 M1 阶段缓存 RAG 检索结果
禁止各模块自行管理 Redis key（必须通过 Cache Module 统一命名规范）

不建议当前阶段实现

多级缓存（L1 内存 + L2 Redis）
缓存预热自动化
缓存命中率监控和告警

## 目标设计知习统一缓存模块，为全系统提供 Redis 缓存策略，覆盖配置缓存、权限缓存、服务状态缓存和 Dashboard 统计缓存。本 Issue 只做模块架构设计，不直接实现代码。 ## 背景说明多个模块需要缓存以提高性能：Config 模块的配置数据、Admin Auth 的权限数据、Workspace Experience 的 Dashboard 聚合数据等。如果不统一管理缓存策略（key 命名规范、过期时间、失效策略），后期会出现缓存混乱和脏数据问题。 Cache 模块基于 Redis + @nestjs/cache-manager，提供统一的缓存接口和策略管理。 ## 模块职责 1. 本模块负责： - 统一缓存接口（基于 @nestjs/cache-manager） - 缓存 Key 命名规范定义 - 缓存过期策略（TTL 管理） - 缓存失效策略（主动失效 + 被动过期） - 缓存穿透保护（空值缓存） - 缓存预热策略（服务启动时加载热点数据） 2. 本模块不负责： - 各业务模块的具体缓存内容（由各模块自行决定缓存什么） - Redis 运维（走 Server Monitor） ## 第一阶段重点缓存对象请判断以下缓存是否合理，并设计过期时间： - 配置数据（Config Module）：TTL 建议 - Admin 权限数据（Admin Auth）：TTL 建议 - 服务商/模型路由配置（AI Gateway）：TTL 建议 - 敏感词库（Content Safety）：TTL 建议 - Dashboard 统计数据（Workspace Experience）：TTL 建议 - 用户基础信息（User & Account）：是否需要缓存，请判断 - 知识库元数据（Workspace & KnowledgeBase）：是否需要缓存，请判断 ## 需要注意的风险 - 不要缓存用户隐私敏感内容太久 - 不要缓存 AI 回答（会导致引用过期） - 不要让缓存绕过权限校验 - 不要在 M1 阶段缓存 RAG 检索结果 ## 基础设施依赖 - Redis：是（核心依赖） - MySQL：否（缓存层不直接操作数据库） ## API 设计 1. Internal Provider（供各模块调用）： - CacheService.get(key) - CacheService.set(key, value, ttl) - CacheService.del(key) - CacheService.wrap(key, factory, ttl)（缓存穿透保护） 2. AAPI： - 缓存状态查看（命中率、key 数量） - 手动清除指定缓存 ## 交付检查 - [ ] 是否需要 Prisma migration：否 - [ ] 是否需要 MySQL：否 - [ ] 是否需要 Redis：是 - [ ] 是否需要 BullMQ：否 - [ ] 是否需要 Admin 视图：是 ## 验收标准 1. 统一缓存接口设计（基于 @nestjs/cache-manager 封装） 2. Key 命名规范文档 3. 第一阶段缓存对象清单 + TTL 策略 4. 缓存穿透保护方案 5. Admin 缓存管理视图设计 6. 集成测试覆盖缓存读写和失效 ## 禁止事项 - 禁止缓存 AI 回答内容 - 禁止缓存包含用户隐私的数据超过合理时间 - 禁止缓存绕过权限校验 - 禁止在 M1 阶段缓存 RAG 检索结果 - 禁止各模块自行管理 Redis key（必须通过 Cache Module 统一命名规范） ## 不建议当前阶段实现 - 多级缓存（L1 内存 + L2 Redis） - 缓存预热自动化 - 缓存命中率监控和告警

wangdl added this to the M3：学习复习闭环（P2） milestone 2026-05-22 21:09:50 +08:00

wangdl self-assigned this 2026-05-22 21:09:50 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#34