LangGraph崩溃恢复重放任务：SQLite原子提交实测

LangGraph 的持久化执行（durable execution）让工作流可以在崩溃后恢复，但恢复时未完成的任务会被重新执行——这是设计使然，还是隐藏的陷阱？一位开发者在 Reddit 上分享了一个可运行的崩溃测试，用 SQLite 作为轻量级接收端，精确复现了任务在数据库写入提交后因进程终止而重放的现象，并对比了三种事务模式下的不同结果。

测试设计：让进程在提交后立即死亡

整个实验不涉及任何模型或外部服务。一个计数器任务接收操作 ID（operation_id），在 SQLite 中执行「先检查去重表，若未见过则递增计数器，再记录去重键」的逻辑。测试者故意在「计数器递增已提交、任务尚未返回」的时间窗口内调用 os._exit(91) 终止进程，随后用 invoke(None, config) 恢复同一个线程。

测试环境被精确锁定：Python 3.14.7、LangGraph 1.2.20、langgraph-checkpoint-sqlite 3.1.3、langgraph-checkpoint 4.3.1、langchain-core 1.7.6 和 SQLite 3.53.4。每个模式都从计数器为零开始，恢复后读取最终值。代码中三种模式（split、atomic、fresh）的差异仅在于事务边界和操作 ID 的生成时机。

os._exit(91) 与常见的 sys.exit() 有本质区别：前者直接触发操作系统级别的进程终止，不执行任何 Python 清理逻辑——包括 finally 块、atexit 回调、缓冲区刷新以及上下文管理器的 __exit__ 方法。这正是该测试选择它的原因：要模拟「任务已产生副作用但尚未返回」这一崩溃窗口，必须确保进程在 LangGraph 有机会将节点标记为完成之前就已死亡。如果用 sys.exit()，LangGraph 的异常处理路径可能捕获退出信号并写入失败状态，从而掩盖重放行为。此外，退出码 91 是测试者刻意选用的非标准值，便于在日志或 shell 中区分这次人为终止与真实的运行时错误。理解这一点，才能明白测试所复现的是「硬崩溃」而非「优雅失败」，后者在 LangGraph 中走的是另一条恢复语义。

三种模式，三种结局

split 模式：计数器递增和去重记录分两次独立事务提交。第一次提交后进程退出，恢复时去重表里还没有记录，于是任务再次递增。最终计数器为 2。

atomic 模式：计数器递增与去重记录在同一个事务中提交。恢复时去重记录已存在，但任务本身仍然被重新执行——只是这次执行发现操作 ID 已被处理，跳过了递增。最终计数器为 1。

fresh 模式：两次写入共享事务，但恢复时任务内部使用 uuid4().hex 生成了全新的操作 ID。去重机制完全失效，计数器再次递增，最终为 2。

你可能没注意到，三种模式的调用日志（calls.log）都记录了两条条目。去重改变的是接收端的效果，而不是阻止任务运行两次。

「至少一次」（at-least-once）与「恰好一次」（exactly-once）是分布式系统中两种典型的消息/任务投递语义。前者保证任务至少被执行一次，但在故障恢复时可能重复；后者保证有且仅有一次，但通常需要分布式事务或两阶段提交等重量级机制。LangGraph 的持久化执行属于前者：检查点（checkpoint）记录的是「任务已开始」而非「任务已提交」，因此崩溃后未标记完成的任务必然重放。要在此基础上逼近「恰好一次」的效果，通行做法是让接收端具备幂等性——即同一操作 ID 的重复执行不产生额外副作用。这正是测试中 SQLite 去重表所扮演的角色。需要强调的是，幂等性不是执行框架提供的保证，而是开发者必须在副作用端自行构造的属性；框架只负责「至少一次」，收敛到「一次」的责任在业务代码。

核心洞察：单操作的 ID 不能撑起多写工作流

对于这个只有一个动作的工作流，持久化的输入携带了操作 ID，使它能够在恢复时被识别。但测试者指出，一个包含多个写入动作的工作流需要为每个逻辑动作分配独立的 ID，而不是为整个线程使用一个去重键。否则，恢复时要么重复执行，要么错误地跳过后续动作。

另一个容易被忽略的边界是：这个测试验证的是本地进程终止与重启，不覆盖断电或 HTTP 接收端。外部 API 需要自己的幂等性契约——把 HTTP 调用塞进 SQLite 事务里，并不能获得数据库的回滚行为。LangGraph 的幂等性指南解释了为什么未完成的任务会再次运行，而 SQLite 的事务文档则界定了本地写入的边界。

幂等键（idempotency key）的粒度设计是幂等接收端能否正确工作的关键。粒度太粗——例如整个工作流线程共用一个键——会导致恢复时第一个动作已处理、后续动作被错误跳过；粒度太细——例如每次重试都生成新键——则去重完全失效，正如 fresh 模式所演示的。合理的设计是为每个「逻辑动作」分配稳定且唯一的 ID，该 ID 在任务重放时必须保持不变，通常由工作流的输入参数或上游节点确定性派生，而非在节点内部随机生成。这与 Stripe 等支付 API 的幂等键实践一致：客户端为每次业务意图生成一个键，重试时复用同一个键，服务端据此识别重复请求。在多写工作流中，这意味着节点需要维护一个动作清单，并为清单中的每一项携带独立的幂等键。

对开发者的实际启示

这个可复现的测试提醒我们，LangGraph 的「持久化执行」不等于「恰好一次执行」。它的语义更接近「至少一次」，配合幂等接收端才能收敛到期望效果。在设计带副作用的节点时，需要显式考虑：副作用是否可重入、去重键的粒度是否与逻辑动作对齐、事务边界是否覆盖了所有相关写入。

测试代码已在本地实际执行，作者也注明这是一篇 AI 辅助撰写的文章。对于想要复现的读者，只需一个干净的 Python 环境，安装上述固定版本依赖，将代码保存为 demo.py，分别以 start 和 resume 参数运行即可观察三种模式的行为差异。

LangGraph 的检查点（checkpoint）机制是其持久化执行的基础：每次节点执行前后，框架会将线程状态序列化写入 checkpointer（本测试中为 SQLite）。恢复时，框架从最后一个检查点重建状态并重新调度未完成的节点。关键点在于，检查点的写入时机与节点内部副作用的提交时机是解耦的——节点可能已经完成了数据库写入，但检查点尚未记录该节点完成，于是恢复时节点被重新调度。这种解耦是性能与可靠性的权衡：若要求检查点与副作用原子提交，就需要引入分布式事务，代价高昂。因此 LangGraph 选择了「至少一次」语义，并把幂等性的责任交给开发者。理解检查点与副作用的这种时序关系，是设计可靠工作流的前提。