1. Redis 是什么

Redis 本质上是一个：

内存型键值数据库（in-memory key-value store）

特点：

非常快
适合频繁读写
支持多种数据结构
可以做缓存、会话状态、队列、锁、计数器
可以选择持久化到磁盘

你不要把它理解成 MySQL/Postgres 那种“长期主数据库”。对你的系统来说，它更像：

实时状态中心 + 高速缓存层

在 report kit 这种三层记忆设计中，Redis 最适合做：

A. Layer 3 Working Memory 的运行时主存

比如：

recent_messages_summary

active_files

current_plan

pending_tasks

toolcall_results

pending_errors

这些更新频繁，很适合 Redis。

B. 分布式锁

比如：

防止同一个 conversation_id 被两个 worker 同时改文件

防止同一个任务被重复执行

C. 任务状态缓存

比如前端轮询：

当前任务是 queued/running/success/failed

D. 短期缓存

比如：

最近一次 RAG 检索结果

最近生成的 prompt 片段

文件解析摘要缓存

E. 可选：消息队列 / job broker

后面如果你用 Celery / RQ / Dramatiq，Redis 还可以做 broker。

2. Redis 的基本使用逻辑

Redis 最核心的思维方式是：

你往 Redis 里放一个 key，对应一个 value。

例如：

working:conv_123:state

对应的 value 可以是：

字符串
JSON 字符串
哈希（hash）
列表（list）
集合（set）
有序集合（zset）

对你这种系统，最常用的是：

string
hash
偶尔 list
偶尔 set

3. 安装 Redis

如果你在 Ubuntu 上，最简单。

Ubuntu 安装

sudo apt update
sudo apt install redis-server -y

安装后检查版本：

redis-server --version

检查客户端：

redis-cli --version

macOS 安装

如果你用 Homebrew：

brew install redis

启动：

brew services start redis

Docker 安装

docker run -d \
  --name redis \
  -p 6379:6379 \
  redis:7

如果你要持久化：

docker run -d \
  --name redis \
  -p 6379:6379 \
  -v redis_data:/data \
  redis:7 \
  redis-server --appendonly yes

4. Redis 配置文件

Ubuntu 安装后，主配置文件通常在：

/etc/redis/redis.conf

你可以用 vim 打开：

sudo vim /etc/redis/redis.conf

6. Redis 关键配置项

先讲你最需要关心的。

6.1 bind

控制 Redis 监听哪些地址。

默认一般是：

bind 127.0.0.1 ::1

意思是：

只允许本机连接

这对单机部署很安全。

如果你不是很明确要远程访问，不要改成 0.0.0.0。

6.2 protected-mode

建议保持：

protected-mode yes

这样更安全。

6.3 port

默认：

port 6379

一般不用改。

6.4 requirepass

如果 Redis 需要外部访问，建议设置密码：

requirepass your_strong_password

单机本地开发可以先不设，但生产建议设。

6.5 appendonly

这个很重要，在第1379 行。Redis 默认是内存数据库，如果崩了，数据可能丢。

建议你对 Layer 3 至少开启 AOF：

appendonly yes

这表示：Redis 会把写操作追加记录到磁盘

6.6 dir

Redis 持久化文件保存位置：

dir /var/lib/redis

一般保持默认即可。

6.7 maxmemory

如果你不想 Redis 把机器内存吃满，可以设：

maxmemory 2gb

6.8 maxmemory-policy

当达到内存上限时怎么办。

比较常见：

maxmemory-policy allkeys-lru

或

maxmemory-policy volatile-lru

对于你的系统，如果很多 key 有过期时间，volatile-lru 很常见。如果很多 key 没设过期，allkeys-lru 更直接。

7. 启动和重启 Redis

Ubuntu 上：

sudo systemctl start redis-server
sudo systemctl status redis-server

重启：

sudo systemctl restart redis-server

开机自启：

sudo systemctl enable redis-server

8. 测试 Redis 是否正常

进入命令行：

redis-cli

然后输入：

ping

正常会返回：

PONG

退出：

exit

如果设置了密码：

redis-cli -a your_strong_password

9. Redis 最基础的数据结构与命令

这是你必须会的。

9.1 String

最简单。

设置：

SET name "hello"

读取：

GET name

删除：

DEL name

设置带过期时间：

SET session:123 "active" EX 3600

意思：

1 小时后自动过期

这在你的系统里非常有用。

9.2 Hash

适合存“一个对象的多个字段”。

例如一个对话的 working state：

HSET working:conv_123 recent_messages_summary "用户上传了三个文件"
HSET working:conv_123 toolcall_results "CSV parsed successfully"

读取一个字段：

HGET working:conv_123 recent_messages_summary

读取全部字段：

HGETALL working:conv_123

这很适合 Layer 3。

9.3 List

适合当队列或日志流。

压入：

LPUSH task_queue "task_001"

取出：

RPOP task_queue

如果你以后做简单任务队列，可能用得到。

9.4 Set

适合去重集合。

SADD active_conversations conv_1
SADD active_conversations conv_2
SMEMBERS active_conversations

9.5 TTL / Expire

设置过期：

EXPIRE working:conv_123 3600

查看剩余过期时间：

TTL working:conv_123

10. 对你最重要的 Redis 使用方式

你这个项目里，最推荐用 Hash 或一个 JSON String 来存 Layer 3。

我建议一开始用 一个 JSON String，简单清晰。

例如 key：

working:conv_123:state

value：

{
  "recent_messages_summary": "用户上传了 lab manual、csv 和 template",
  "active_files": ["lab_manual.pdf", "data.csv", "template.tex"],
  "current_plan": [
    "Parse uploaded files",
    "Analyze csv",
    "Draft report.tex"
  ],
  "pending_tasks": [
    "generate figures",
    "compile latex"
  ],
  "toolcall_results": "CSV parsed successfully",
  "pending_errors": [],
  "updated_at": "2026-03-18T20:00:00Z"
}

然后整块读写。

优点：

简单
和 Python/FastAPI 配合方便
不容易字段散乱

11. 你项目里的推荐 key 命名规则

一定要统一命名，不然后面会乱。

我建议：

Working state

working:{conversation_id}:state

任务状态

task:{task_id}:status

对话锁

lock:conversation:{conversation_id}

用户限流

rate:user:{user_id}

12. Python 里怎么用 Redis

你用 FastAPI，推荐 Python 包：

pip install redis

如果你要异步 FastAPI，建议直接用新版 redis 包里的 asyncio 接口。

同步示例

import redis
import json

r = redis.Redis(host="localhost", port=6379, decode_responses=True)

state = {
    "recent_messages_summary": "用户上传了文件",
    "active_files": ["a.pdf", "b.csv"],
    "current_plan": ["parse files", "write draft"],
    "pending_tasks": ["compile report"],
    "toolcall_results": "none",
    "pending_errors": [],
}

r.set("working:conv_123:state", json.dumps(state), ex=3600)

raw = r.get("working:conv_123:state")
loaded = json.loads(raw)
print(loaded)

FastAPI 中推荐异步写法

pip install redis
from redis.asyncio import Redis
import json

redis_client = Redis(host="localhost", port=6379, decode_responses=True)

async def save_working_state(conversation_id: str, state: dict):
    key = f"working:{conversation_id}:state"
    await redis_client.set(key, json.dumps(state), ex=3600)

async def load_working_state(conversation_id: str):
    key = f"working:{conversation_id}:state"
    raw = await redis_client.get(key)
    if not raw:
        return None
    return json.loads(raw)

13. Redis 在你系统中的典型流程

比如用户发来一条消息：

Step 1

FastAPI 收到请求

Step 2

先查 Redis：

working:{conversation_id}:state

有就恢复当前 Layer 3

Step 3

没有就去 Postgres 查 working_state

Step 4

处理本轮消息，更新：

recent_messages_summary
active_files
current_plan
pending_tasks
toolcall_results
pending_errors

Step 5

新状态写回 Redis

Step 6

同时按关键时机写回 Postgres 快照

这就是你 Layer 3 的标准逻辑。

14. Redis 锁怎么用

你的系统很需要“同一个 conversation 不能同时被两个任务乱改”。

Redis 可以做简单锁。

Python 例子：

from redis.asyncio import Redis

redis_client = Redis(host="localhost", port=6379, decode_responses=True)

async def acquire_conversation_lock(conversation_id: str):
    key = f"lock:conversation:{conversation_id}"
    return await redis_client.set(key, "1", ex=60, nx=True)

async def release_conversation_lock(conversation_id: str):
    key = f"lock:conversation:{conversation_id}"
    await redis_client.delete(key)

这里：

nx=True 表示只有 key 不存在时才设置成功
ex=60 表示 60 秒自动过期，防止死锁

15. 持久化：为什么 Redis 不能只靠内存

如果你只用内存：

服务器重启
Redis 崩溃
容器重建

Layer 3 就没了。

所以建议：

开启 AOF

在 redis.conf 中：

appendonly yes

这样 Redis 会记录写操作。

但即使这样，Redis 也不应该是唯一真相来源。

对于你系统：

Redis = 运行时主存 Postgres = 持久快照兜底

这点一定要记住。

16. Docker 里跑 Redis 的推荐方式

如果你后面生产用 Docker Compose，很适合这样：

services:
  redis:
    image: redis:7
    container_name: redis
    command: ["redis-server", "--appendonly", "yes"]
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  redis_data:

这样：

Redis 服务在容器里
AOF 数据在 volume 里
删容器不丢数据

17. 你这个项目的 Redis 最小配置建议

如果是开发/内测，我建议：

本机监听即可
开启 AOF
先不暴露公网
maxmemory 先不设太死
用 JSON string 保存 working:{conversation_id}:state

如果是小规模生产：

bind 127.0.0.1
用 Nginx/FastAPI 间接访问，不要公网暴露 Redis
开启密码
开启 AOF
挂持久卷
做每日备份

18. Redis 和 Postgres 的职责边界

这是你后面最容易混淆的地方。

Redis 负责

快
当前状态
锁
短期缓存
临时队列

Postgres 负责

真正持久化
用户信息
conversation 元数据
Layer 1 / 2 持久记忆
Layer 3 快照
文件/任务/artifact 记录

一句话：

Redis 是“高速工作台”，Postgres 是“正式档案馆”。

19. 你现在需要先学会的最小命令集

先把这几个练熟：

redis-cli
PING
SET test "hello"
GET test
DEL test
HSET myhash field1 "value1"
HGET myhash field1
HGETALL myhash
EXPIRE test 60
TTL test

如果这些都懂了，Redis 基本入门就够了。

A. Layer 3 Working Memory 的运行时主存​

B. 分布式锁​

C. 任务状态缓存​

D. 短期缓存​

E. 可选：消息队列 / job broker​

2. Redis 的基本使用逻辑

3. 安装 Redis

Ubuntu 安装​

macOS 安装​

Docker 安装​

4. Redis 配置文件

6. Redis 关键配置项

6.1 bind​

6.2 protected-mode​

6.3 port​

6.4 requirepass​

6.5 appendonly​

6.6 dir​

6.7 maxmemory​

6.8 maxmemory-policy​

7. 启动和重启 Redis

8. 测试 Redis 是否正常

9. Redis 最基础的数据结构与命令

9.1 String​

9.2 Hash​

9.3 List​

9.4 Set​

9.5 TTL / Expire​

10. 对你最重要的 Redis 使用方式

11. 你项目里的推荐 key 命名规则

Working state​

任务状态​

对话锁​

用户限流​

最近检索缓存​

12. Python 里怎么用 Redis

同步示例​

FastAPI 中推荐异步写法​