SQLite与CockroachDB如何实现全局一致性？分布式数据同步实战详解

把SQLite当作边缘节点的本地存储，再把数据汇聚到CockroachDB做全局查询和分析，这种架构在物联网、零售门店、移动端数据回传等场景里非常常见。难点在于：SQLite是单机嵌入式数据库，天生没有分布式协调能力，而CockroachDB虽然支持强一致的分布式事务，但它无法主动感知SQLite里的数据变化。两套系统之间怎么保证数据不丢、不乱序、不冲突，就是这篇文章要解决的核心问题。

一、整体同步架构的设计思路

这个项目的背景是一家连锁零售企业，每个门店有一台离线可用的本地收银终端，数据先落在终端的SQLite里，网络恢复后再同步到部署在云端的CockroachDB集群。早期版本的实现是直接整表上传，用时间戳做覆盖，结果一旦两个门店同时修改同一件商品的库存，就会出现后写入的数据把先写入的数据冲掉的尴尬情况。

重新设计时，我们把同步链路拆成了三层：变更捕获层负责从SQLite里拿到增量数据，传输层负责打包、排序和断点续传，应用层在CockroachDB侧做冲突检测和幂等写入。这样拆的好处是每一层都可以独立测试，出问题时也能快速定位是采集丢了数据还是应用端处理错了顺序。

整个链路的核心原则有三条：第一，所有变更必须带单调递增的序列号，保证可排序；第二，所有写入必须幂等，允许传输层重试而不产生副作用；第三，冲突不能靠覆盖解决，必须显式定义合并策略。这三条原则贯穿了后面所有的代码实现。

二、变更捕获：触发器方案还是WAL解析方案

从SQLite里捕获增量数据，主流做法有两种。一种是基于触发器的审计表方案：给业务表建AFTER INSERT、AFTER UPDATE、AFTER DELETE触发器，把变更记录写入一张专门的change_log表。这种方案实现简单，事务语义清晰，触发器和业务写入在同一个本地事务里，不会丢数据。

另一种是解析WAL文件，性能开销更小，但实现复杂度高，而且WAL的格式属于内部实现细节，SQLite版本升级时格式可能变化，风险不小。对于零售这种每秒写入量并不高的场景，我们最终选择了触发器方案。下面是核心的建表和触发器语句：

-- 变更日志表，seq由AUTOINCREMENT保证单调递增
CREATE TABLE change_log (
    seq       INTEGER PRIMARY KEY AUTOINCREMENT,
    table_name TEXT NOT NULL,
    row_id    INTEGER NOT NULL,
    op        TEXT NOT NULL,   -- I/U/D 三种操作
    payload   TEXT,            -- 变更后的完整行数据，JSON格式
    created_at TEXT DEFAULT (datetime('now')),
    synced    INTEGER DEFAULT 0
);

CREATE TRIGGER product_ai AFTER INSERT ON product
BEGIN
    INSERT INTO change_log(table_name, row_id, op, payload)
    VALUES ('product', NEW.id, 'I',
            json_object('id', NEW.id, 'name', NEW.name, 'stock', NEW.stock, 'version', NEW.version));
END;

CREATE TRIGGER product_au AFTER UPDATE ON product
BEGIN
    INSERT INTO change_log(table_name, row_id, op, payload)
    VALUES ('product', NEW.id, 'U',
            json_object('id', NEW.id, 'name', NEW.name, 'stock', NEW.stock, 'version', NEW.version));
END;

这里有个容易踩的坑：payload里我们额外存了一个version字段，业务表上每次更新都让version加一。这个字段是后续冲突检测的依据，光靠时间戳在时钟不同步的终端环境下是不可靠的。另外要注意，SQLite的AUTOINCREMENT虽然性能上比普通INTEGER PRIMARY KEY略慢，但它能保证序列号不复用，这在同步场景里是必须的。

采集端用一个后台线程定时扫描change_log，按seq升序读取未同步的记录，打包发送，成功后标记synced为1。读取和标记之间要保持事务原子性，否则进程崩溃时可能出现重复发送，好在应用层是幂等的，重复发送不会有问题。

三、CockroachDB侧的幂等写入与冲突处理

数据到达云端后，直接写进CockroachDB。CockroachDB兼容PostgreSQL协议，支持分布式事务，所以应用端逻辑可以写在一个存储过程或者一段显式事务里。关键点有三个：用change_log的seq做幂等键，用version做乐观并发控制，用事务保证检查和写入的原子性。

我们在CockroachDB里建了一张同步去重表，每收到一批数据，先插入seq，如果主键冲突说明这批已经处理过，直接跳过。业务表的写入则采用CAS（Compare And Swap）风格：只有当本地的version大于远端的version时才执行更新，否则说明远端有更新的数据，进入冲突处理流程。核心SQL如下：

BEGIN;

-- 幂等检查：seq已存在则说明重复投递，整批跳过
INSERT INTO sync_dedup(seq, node_id)
VALUES ($1, $2)
ON CONFLICT (seq) DO NOTHING;

-- 仅当插入成功（未重复）时才继续处理业务变更
-- 乐观并发控制：远端version小于上报version才允许更新
UPDATE product
SET    name = $3, stock = $4, version = $5
WHERE  id = $6
AND    version < $5;

-- 如果影响行数为0，说明发生冲突，记录到冲突表等待人工或策略处理
INSERT INTO sync_conflict(node_id, row_id, remote_version, local_version, payload)
SELECT $2, $6, version, $5, $7 FROM product WHERE id = $6
AND NOT EXISTS (
    SELECT 1 FROM product WHERE id = $6 AND version < $5
);

COMMIT;

冲突处理策略没有银弹，要看业务语义。库存这类数值型字段可以用合并策略，比如取两边增量的和；商品名称这类字段只能取胜利者策略，通常以version高的为准；而对于订单这类敏感数据，一律进冲突表等人工裁决。我们在项目里把这三种策略做成了可配置项，每个字段可以单独指定。

还有一个细节值得注意：CockroachDB的事务如果检测到写冲突会自动重试，但客户端拿到的可能是事务重试错误（错误码40001），应用层必须捕获这个错误并重新提交，不能当成普通失败直接丢弃。

四、异常场景的补偿与顺序保证

分布式链路里最怕的不是失败，而是不知道自己失败了。网络抖动导致的一批数据丢失，往往几天后才被发现。我们的做法是每个终端维护一个本地已确认的最大seq，云端每成功处理一批就回执这个seq，终端收到回执才推进水位。启动同步时先交换水位，如果发现云端水位落后于本地水位，就从云端水位加一开始重传，配合幂等写入，重传是安全的。

顺序问题也需要特别处理。同一个业务行的变更必须按seq顺序应用，否则可能出现旧数据覆盖新数据。解决办法是采集端按seq分组，保证同一行的变更始终在同一个批次里且有序；不同行之间的顺序其实无所谓，可以并行处理提高吞吐。下面是采集线程的简化Go实现：

func (s *Syncer) fetchBatch(limit int) ([]Change, error) {
    rows, err := s.db.Query(`
        SELECT seq, table_name, row_id, op, payload
        FROM change_log
        WHERE synced = 0
        ORDER BY seq ASC
        LIMIT ?`, limit)
    if err != nil {
        return nil, err
    }
    defer rows.Close()

    var batch []Change
    for rows.Next() {
        var c Change
        if err := rows.Scan(&c.Seq, &c.Table, &c.RowID, &c.Op, &c.Payload); err != nil {
            return nil, err
        }
        batch = append(batch, c)
    }
    // 关键：同一行的多次变更必须在同一批内且按seq升序，
    // 超出行数限制时向后扩展，把同行的后续变更并入本批
    batch = s.extendForSameRows(batch)
    return batch, nil
}

最后补充一点关于删除的处理。SQLite侧的删除也要写change_log，op记为D，payload只存row_id。CockroachDB侧收到删除操作时不要物理删除，而是打上墓碑标记，因为下游可能还有节点需要感知这次删除，物理删除会让这些节点永远收不到通知。墓碑数据可以设置一个较长的过期时间，由定时任务统一清理。

这套方案上线运行后，日均同步百万级变更记录，全程无数据丢失。总结下来，SQLite与CockroachDB的全局一致性并不依赖某个神奇的开源组件，而是把幂等、单调序列、乐观并发控制和显式冲突策略这几个基础概念老老实实做对。理解了这些，换成其他数据库组合，思路也是通用的。

SQLiteCockroachDB全局一致性修改时间：2026-09-08 16:19:55