886 lines
13 KiB
Markdown
886 lines
13 KiB
Markdown
([Files][1])([Files][2])([Files][3])([Files][4])([Files][5])
|
||
|
||
可以。下面我把 **知习后端 Redis 设计** 单独整理一版。
|
||
|
||
你可以把它理解成：
|
||
|
||
```text
|
||
MySQL：长期真实数据，必须可靠保存
|
||
Redis：短期状态、缓存、队列、限流、锁、任务进度
|
||
```
|
||
|
||
Redis **不需要建表**，需要设计的是：
|
||
|
||
```text
|
||
1. Redis 用在哪些场景
|
||
2. Key 怎么命名
|
||
3. Value 存什么
|
||
4. 过期时间多久
|
||
5. 哪些数据绝对不能只放 Redis
|
||
```
|
||
|
||
---
|
||
|
||
# 一、Redis 在知习里的定位
|
||
|
||
Redis 不作为主数据库。
|
||
|
||
它主要负责：
|
||
|
||
```text
|
||
1. 缓存
|
||
2. 限流
|
||
3. 队列
|
||
4. 临时任务状态
|
||
5. 分布式锁
|
||
6. 防重复提交
|
||
7. AI 调用次数统计
|
||
8. 短期 token / 黑名单
|
||
9. 通知任务调度
|
||
```
|
||
|
||
核心业务数据仍然必须写入 MySQL：
|
||
|
||
```text
|
||
用户
|
||
知识库
|
||
知识点
|
||
学习记录
|
||
主动回忆回答
|
||
AI 分析结果
|
||
待巩固项
|
||
复习计划
|
||
学习活跃记录
|
||
通知记录
|
||
用户设置
|
||
```
|
||
|
||
---
|
||
|
||
# 二、Redis Key 命名规范
|
||
|
||
建议统一用这种格式：
|
||
|
||
```text
|
||
业务域:对象类型:对象ID:字段
|
||
```
|
||
|
||
例如：
|
||
|
||
```text
|
||
cache:user:123:profile
|
||
rate:user:123:ai:daily:2026-05-09
|
||
lock:ai-analysis:session:987
|
||
job:ai-analysis:abc123:status
|
||
```
|
||
|
||
统一规则：
|
||
|
||
```text
|
||
1. 全部小写
|
||
2. 用冒号 : 分隔
|
||
3. 从大范围到小范围
|
||
4. userId、jobId、sessionId 明确写在 key 里
|
||
5. 带日期的 key 用 YYYY-MM-DD
|
||
6. 所有临时 key 必须设置 TTL
|
||
```
|
||
|
||
---
|
||
|
||
# 三、Redis 主要使用场景
|
||
|
||
## 1. 缓存 Cache
|
||
|
||
用于缓存高频读取的数据，减少 MySQL 压力。
|
||
|
||
### 用户资料缓存
|
||
|
||
```text
|
||
key:
|
||
cache:user:{userId}:profile
|
||
|
||
value:
|
||
{
|
||
"id": 123,
|
||
"nickname": "李明",
|
||
"avatarUrl": null,
|
||
"learningIdentity": "系统学习者",
|
||
"learningDirection": "认知科学"
|
||
}
|
||
|
||
ttl:
|
||
5-10 分钟
|
||
```
|
||
|
||
### 用户知识库列表缓存
|
||
|
||
```text
|
||
key:
|
||
cache:user:{userId}:knowledge-bases
|
||
|
||
value:
|
||
[
|
||
{
|
||
"id": 1,
|
||
"title": "认知心理学",
|
||
"itemCount": 42
|
||
}
|
||
]
|
||
|
||
ttl:
|
||
3-5 分钟
|
||
```
|
||
|
||
### 当前用户设置缓存
|
||
|
||
```text
|
||
key:
|
||
cache:user:{userId}:preferences
|
||
|
||
ttl:
|
||
10 分钟
|
||
```
|
||
|
||
注意：
|
||
|
||
```text
|
||
缓存可以丢
|
||
MySQL 不能丢
|
||
缓存更新不及时也没关系，但关键业务查询必须以 MySQL 为准
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 限流 Rate Limit
|
||
|
||
用于控制请求频率和 AI 成本。
|
||
|
||
### 用户每日 AI 调用次数
|
||
|
||
```text
|
||
key:
|
||
rate:user:{userId}:ai:daily:{date}
|
||
|
||
example:
|
||
rate:user:123:ai:daily:2026-05-09
|
||
|
||
value:
|
||
8
|
||
|
||
ttl:
|
||
到当天结束，或者 24 小时
|
||
```
|
||
|
||
用途：
|
||
|
||
```text
|
||
限制每天 AI 分析次数
|
||
限制生成回忆测试次数
|
||
限制找薄弱知识点次数
|
||
```
|
||
|
||
---
|
||
|
||
### IP 请求频率限制
|
||
|
||
```text
|
||
key:
|
||
rate:ip:{ip}:request:{minute}
|
||
|
||
example:
|
||
rate:ip:1.2.3.4:request:2026-05-09T10:35
|
||
|
||
value:
|
||
42
|
||
|
||
ttl:
|
||
60-120 秒
|
||
```
|
||
|
||
用途：
|
||
|
||
```text
|
||
防刷接口
|
||
防反馈表单乱提交
|
||
防登录接口暴力请求
|
||
```
|
||
|
||
---
|
||
|
||
### 登录尝试次数
|
||
|
||
```text
|
||
key:
|
||
rate:login:{ip}:{date}
|
||
|
||
ttl:
|
||
10-30 分钟
|
||
```
|
||
|
||
Apple 登录一般问题不大，但后面如果有邮箱登录、验证码登录，这个会用到。
|
||
|
||
---
|
||
|
||
## 3. 分布式锁 Lock
|
||
|
||
用于防止重复提交。
|
||
|
||
### 防止重复 AI 分析
|
||
|
||
```text
|
||
key:
|
||
lock:ai-analysis:session:{sessionId}
|
||
|
||
example:
|
||
lock:ai-analysis:session:987
|
||
|
||
value:
|
||
randomToken
|
||
|
||
ttl:
|
||
60-300 秒
|
||
```
|
||
|
||
场景：
|
||
|
||
```text
|
||
用户连续点两次“提交 AI 分析”
|
||
后端只允许创建一个分析任务
|
||
```
|
||
|
||
---
|
||
|
||
### 防止重复导入资料
|
||
|
||
```text
|
||
key:
|
||
lock:document-import:{importId}
|
||
|
||
ttl:
|
||
5-30 分钟
|
||
```
|
||
|
||
---
|
||
|
||
### 防止重复生成复习计划
|
||
|
||
```text
|
||
key:
|
||
lock:review-plan:user:{userId}:item:{itemId}
|
||
|
||
ttl:
|
||
60-300 秒
|
||
```
|
||
|
||
注意：
|
||
|
||
```text
|
||
锁一定要设置 TTL
|
||
解锁时要校验 value，不能误删别人的锁
|
||
```
|
||
|
||
---
|
||
|
||
## 4. AI 分析任务状态
|
||
|
||
AI 分析建议用异步任务。
|
||
|
||
流程：
|
||
|
||
```text
|
||
App 提交回答
|
||
→ 后端创建 ai_analysis_jobs 记录
|
||
→ 加入 Redis 队列
|
||
→ 返回 jobId
|
||
→ Worker 调用 AI
|
||
→ 结果写入 MySQL
|
||
→ Redis 状态改为 completed
|
||
```
|
||
|
||
### 任务状态 key
|
||
|
||
```text
|
||
key:
|
||
job:ai-analysis:{jobId}:status
|
||
|
||
value:
|
||
pending / processing / completed / failed
|
||
|
||
ttl:
|
||
24 小时
|
||
```
|
||
|
||
### 任务进度 key
|
||
|
||
```text
|
||
key:
|
||
job:ai-analysis:{jobId}:progress
|
||
|
||
value:
|
||
0-100
|
||
|
||
ttl:
|
||
24 小时
|
||
```
|
||
|
||
### 任务错误信息
|
||
|
||
```text
|
||
key:
|
||
job:ai-analysis:{jobId}:error
|
||
|
||
value:
|
||
"AI provider timeout"
|
||
|
||
ttl:
|
||
24 小时
|
||
```
|
||
|
||
注意：
|
||
|
||
```text
|
||
Redis 只存临时状态
|
||
最终任务记录和分析结果必须写入 MySQL：
|
||
ai_analysis_jobs
|
||
ai_analysis_results
|
||
focus_items
|
||
review_cards
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 资料导入任务状态
|
||
|
||
导入资料也建议异步。
|
||
|
||
场景：
|
||
|
||
```text
|
||
上传 PDF
|
||
粘贴长文本
|
||
导入链接
|
||
AI 解析生成知识点
|
||
```
|
||
|
||
### 导入任务状态
|
||
|
||
```text
|
||
key:
|
||
job:document-import:{importId}:status
|
||
|
||
value:
|
||
pending / parsing / chunking / generating / completed / failed
|
||
|
||
ttl:
|
||
24 小时
|
||
```
|
||
|
||
### 导入进度
|
||
|
||
```text
|
||
key:
|
||
job:document-import:{importId}:progress
|
||
|
||
value:
|
||
0-100
|
||
|
||
ttl:
|
||
24 小时
|
||
```
|
||
|
||
### 导入处理中提示
|
||
|
||
```text
|
||
key:
|
||
job:document-import:{importId}:message
|
||
|
||
value:
|
||
"正在提取关键知识点"
|
||
|
||
ttl:
|
||
24 小时
|
||
```
|
||
|
||
最终结果写入 MySQL：
|
||
|
||
```text
|
||
document_imports
|
||
uploaded_files
|
||
knowledge_items
|
||
knowledge_item_relations
|
||
tags
|
||
```
|
||
|
||
---
|
||
|
||
## 6. BullMQ 队列
|
||
|
||
如果后端是 Node.js / NestJS，建议用 BullMQ。
|
||
|
||
队列由 BullMQ 自动管理 Redis key，不需要你自己建。
|
||
|
||
建议预留 3 个队列：
|
||
|
||
```text
|
||
ai-analysis
|
||
document-import
|
||
notification
|
||
```
|
||
|
||
---
|
||
|
||
### ai-analysis 队列
|
||
|
||
任务数据：
|
||
|
||
```json
|
||
{
|
||
"jobId": 123,
|
||
"userId": 456,
|
||
"sessionId": 789,
|
||
"answerId": 1001,
|
||
"jobType": "active_recall_analysis"
|
||
}
|
||
```
|
||
|
||
处理逻辑：
|
||
|
||
```text
|
||
读取用户回答
|
||
调用 AI
|
||
生成分析结果
|
||
写入 ai_analysis_results
|
||
生成 focus_items
|
||
生成 review_cards
|
||
发送通知
|
||
```
|
||
|
||
---
|
||
|
||
### document-import 队列
|
||
|
||
任务数据：
|
||
|
||
```json
|
||
{
|
||
"importId": 123,
|
||
"userId": 456,
|
||
"knowledgeBaseId": 789,
|
||
"sourceType": "file"
|
||
}
|
||
```
|
||
|
||
处理逻辑：
|
||
|
||
```text
|
||
解析文件
|
||
提取文本
|
||
分段
|
||
生成知识点
|
||
写入 knowledge_items
|
||
更新 document_imports 状态
|
||
```
|
||
|
||
---
|
||
|
||
### notification 队列
|
||
|
||
任务数据：
|
||
|
||
```json
|
||
{
|
||
"userId": 456,
|
||
"type": "review_due",
|
||
"title": "8 张卡片今日到期复习",
|
||
"data": {
|
||
"reviewCount": 8
|
||
}
|
||
}
|
||
```
|
||
|
||
处理逻辑：
|
||
|
||
```text
|
||
写入 notifications 表
|
||
后面可扩展推送 APNs
|
||
```
|
||
|
||
---
|
||
|
||
# 四、Redis Key 总表
|
||
|
||
## 缓存类
|
||
|
||
```text
|
||
cache:user:{userId}:profile
|
||
cache:user:{userId}:preferences
|
||
cache:user:{userId}:knowledge-bases
|
||
cache:knowledge-base:{knowledgeBaseId}:summary
|
||
cache:review:user:{userId}:due-count
|
||
```
|
||
|
||
---
|
||
|
||
## 限流类
|
||
|
||
```text
|
||
rate:user:{userId}:ai:daily:{date}
|
||
rate:user:{userId}:feedback:hourly
|
||
rate:ip:{ip}:request:{minute}
|
||
rate:ip:{ip}:login:{date}
|
||
```
|
||
|
||
---
|
||
|
||
## 锁类
|
||
|
||
```text
|
||
lock:ai-analysis:session:{sessionId}
|
||
lock:ai-analysis:answer:{answerId}
|
||
lock:document-import:{importId}
|
||
lock:review-plan:user:{userId}:item:{itemId}
|
||
lock:feedback:ip:{ip}
|
||
```
|
||
|
||
---
|
||
|
||
## 任务状态类
|
||
|
||
```text
|
||
job:ai-analysis:{jobId}:status
|
||
job:ai-analysis:{jobId}:progress
|
||
job:ai-analysis:{jobId}:error
|
||
|
||
job:document-import:{importId}:status
|
||
job:document-import:{importId}:progress
|
||
job:document-import:{importId}:message
|
||
job:document-import:{importId}:error
|
||
```
|
||
|
||
---
|
||
|
||
## 会话临时状态
|
||
|
||
```text
|
||
session:learning:{sessionId}:heartbeat
|
||
session:learning:{sessionId}:current-step
|
||
session:active-recall:{sessionId}:draft
|
||
```
|
||
|
||
例如用户正在写回答，可以短期保存草稿：
|
||
|
||
```text
|
||
key:
|
||
session:active-recall:{sessionId}:draft
|
||
|
||
ttl:
|
||
1-24 小时
|
||
```
|
||
|
||
最终提交后还是写 MySQL。
|
||
|
||
---
|
||
|
||
## Token / 黑名单
|
||
|
||
```text
|
||
auth:refresh-token:blacklist:{tokenId}
|
||
auth:access-token:blacklist:{jwtId}
|
||
```
|
||
|
||
退出登录或注销账号时可用。
|
||
|
||
---
|
||
|
||
# 五、TTL 建议
|
||
|
||
```text
|
||
用户资料缓存：5-10 分钟
|
||
知识库列表缓存：3-5 分钟
|
||
AI 每日限流：到当天结束或 24 小时
|
||
IP 请求限流：60-120 秒
|
||
登录尝试限流：10-30 分钟
|
||
AI 分析任务状态：24 小时
|
||
资料导入任务状态：24 小时
|
||
分布式锁：60 秒到 30 分钟，按任务类型决定
|
||
学习草稿：1-24 小时
|
||
Token 黑名单：到 token 原本过期时间
|
||
```
|
||
|
||
---
|
||
|
||
# 六、Redis 数据类型建议
|
||
|
||
## String
|
||
|
||
最常用。
|
||
|
||
用于：
|
||
|
||
```text
|
||
缓存 JSON
|
||
计数器
|
||
状态
|
||
锁
|
||
```
|
||
|
||
示例：
|
||
|
||
```text
|
||
rate:user:123:ai:daily:2026-05-09 = 8
|
||
job:ai-analysis:1001:status = processing
|
||
```
|
||
|
||
---
|
||
|
||
## Hash
|
||
|
||
可选，用于对象字段更新频繁的场景。
|
||
|
||
例如：
|
||
|
||
```text
|
||
job:ai-analysis:1001
|
||
status = processing
|
||
progress = 40
|
||
message = 正在分析薄弱点
|
||
```
|
||
|
||
v0.1 也可以先用 String 多 key，简单直接。
|
||
|
||
---
|
||
|
||
## List / Stream
|
||
|
||
队列相关，但如果使用 BullMQ，不需要自己操作。
|
||
|
||
---
|
||
|
||
## Set
|
||
|
||
可选。
|
||
|
||
比如记录某天处理过的学习项：
|
||
|
||
```text
|
||
set:user:{userId}:reviewed-items:{date}
|
||
```
|
||
|
||
---
|
||
|
||
## Sorted Set
|
||
|
||
后期可用于按时间排序的任务。
|
||
|
||
例如：
|
||
|
||
```text
|
||
zset:review:due
|
||
```
|
||
|
||
但 v0.1 可以先不做，复习到期直接查 MySQL。
|
||
|
||
---
|
||
|
||
# 七、哪些不要放 Redis
|
||
|
||
不要把这些只放 Redis：
|
||
|
||
```text
|
||
用户资料
|
||
知识库内容
|
||
知识点内容
|
||
学习记录
|
||
主动回忆回答
|
||
AI 分析结果
|
||
待巩固项
|
||
复习卡片
|
||
复习记录
|
||
学习活跃记录
|
||
通知记录
|
||
用户设置
|
||
协议同意记录
|
||
```
|
||
|
||
这些全部要写 MySQL。
|
||
|
||
Redis 可以缓存它们，但不是唯一来源。
|
||
|
||
---
|
||
|
||
# 八、Redis 和 MySQL 的典型组合流程
|
||
|
||
## AI 分析流程
|
||
|
||
```text
|
||
1. MySQL 创建 ai_analysis_jobs
|
||
2. Redis 加入 ai-analysis 队列
|
||
3. Redis 存 job 状态 processing
|
||
4. Worker 调用 AI
|
||
5. MySQL 写 ai_analysis_results
|
||
6. MySQL 写 focus_items
|
||
7. MySQL 写 review_cards
|
||
8. Redis 存 job 状态 completed
|
||
9. MySQL 写 notifications
|
||
```
|
||
|
||
---
|
||
|
||
## 资料导入流程
|
||
|
||
```text
|
||
1. MySQL 创建 document_imports
|
||
2. Redis 加入 document-import 队列
|
||
3. Redis 存导入进度
|
||
4. Worker 解析文件
|
||
5. MySQL 写 knowledge_items
|
||
6. MySQL 更新 document_imports 为 success
|
||
7. Redis 状态 completed
|
||
```
|
||
|
||
---
|
||
|
||
## 学习活跃图流程
|
||
|
||
```text
|
||
1. 用户完成学习动作
|
||
2. MySQL 写 learning_records
|
||
3. MySQL 更新 daily_learning_activities
|
||
4. Redis 可短期缓存今日活跃统计
|
||
5. App 查询活跃图时优先查 MySQL，必要时加缓存
|
||
```
|
||
|
||
---
|
||
|
||
# 九、v0.1 Redis 最小落地范围
|
||
|
||
第一版不用把所有 Redis 场景都做完。
|
||
|
||
建议先做：
|
||
|
||
```text
|
||
1. Redis 连接
|
||
2. /health 检查 Redis
|
||
3. RedisService
|
||
4. AI 每日调用限流
|
||
5. AI 分析队列
|
||
6. AI 分析任务状态
|
||
7. 防重复提交锁
|
||
8. document-import 队列预留
|
||
9. notification 队列预留
|
||
```
|
||
|
||
暂时不做：
|
||
|
||
```text
|
||
复杂缓存策略
|
||
Sorted Set 复习调度
|
||
复杂分布式任务调度
|
||
全量通知推送
|
||
复杂排行榜
|
||
```
|
||
|
||
---
|
||
|
||
# 十、给 Trae 的提示词
|
||
|
||
```text
|
||
请为「知习」api-server 设计并接入 Redis。
|
||
|
||
注意：
|
||
Redis 不需要像 MySQL 一样建表。
|
||
Redis 只用于缓存、限流、队列、临时状态、分布式锁、防重复提交和任务进度。
|
||
核心业务数据必须写入 MySQL，不能只存在 Redis。
|
||
|
||
请完成以下内容：
|
||
|
||
1. 基础接入
|
||
- docker-compose 增加 redis:7-alpine
|
||
- 增加 RedisModule
|
||
- 增加 RedisService
|
||
- 支持 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DB、REDIS_URL
|
||
- /health 检查 Redis 是否可用
|
||
|
||
2. RedisService 方法
|
||
- get
|
||
- set
|
||
- del
|
||
- exists
|
||
- expire
|
||
- ttl
|
||
- incr
|
||
- setNx
|
||
- lock
|
||
- unlock
|
||
|
||
3. Key 命名规范
|
||
请创建文档 docs/redis-key-design.md，包含以下 key 规范：
|
||
|
||
缓存：
|
||
cache:user:{userId}:profile
|
||
cache:user:{userId}:preferences
|
||
cache:user:{userId}:knowledge-bases
|
||
|
||
限流：
|
||
rate:user:{userId}:ai:daily:{date}
|
||
rate:ip:{ip}:request:{minute}
|
||
rate:user:{userId}:feedback:hourly
|
||
|
||
锁：
|
||
lock:ai-analysis:session:{sessionId}
|
||
lock:ai-analysis:answer:{answerId}
|
||
lock:document-import:{importId}
|
||
lock:review-plan:user:{userId}:item:{itemId}
|
||
|
||
任务状态：
|
||
job:ai-analysis:{jobId}:status
|
||
job:ai-analysis:{jobId}:progress
|
||
job:ai-analysis:{jobId}:error
|
||
job:document-import:{importId}:status
|
||
job:document-import:{importId}:progress
|
||
job:document-import:{importId}:message
|
||
job:document-import:{importId}:error
|
||
|
||
4. BullMQ 队列
|
||
请预留以下队列：
|
||
- ai-analysis
|
||
- document-import
|
||
- notification
|
||
|
||
5. AI 分析任务
|
||
请实现基础队列结构：
|
||
- 创建 AI 分析任务时写入 MySQL ai_analysis_jobs
|
||
- 添加任务到 Redis BullMQ 队列
|
||
- Redis 记录任务 status/progress
|
||
- Worker 处理完成后更新 MySQL
|
||
- Redis 更新状态为 completed
|
||
|
||
6. 限流
|
||
请实现基础 AI 调用限流：
|
||
rate:user:{userId}:ai:daily:{date}
|
||
用于限制用户每日 AI 分析调用次数。
|
||
|
||
7. 分布式锁
|
||
请实现 lock/unlock 工具，防止重复提交 AI 分析任务。
|
||
锁必须有 TTL。
|
||
解锁时要校验 token，不能误删其他请求的锁。
|
||
|
||
8. 注意事项
|
||
- 不要把用户、知识库、学习记录、AI 分析结果、待巩固项、复习计划只存 Redis
|
||
- Redis 中所有临时状态必须设置 TTL
|
||
- BullMQ 自动创建的 Redis key 不需要手动管理
|
||
- 代码要模块化，方便后续扩展
|
||
```
|
||
|
||
---
|
||
|
||
一句话总结：
|
||
|
||
**Redis 在知习里不是“另一个 MySQL”，它是系统的加速器和调度器。MySQL 存结果，Redis 管过程。**
|
||
|
||
[1]: file://my_files/file_00000000e760722fbb391fe031a23b24 "personal_developer_startup_plan.md"
|
||
[2]: file://my_files/file_00000000cbe0722fb8f20caa41630738 "Pasted text.txt"
|
||
[3]: file://my_files/file_0000000013c071fdbc2b510f32da8546 "Pasted text.txt"
|
||
[4]: file://my_files/file_00000000ffd071fd9492b93fd9ebf5ba "Pasted text.txt"
|
||
[5]: file://my_files/file_0000000061e471f590475885fd76860c "REAL_MIGRATION_STATUS.md"
|