# SQLite 出箱模式 + WAL 持久化任务队列：Exactly-Once 事件消费与崩溃恢复 > 用 SQLite Outbox Pattern + WAL 构建耐崩溃任务队列，实现 exactly-once 事件流消费，集成 Debezium CDC 管道。给出 schema、PRAGMA 配置与监控参数。 ## 元数据 - 路径: /posts/2025/11/22/sqlite-outbox-wal-durable-queue-debezium-cdc/ - 发布时间: 2025-11-22T15:05:17+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 站点: https://blog.hotdry.top ## 正文 在分布式系统中，实现 durable execution（持久化执行）常需复杂引擎如 Temporal 或 Cadence，但对于中小规模任务队列，SQLite 的 Outbox Pattern 结合 WAL（Write-Ahead Logging）模式提供廉价、高可靠方案。该模式将业务变更与事件写入同一事务的 outbox 表，利用 WAL 持久化确保崩溃恢复，并通过 Debezium CDC 无缝流式投递到 Kafka，实现 exactly-once 语义。 ### Outbox Pattern 在 SQLite 中的核心设计 Outbox Pattern 解决“双写不一致”问题：业务服务在本地事务中同时写入业务表和 outbox 表，后者存储待发布事件。SQLite 天然支持此模式，因其 ACID 事务保证原子性。 典型 outbox 表 schema： ```sql CREATE TABLE IF NOT EXISTS outbox_events ( id INTEGER PRIMARY KEY AUTOINCREMENT, aggregate_type TEXT NOT NULL, aggregate_id TEXT NOT NULL, event_type TEXT NOT NULL, payload JSON NOT NULL, -- 事件负载，序列化为 JSON created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, processed_at TIMESTAMP NULL ); CREATE INDEX idx_outbox_aggregate ON outbox_events(aggregate_type, aggregate_id); CREATE INDEX idx_outbox_created ON outbox_events(created_at); ``` 业务事务示例（伪代码）： ```sql BEGIN TRANSACTION; -- 业务变更，如订单创建 INSERT INTO orders (id, status) VALUES ('order-123', 'created'); -- 写入 outbox INSERT INTO outbox_events (aggregate_type, aggregate_id, event_type, payload) VALUES ('Order', 'order-123', 'OrderCreated', '{"id": "order-123", "status": "created"}'); COMMIT; ``` 崩溃时，事务回滚确保业务与事件一致；成功提交后，事件持久化在 outbox。 ### WAL 模式：持久化与并发保障 默认 rollback journal 下，SQLite 写阻塞读，不适高并发任务队列。启用 WAL 模式（PRAGMA journal_mode=WAL;）将变更追加到 -wal 文件，支持读写并发：读从主文件 + wal 合并，写仅追加 wal。 关键 PRAGMA 配置： - `PRAGMA journal_mode = WAL;` // 启用 WAL - `PRAGMA synchronous = NORMAL;` // 平衡耐久性与性能，崩溃可能丢最近事务 - `PRAGMA wal_autocheckpoint = 1000;` // wal 文件达 1000 页（默认 ~1MB）自动 checkpoint - `PRAGMA busy_timeout = 5000;` // 锁冲突等待 5s - `PRAGMA cache_size = 10000;` // 增大缓存，提升吞吐 WAL 确保耐崩溃：wal 文件 fsync 后事务持久，重启自动 replay 未 checkpoint 变更。测试显示，WAL 下写吞吐提升 2-4 倍，读写并发无阻塞。 Checkpoint 机制： - 被动：wal 满时当前 COMMIT 线程执行。 - 主动：闲时调用 `PRAGMA wal_checkpoint(FULL);`，回写 wal 到主文件，truncate wal。 监控 wal 文件大小（<100MB），若过大，手动 FULL checkpoint。 ### Debezium CDC：Exactly-Once 事件流消费 轮询 outbox 易积压、延迟高。集成 Debezium（支持 SQLite connector）捕获 outbox 变更，实时流式投递到 Kafka。 Debezium SQLite connector 配置（docker-compose 示例）： ```yaml debezium: image: debezium/connect:2.5 depends_on: [kafka, sqlite-db] environment: BOOTSTRAP_SERVERS: kafka:9092 GROUP_ID: 1 CONFIG_STORAGE_TOPIC: dbserver1-config OFFSET_STORAGE_TOPIC: dbserver1-offset STATUS_STORAGE_TOPIC: dbserver1-status command: ["connect-standalone", "/etc/kafka-connect-sqlite.properties"] ``` kafka-connect-sqlite.properties： ``` connector.class=io.debezium.connector.sqlite.SqliteConnector database.hostname=sqlite-db database.path=/var/lib/sqlite/tasks.db database.history.kafka.bootstrap.servers=kafka:9092 database.history.kafka.topic=dbhistory.tasks table.include.list=outbox_events transforms=unwrap transforms.unwrap.type=io.debezium.transforms.ExtractNewRecordState transforms.unwrap.drop.tombstones=true ``` Debezium 订阅 binlog/wal，捕获 INSERT 到 outbox，转换为 Kafka 事件。消费端 Kafka Streams/消费者处理后，更新 processed_at（幂等）。 Exactly-Once：Debezium 事务边界 + Kafka exactly-once + 消费幂等（unique aggregate_id）。 ### Crash 恢复与监控参数 崩溃恢复流程： 1. SQLite 重启：自动从 wal replay 未 checkpoint 事务。 2. Debezium 重连：从 offset 恢复，replay outbox 变更。 3. 任务队列：未 processed 事件重发，确保不丢。 落地参数清单： - **吞吐阈值**：SQLite WAL 适 <1k TPS，高吞吐迁 Postgres。 - **Checkpoint 频率**：每 5min 或 wal>50MB 执行 FULL。 - **监控指标**： | 指标 | 阈值 | 告警 | |------|------|------| | wal 文件大小 | <100MB | >200MB | | Checkpoint 滞后 | <1h | >2h | | Outbox 未处理数 | <1k | >10k | | Debezium 滞后 | <10s | >1min | 回滚策略：若 wal 膨胀，`PRAGMA journal_mode=DELETE;` 切换回默认。 ### 实战风险与优化 风险：SQLite 单写者锁，wal 共享内存限单机；Debezium SQLite connector 实验性，生产慎用（fallback 轮询 publisher）。 优化：分区 outbox（按 aggregate_type），结合 Watermill 等库简化 pub/sub。 此方案成本低、无运维，适 edge computing 或单机 durable queue。 **资料来源**： - Gunnar Morling: Building a Durable Execution Engine With SQLite (morling.dev) - Debezium SQLite Connector Docs - SQLite WAL Mode (sqlite.org/wal.html) ## 同分类近期文章 ### [Apache Arrow 10 周年：剖析 mmap 与 SIMD 融合的向量化 I/O 工程流水线](/posts/2026/02/13/apache-arrow-mmap-simd-vectorized-io-pipeline/) - 日期: 2026-02-13T15:01:04+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 深入分析 Apache Arrow 列式格式如何与操作系统内存映射及 SIMD 指令集协同，构建零拷贝、硬件加速的高性能数据流水线，并给出关键工程参数与监控要点。 ### [Stripe维护系统工程：自动化流程、零停机部署与健康监控体系](/posts/2026/01/21/stripe-maintenance-systems-engineering-automation-zero-downtime/) - 日期: 2026-01-21T08:46:58+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 深入分析Stripe维护系统工程实践，聚焦自动化维护流程、零停机部署策略与ML驱动的系统健康度监控体系的设计与实现。 ### [基于参数化设计和拓扑优化的3D打印人体工程学工作站定制](/posts/2026/01/20/parametric-ergonomic-3d-printing-design-workflow/) - 日期: 2026-01-20T23:46:42+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 通过OpenSCAD参数化设计、BOSL2库燕尾榫连接和拓扑优化，实现个性化人体工程学3D打印工作站的轻量化与结构强度平衡。 ### [TSMC产能分配算法解析：构建半导体制造资源调度模型与优先级队列实现](/posts/2026/01/15/tsmc-capacity-allocation-algorithm-resource-scheduling-model-priority-queue-implementation/) - 日期: 2026-01-15T23:16:27+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 深入分析TSMC产能分配策略，构建基于强化学习的半导体制造资源调度模型，实现多目标优化的优先级队列算法，提供可落地的工程参数与监控要点。 ### [SparkFun供应链重构：BOM自动化与供应商评估框架](/posts/2026/01/15/sparkfun-supply-chain-reconstruction-bom-automation-framework/) - 日期: 2026-01-15T08:17:16+08:00 - 分类: [systems-engineering](/categories/systems-engineering/) - 摘要: 分析SparkFun终止与Adafruit合作后的硬件供应链重构工程挑战，包括BOM自动化管理、替代供应商评估框架、元器件兼容性验证流水线设计