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 统计缓存。

背景说明

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

Cache 模块基于已有 RedisService 封装，提供统一的缓存接口和策略管理。

模块职责

本模块负责：
- 统一缓存接口（基于 RedisService 封装）
- 缓存 Key 命名规范定义
- 缓存过期策略（TTL 管理）
- 缓存失效策略（主动失效 + 被动过期）
- 缓存穿透保护（空值缓存）
本模块不负责：
- 各业务模块的具体缓存内容（由各模块自行决定缓存什么）
- Redis 运维（走 Server Monitor）

第一阶段重点缓存对象

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

配置数据（Config Module）：TTL 300s
Admin 权限数据（Admin Auth）：TTL 300s
服务商/模型路由配置（AI Gateway）：TTL 600s
敏感词库（Content Safety）：TTL 3600s
Dashboard 统计数据（Workspace Experience）：TTL 300s
用户基础信息（User & Account）：TTL 300s
知识库元数据（Workspace & KnowledgeBase）：TTL 300s

需要注意的风险

不要缓存用户隐私敏感内容太久
不要缓存 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 视图：是

验收标准

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

禁止事项

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

不建议当前阶段实现

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

## 目标设计知习统一缓存模块，为全系统提供 Redis 缓存策略，覆盖配置缓存、权限缓存、服务状态缓存和 Dashboard 统计缓存。 ## 背景说明多个模块需要缓存以提高性能：Config 模块的配置数据、Admin Auth 的权限数据、Workspace Experience 的 Dashboard 聚合数据等。如果不统一管理缓存策略（key 命名规范、过期时间、失效策略），后期会出现缓存混乱和脏数据问题。 Cache 模块基于已有 RedisService 封装，提供统一的缓存接口和策略管理。 ## 模块职责 1. 本模块负责： - 统一缓存接口（基于 RedisService 封装） - 缓存 Key 命名规范定义 - 缓存过期策略（TTL 管理） - 缓存失效策略（主动失效 + 被动过期） - 缓存穿透保护（空值缓存） 2. 本模块不负责： - 各业务模块的具体缓存内容（由各模块自行决定缓存什么） - Redis 运维（走 Server Monitor） ## 第一阶段重点缓存对象请判断以下缓存是否合理，并设计过期时间： - 配置数据（Config Module）：TTL 300s - Admin 权限数据（Admin Auth）：TTL 300s - 服务商/模型路由配置（AI Gateway）：TTL 600s - 敏感词库（Content Safety）：TTL 3600s - Dashboard 统计数据（Workspace Experience）：TTL 300s - 用户基础信息（User & Account）：TTL 300s - 知识库元数据（Workspace & KnowledgeBase）：TTL 300s ## 需要注意的风险 - 不要缓存用户隐私敏感内容太久 - 不要缓存 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 数量） - 手动清除指定缓存 ## 交付检查 - [x] 是否需要 Prisma migration：否 - [x] 是否需要 MySQL：否 - [x] 是否需要 Redis：是 - [x] 是否需要 BullMQ：否 - [x] 是否需要 Admin 视图：是 ## 验收标准 1. 统一缓存接口设计（基于已有 RedisService 封装） 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

wangdl commented

2026-05-24 15:58:31 +08:00

✅ M3-06 实施完成

设计决策

基于已有 RedisService 封装而非新增 @nestjs/cache-manager 依赖。理由：

RedisService 已提供完整的 get/set/del/exists/keys 能力
新增 cache-manager 依赖增加复杂度而无实质增益
项目已有统一 key 命名前缀（如 workspace:dashboard:userId）

新增内容

模块	说明
`CacheService`	统一缓存接口，含 `get/set/del/wrap/flushPattern/flushAll/getStats`
`AdminCacheController`	Admin 缓存管理（统计/清除/重置）
Key 命名规范	`module:entity:id` 格式，自动添加 `cache:` 前缀

缓存穿透保护

CacheService.wrap() 实现 cache-aside 模式：

命中 → 返回缓存值
未命中 → 执行 factory，缓存结果
factory 返回 null → 缓存 __CACHE_NULL__ 哨兵值（较短 TTL ≤ 60s）

第一阶段缓存对象 & TTL 策略

缓存对象	Key 模式	TTL
配置数据	`cache:config:app:*`	300s
Admin 权限	`cache:admin:permission:*`	300s
AI Gateway 路由	`cache:ai:routes`	600s
敏感词库	`cache:safety:words`	3600s
Dashboard 统计	`cache:workspace:dashboard:*`	300s
用户基础信息	`cache:user:info:*`	300s
知识库元数据	`cache:kb:meta:*`	300s

AAPI 端点

端点	方法	说明
`/admin-api/cache/stats`	GET	缓存命中率统计
`/admin-api/cache/flush/:module`	POST	按模块清除缓存
`/admin-api/cache/flush-key`	POST	清除指定 key
`/admin-api/cache/flush-all`	POST	清除所有缓存
`/admin-api/cache/reset-stats`	POST	重置统计

Admin 页面

菜单 系统运维 → 缓存管理 已添加（/cache 路由）。

E2E（test/m3.e2e-spec.ts）

6 tests: stats, flush-key, flush module, reset stats, flush-all, and auth check.

npx jest --config ./test/jest-e2e.json test/m3.e2e-spec.ts  # 35 passed, 1 pre-existing failure

## ✅ M3-06 实施完成 ### 设计决策基于已有 `RedisService` 封装而非新增 `@nestjs/cache-manager` 依赖。理由： - RedisService 已提供完整的 get/set/del/exists/keys 能力 - 新增 cache-manager 依赖增加复杂度而无实质增益 - 项目已有统一 key 命名前缀（如 `workspace:dashboard:userId`） ### 新增内容 | 模块 | 说明 | |------|------| | `CacheService` | 统一缓存接口，含 `get/set/del/wrap/flushPattern/flushAll/getStats` | | `AdminCacheController` | Admin 缓存管理（统计/清除/重置） | | Key 命名规范 | `module:entity:id` 格式，自动添加 `cache:` 前缀 | ### 缓存穿透保护 `CacheService.wrap()` 实现 cache-aside 模式： - 命中 → 返回缓存值 - 未命中 → 执行 factory，缓存结果 - factory 返回 null → 缓存 `__CACHE_NULL__` 哨兵值（较短 TTL ≤ 60s） ### 第一阶段缓存对象 & TTL 策略 | 缓存对象 | Key 模式 | TTL | |---------|---------|-----| | 配置数据 | `cache:config:app:*` | 300s | | Admin 权限 | `cache:admin:permission:*` | 300s | | AI Gateway 路由 | `cache:ai:routes` | 600s | | 敏感词库 | `cache:safety:words` | 3600s | | Dashboard 统计 | `cache:workspace:dashboard:*` | 300s | | 用户基础信息 | `cache:user:info:*` | 300s | | 知识库元数据 | `cache:kb:meta:*` | 300s | ### AAPI 端点 | 端点 | 方法 | 说明 | |------|------|------| | `/admin-api/cache/stats` | GET | 缓存命中率统计 | | `/admin-api/cache/flush/:module` | POST | 按模块清除缓存 | | `/admin-api/cache/flush-key` | POST | 清除指定 key | | `/admin-api/cache/flush-all` | POST | 清除所有缓存 | | `/admin-api/cache/reset-stats` | POST | 重置统计 | ### Admin 页面菜单 `系统运维 → 缓存管理` 已添加（`/cache` 路由）。 ### E2E（test/m3.e2e-spec.ts） 6 tests: stats, flush-key, flush module, reset stats, flush-all, and auth check. ```bash npx jest --config ./test/jest-e2e.json test/m3.e2e-spec.ts # 35 passed, 1 pre-existing failure ```

wangdl closed this issue

2026-06-06 14:43:16 +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