Document Redis concurrency phase

ai_knowledge_base_v2/development_records/2026-07-08-concurrency-optimization-plan.md

@@ -338,3 +338,46 @@
 1. DB session 仍是同步的，权限范围、Prompt 读取、消息落库还没有切到 async DB。
 2. 当前缓存仍是进程内缓存，多 worker 下不会共享缓存。
 3. 飞书直读并发上限是代码内默认值，后续可在系统配置中开放。
+
+## 阶段 4 实施计划
+
+目标：引入 Redis，让多 worker / 多实例部署时可以共享问答排队状态和飞书读取缓存。
+
+阶段 4 分两步实施：
+
+1. 阶段 4A：Redis 全局问答队列。
+2. 阶段 4B：Redis 飞书共享缓存。
+
+### 阶段 4A：Redis 全局问答队列
+
+实施范围：
+
+1. 增加 Redis 依赖和 `REDIS_URL` 配置。
+2. dev compose 增加 Redis 服务，后端通过 `redis://redis:6379/0` 连接。
+3. 新增 Redis 队列管理器，使用 Redis 记录：
+   - 当前正在生成的请求 token。
+   - 等待队列 token。
+   - active token 的过期时间，避免 worker 崩溃后 active 计数永久泄漏。
+4. `/chat/completions` 优先使用 Redis 队列；Redis 不可用时自动回退进程内队列。
+5. SSE 事件协议保持不变，用户端无需改动。
+
+风险控制：
+
+1. Redis 队列必须保留进程内回退，避免 Redis 临时不可用时问答完全不可用。
+2. active token 必须带 TTL；请求异常、客户端断开、worker 崩溃都不能让队列永久卡死。
+3. 不修改已有 5 个未提交后端文件。
+
+### 阶段 4B：Redis 飞书共享缓存
+
+实施范围：
+
+1. 飞书 tenant token、wiki node info、children、docx/file 文本内容接入 Redis 缓存。
+2. 缓存 key 按应用凭证和资源 token 隔离。
+3. Redis 不可用时自动回退进程内缓存。
+4. 保留当前 5 分钟缓存 TTL，后续可在系统设置中开放。
+
+风险控制：
+
+1. 不改变知识库召回排序和 Prompt 构建。
+2. 不缓存用户问题、模型回答和用户隐私信息。
+3. 不把飞书读取失败结果长时间缓存，避免权限/配置修复后仍命中错误缓存。