# 门店终端离线一天，数据恢复后对不上：oplog、幂等键与LWW合并的落地记录

上周五晚上十点，门店老板娘发微信来："我们店里网断了一整天，今天早上恢复了，但是昨天记的几笔跟后台对不上，差了七八条。"我本来以为是简单的同步问题，结果远程一看，终端离线期间本地攒了一堆操作，联网后一古脑往上报，有的重复了，有的互相覆盖了，整整对了一个半小时。

这事让我把终端离线同步的整套逻辑重新设计了一遍：本地操作日志、幂等去重、最后写入获胜。记录下来。

## 一、先搞清楚对不上的三种原因

终端离线期间的数据冲突，本质是三类问题混在一起：

1. **重复上报**：断网时本地点了"提交"，界面没反应又点了一次，联网后两条都发上去了。
2. **顺序错乱**：终端 A 和终端 B 都改了同一条记录，谁后到谁覆盖，跟实际操作顺序无关。
3. **本地未落库**：内存里的操作崩溃重启丢了，客户以为记上了，实际后台没有。

这三类问题要分开治，一个方案解决不了全部。

## 二、本地操作日志：每条操作先落 oplog

核心思路是终端每做一步操作，先写一份本地追加日志（oplog），再去发网络请求。联网失败不删日志，下次联网重发。日志结构：

```txt
{
  "opId": "终端UUID+雪花ID",   // 全局唯一
  "entity": "order",
  "entityId": "OD20261012003",
  "action": "update",
  "payload": { "status": "paid", "amount": 12800 },
  "clientTs": 1728712345678,   // 终端本地时间戳
  "seq": 1024                   // 单调递增序号
}
```

opId 是去重的关键：同一个 opId 无论重发多少次，服务端只认第一次。这里要注意终端时间不准（门店电脑时钟经常差几分钟），所以**不能拿 clientTs 当冲突依据**，服务端要在接收时盖一个服务端接收时间戳 serverTs。

## 三、幂等去重：服务端 opId 表拦截重复

服务端收到操作后，先查 opId 是否已处理过：

```txt
// 伪代码
if (opLogService.exists(opId)) {
    return lastResult;   // 直接返回上次结果，不重复执行
}
opLogService.save(opId, serverTs);
entityService.apply(action, payload);
```

opId 表保留 7 天即可，用 Redis SET 存，key=opId，value=结果，TTL 7 天。老板娘那种"点了两次提交"的情况，第二次请求直接被 Redis 拦掉，不会重复入库。

## 四、冲突合并：LWW 最后写入获胜

同一条记录被两个终端改过怎么办？我们业务能接受"以最后一次操作为准"，所以用 LWW（Last Write Wins）：

```txt
# 每条记录存版本时间戳
UPDATE biz_record
SET status = #{status}, version_ts = #{serverTs}, op_id = #{opId}
WHERE id = #{entityId}
  AND version_ts < #{serverTs}   -- 只接受更新的版本
```

那个 `AND version_ts < #{serverTs}` 是关键：旧版本的操作到了直接丢弃，不会把新数据覆盖回去。

对金额类字段我们没敢用 LWW——金额冲突得人工审，不能自动覆盖，单独打一个"待核对"标记推给店长。

## 五、踩坑清单（5 条实际踩过的）

1. 终端时钟不可信，冲突判定一律用服务端 serverTs，别用客户端时间。
2. oplog 用追加写（WAL）别用覆盖写，崩溃恢复时从最后一条接着发。
3. opId 别用自增序号，换终端就撞号；用终端 UUID + 雪花。
4. 批量重发要限速，一天断网攒几千条，联网瞬间全打过来会把服务端连接池打满。
5. 下载增量也得有版本号：客户端拉数据带 lastSyncTs，服务端只返回变更过的，别全量拉。

| 冲突类型 | 方案 | 能否自动合并 |
|---|---|---|
| 重复提交 | opId 幂等去重 | 能 |
| 同记录并发改 | LWW 版本号比较 | 非金额字段能 |
| 金额/库存冲突 | 打标记人工核对 | 不能 |

这次门店终端同步改造是在唯顿收银系统的门店终端模块上做的，我主要负责设计本地 oplog 表结构和服务端 opId 幂等那套逻辑，改完后模拟断网 24 小时再联网，700 多条操作零重复、零错覆盖，老板娘再没找过来对过账。

## 复盘

- 离线同步的第一步是本地先落日志，而不是先调接口；网络失败不能丢操作。
- 幂等键用全局唯一 opId，比业务字段去重可靠得多。
- 自动合并只用于可接受覆盖的字段，金额库存类冲突必须留给人判断。

以上是个人实践记录，各平台具体功能以官方实时信息为准。

做终端离线同步时，你们在金额这类敏感字段的冲突上，是全量人工核对，还是有别的自动合并策略？


上周五晚上十点，门店老板娘发微信来："我们店里网断了一整天，今天早上恢复了，但是昨天记的几笔跟后台对不上，差了七八条。"我本来以为是简单的同步问题，结果远程一看，终端离线期间本地攒了一堆操作，联网后一古脑往上报，有的重复了，有的互相覆盖了，整整对了一个半小时。

门店终端离线一天，数据恢复后对不上：oplog、幂等键与LWW合并的落地记录

门店终端断网一天，恢复后发现本地操作对不上。记录从本地oplog追加日志、服务端opId幂等去重，到LWW版本号合并的完整改造，附5个实际踩过的坑。

后端

架构设计

数据库

门店终端离线一天数据对不上？三种原因：重复上报、顺序错乱、本地未落库。解决方案：本地oplog记录每条操作、服务端opId幂等去重拦截重复请求、LWW版本时间戳解决并发覆盖，金额类冲突保留人工核对。实测断网24小时恢复700+操作零重复零覆盖。

数据恢复

代码解释

Redis

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

门店终端离线一天，数据恢复后对不上：oplog、幂等键与LWW合并的落地记录-腾讯云开发者社区-腾讯云

门店终端离线一天，数据恢复后对不上：oplog、幂等键与LWW合并的落地记录

门店终端离线一天，数据恢复后对不上：oplog、幂等键与LWW合并的落地记录

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐