---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - study
  - langchain
  - python
  - integrations
  - checkpointer
  - langgraph
topic: LangGraph Checkpointer 线程状态持久化与恢复
sources:
  - https://docs.langchain.com/oss/python/integrations/checkpointers
  - https://docs.langchain.com/oss/python/integrations/checkpointers/index
last_verified: 2026-08-11
---
# Checkpointers：线程状态与恢复

## 定位

Checkpointer 保存 LangGraph thread 的执行状态，让 agent 跨交互恢复。它用于短期线程状态、interrupt/resume 和故障恢复，不等同于跨 thread 的 long-term memory，也不等同于只存消息的 chat history。

`/checkpointers` 与 `/checkpointers/index` 当前同正文，列出：

| 后端 | 包 |
|---|---|
| In-memory | `langgraph-checkpoint` |
| SQLite | `langgraph-checkpoint-sqlite` |
| PostgreSQL | `langgraph-checkpoint-postgres` |
| AWS DynamoDB/Bedrock/Valkey | `langgraph-checkpoint-aws` |
| MongoDB | `langgraph-checkpoint-mongodb` |
| Azure Cosmos DB NoSQL | `langchain-azure-cosmosdb` |
| Redis | `langgraph-checkpoint-redis` |
| CockroachDB | `langchain-cockroachdb` |
| Aerospike | `langgraph-checkpoint-aerospike` |
| ScyllaDB | `langgraph-checkpoint-scylladb` |
| Tigris | `langgraph-checkpoint-tigris` |
| TypeDB | `langgraph-checkpoint-typedb` |
| Inspeximus | `langgraph-checkpoint-inspeximus` |
| Supabase | `langgraph-checkpoint-supabase` |

本页是后端索引，不给出各包的 setup、schema、sync/async、transaction 或 TTL 细节。实现时必须按锁定包的 Reference/README 核对，不能从列表推断等价保证。

## 生产契约

- `thread_id`、checkpoint namespace 和 authenticated tenant 必须由服务端绑定；模型或客户端不能用任意 ID 读取别人的状态。
- checkpoint 写入与外部 tool side effect 不是天然同一事务。恢复后可能再次执行工具，所有副作用工具需要幂等键、outbox 或显式 completion marker。
- state schema、serializer 和 reducer 变化属于数据 migration；发布前验证旧 checkpoint 可读、回滚版本可恢复。
- In-memory 只适合测试；生产后端配置连接池、超时、重试、加密、备份、恢复和容量/TTL。
- HITL pause 可能持续很久，保留期不能短于最大审批窗口；删除 thread 时同步清理 checkpoint、artifact 和审计引用。

## 故障测试

至少覆盖 node 执行前/后崩溃、checkpoint 写成功但响应丢失、外部动作成功但 checkpoint 失败、重复 resume、并发同 thread、过期、schema upgrade 和后端 failover。最终验证的是“恢复后状态与副作用一致”，不只是数据库存在一行记录。

## 验证边界

已验证两个官方路由及当前后端/包清单；没有逐个运行 14 个后端，因此它们的事务、一致性、async 和运维能力均未被本笔记确认。