聊天代理持久化
David-Li04062026-10-25查看 1734复制 632
Chat 服务持久化层指南。Checkpointer（多轮上下文）、Message Persistence（PostgreSQL）、Redis Streams Consumer 架构及故障排查。使用场景：(1) chat.messages 表为空时，(2) 发生 checkpointer 相关错误时，(3) 多轮对话上下文无法保持时，(4) 配置 Redis Streams consumer group 时。
📘如何使用这个技能
- 1复制技能内容·点击上方「Copy SKILL.md」复制全部内容，或 Download 下载到本地
- 2打开你的 AI 客户端·支持 Claude Code、Trae、Cursor、ChatGPT、DeepSeek、Kimi 等任意 AI 助手
- 3粘贴为系统提示/知识文件·Claude Code：放入 .claude/skills/ 目录；普通对话：作为首条消息发送并说「请严格按这份技能文档执行」
- 4直接提出你的需求·AI 会按技能定义的工作流、格式和约束来处理，无需再解释背景
💡 提示：技能生效后，每次对话只需一句需求，AI 会按 SKILL.md 的流程执行。
SKILL.md6060 chars
---
name: chat-agent-persistence
description: Chat 서비스의 영속화 레이어 가이드. Checkpointer(멀티턴 컨텍스트), Message Persistence(PostgreSQL), Redis Streams Consumer 아키텍처 및 트러블슈팅. Use when: (1) chat.messages 테이블이 비어있을 때, (2) checkpointer 관련 에러 발생 시, (3) 멀티턴 대화 컨텍스트가 유지되지 않을 때, (4) Redis Streams consumer group 설정 시.
---
# Chat Agent Persistence Guide
> Chat 서비스의 데이터 영속화 레이어 (Checkpointer + Message Storage)
## Architecture Overview
```
┌───────────────────────────────────────────────────────────────────────────┐
│ Chat Persistence Architecture │
├───────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ chat-worker │ │
│ │ (LangGraph) │ │
│ └──────┬──────┘ │
│ │ │
│ ┌────┴────┐ │
│ │ │ │
│ ▼ ▼ │
│ Checkpointer Progress Events │
│ (Multi-turn) (Stage updates) │
│ │ │ │
│ │ │ XADD │
│ ▼ ▼ │
│ ┌────────────┐ ┌──────────────────┐ │
│ │ PostgreSQL │ │ Redis Streams │ │
│ │checkpoints │ │ chat:events:{0-3}│ │
│ └────────────┘ └────────┬─────────┘ │
│ │ │
│ ┌────────────┼────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐ │
│ │ eventrouter │ │chat-persist │ │ (other groups) │ │
│ │ (group) │ │ (group) │ │ │ │
│ └──────┬──────┘ └──────┬──────┘ └──────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │event-router │ │chat-consumer │ │
│ │ (SSE fan) │ │ (DB write) │ │
│ └─────────────┘ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ PostgreSQL │ │
│ │chat.messages │ │
│ └──────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────────┘
```
## Two Persistence Paths
| Path | Purpose | Component | Target |
|------|---------|-----------|--------|
| **Checkpointer** | 멀티턴 컨텍스트 (LangGraph state) | CachedPostgresSaver | checkpoints 테이블 |
| **Message Storage** | 대화 이력 (user/assistant) | ChatPersistenceConsumer | chat.messages 테이블 |
## Quick Diagnosis
```bash
# 1. chat.messages 테이블 확인
kubectl exec -n postgres deploy/postgresql -- psql -U sesacthon -d ecoeco -c \
"SELECT COUNT(*) FROM chat.messages;"
# 2. Checkpointer 상태 확인 (worker 로그)
kubectl logs -n chat deploy/chat-worker --tail=100 | grep -E "(CachedPostgresSaver|checkpointer|InMemory)"
# 3. Redis Streams consumer group 확인
kubectl exec -n redis rfr-streams-redis-0 -c redis -- redis-cli XINFO GROUPS chat:events:0
```
## Common Issues
### Issue 1: CachedPostgresSaver 초기화 실패
**증상**: `InMemory checkpointer created (Redis fallback disabled)`
**로그**:
```
[WARNING] CachedPostgresSaver failed, falling back to Redis only:
object _AsyncGeneratorContextManager can't be used in 'await' expression
```
**원인**: `checkpointer.py:228`에서 async context manager를 `await`로 호출
**상세**: See [checkpointer.md](references/checkpointer.md)
### Issue 2: chat.messages 테이블 비어있음
**증상**: `chat.conversations`에 데이터 있지만 `chat.messages`는 0건
**진단**:
```bash
# Consumer group 확인 - "chat-persistence" 없으면 미배포
kubectl exec -n redis rfr-streams-redis-0 -c redis -- redis-cli XINFO GROUPS chat:events:0
```
**원인**: ChatPersistenceConsumer 미배포
**상세**: See [message-consumer.md](references/message-consumer.md)
## Code Locations
| Component | Path |
|-----------|------|
| Checkpointer | `apps/chat_worker/infrastructure/orchestration/langgraph/checkpointer.py` |
| Dependencies | `apps/chat_worker/setup/dependencies.py` (Lines 641-678) |
| Consumer Entry | `apps/chat/consumer.py` |
| Consumer Infra | `apps/chat/infrastructure/messaging/redis_streams_consumer.py` |
| Consumer Adapter | `apps/chat/presentation/consumer/redis_streams_adapter.py` |
## Reference Files
- **Checkpointer 상세**: See [checkpointer.md](references/checkpointer.md) - Cache-Aside 패턴, LangGraph API
- **Message Consumer 상세**: See [message-consumer.md](references/message-consumer.md) - 배포 방법, Consumer Group
- **트러블슈팅 문서**: `docs/troubleshooting/chat-messages-not-persisted.md`
- **PostgreSQL 분석**: `docs/reports/postgres-chat-data-analysis.md`