一、前置思考

1.1 多设备同步的一致性问题

分布式 KV Store 让数据跨设备同步成为可能，但同步不等于一致：两台设备同时修改同一个 key，谁赢？设备离线期间的修改怎么合并？同步延迟期间读到旧值怎么办？

场景: 手机和手表同时修改步数目标
  手机: 目标 = 10000 (14:00:01)
  手表: 目标 = 8000  (14:00:02)
  → 同步后最终值是多少? 谁说了算?

1.2 CAP 定理的工程含义

CAP: 一致性(Consistency) / 可用性(Availability) / 分区容错(Partition tolerance)
  分布式系统只能三选二

移动分布式场景: 网络不可靠 (分区必然发生)
  → P 必选, 在 C 与 A 之间取舍

鸿蒙分布式数据的选择:
  → 弱一致 (最终一致性) + 高可用
  → 离线可用 (A), 联网后收敛 (最终C)
  → 用 CRDT / LWW / 版本向量 实现收敛

1.3 本文路线

深入 CAP 取舍、冲突检测、CRDT 数据结构、版本向量，给出鸿蒙分布式 KV 的一致性保障工程方案。

二、核心原理

2.1 最终一致性的收敛机制

设备A ──修改──→ 设备B
  │                │
  └──修改──→ 冲突检测 → 冲突解决 → 收敛到一致值

三种冲突解决策略：

策略	原理	优点	缺点
LWW (Last-Write-Wins)	时间戳大者胜	简单	时钟不可靠时错判
CRDT	数学上可交换合并	天然无冲突	仅适用特定结构
版本向量	记录每设备版本	精确检测并发	需合并算法

2.2 CRDT 无冲突数据结构

CRDT（Conflict-free Replicated Data Type）通过操作可交换性从数学上消除冲突：

G-Counter (只增计数器):
  每个节点保存自己的增量
  merge = 逐节点取 max 后求和
  → 无论并发多少次 +1, 合并结果一致

PN-Counter (增减计数器):
  正增量 G-Counter + 负增量 G-Counter 组合

LWW-Register (带时间戳寄存器):
  存 {value, timestamp}
  merge = 取时间戳大者
  → 依赖时钟, 是"弱CRDT"

OR-Set (可重复添加删除的集合):
  每个元素带唯一 tag
  删除 = 记录 tombstone tag
  → 并发添加/删除不丢失

CRDT 的核心价值：不需要协调中心、不需要锁定、离线可用，合并操作满足交换律/结合律/幂等律。

2.3 版本向量（Vector Clock）

版本向量记录每个节点的修改版本号：

设备A: [A:3, B:1]  表示 A 改了3次, B 改了1次
设备B: [A:2, B:2]

比较规则:
  向量A ≤ 向量B (逐维) → B 包含 A 的所有修改, 直接覆盖
  向量A ∥ 向量B (存在 A>B 和 A<B 维度) → 并发修改, 需合并

A: [A:3, B:1]  vs  B: [A:2, B:2]
  A维度: 3 > 2   B维度: 1 < 2
  → 互有领先 → 并发冲突 → 交给合并策略

2.4 鸿蒙分布式 KV 的一致性模型

• 支持 MULTI_VERSION_CRDT 类型 KV Store（多版本 CRDT 合并）；
• 单机写本地立即生效，同步走软总线异步推送；
• 同步策略：PUSH_ONLY / PULL_ONLY / PUSH_PULL；
• 冲突合并默认 LWW（按修改时间），CRDT 计数器按结构合并。

三、源码/API 深度解析

3.1 创建分布式 KV（MULTI_VERSION_CRDT）

import { distributedKVStore } from '@kit.ArkData';
import { common } from '@kit.AbilityKit';

async function createDistKv(context: common.Context): Promise<void> {
  const kvManager = distributedKVStore.createKVManager({
    bundleName: 'com.example.app',
    context: context
  });

  const options: distributedKVStore.Options = {
    createIfMissing: true,
    encrypt: true,
    securityLevel: distributedKVStore.SecurityLevel.S1,
    // 关键: 多版本 CRDT 类型, 自动冲突合并
    kvStoreType: distributedKVStore.KVStoreType.MULTI_VERSION
  };

  const kv = await kvManager.getKVStore('dist_kv', options);
  const deviceIdList = await kvManager.getDeviceIds();   // 获取组网设备
  // 开启自动同步
  await kv.sync(deviceIdList, distributedKVStore.SyncMode.PUSH_PULL, 1000);
}

3.2 冲突解决回调（onConflict）

// 自定义冲突解决策略 (替代默认 LWW)
// 注意: 仅 DEVICE_COLLABORATION 类型支持自定义
kv.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_LOCAL_ONLY, (data) => {
  data.updatedEntries.forEach(e => {
    console.info(`本地变更: ${e.key} = ${e.value}`);
  });
});

3.3 手动实现 LWW 版本合并（应用层）

interface VersionedValue {
  value: string;
  ts: number;          // 修改时间戳
  deviceId: string;    // 修改设备
}

// 应用层 LWW 合并: 时间戳大者胜, 相同时设备id字典序兜底
function mergeLww(a: VersionedValue, b: VersionedValue): VersionedValue {
  if (a.ts > b.ts) { return a; }
  if (b.ts > a.ts) { return b; }
  return a.deviceId > b.deviceId ? a : b;   // 时钟相同按设备兜底
}

四、企业级实战落地

4.1 CRDT 计数器落地（点赞/步数）

// 场景: 健康 App 步数在手机+手表分别累计, 合并后不丢
interface NodeCounter {
  nodeId: string;
  deltas: number[];
}

class GCounter {
  private nodes: Map<string, number> = new Map();   // nodeId -> 累计增量

  increment(nodeId: string, delta: number): void {
    this.nodes.set(nodeId, (this.nodes.get(nodeId) ?? 0) + delta);
  }

  value(): number {
    let sum = 0;
    this.nodes.forEach(v => { sum += v; });
    return sum;
  }

  merge(other: GCounter): void {
    // 逐节点取 max 后求和 → 无冲突收敛
    other.nodes.forEach((v, nodeId) => {
      const cur = this.nodes.get(nodeId) ?? 0;
      this.nodes.set(nodeId, Math.max(cur, v));
    });
  }
}

4.2 同步冲突检测与解决流程

本地写入 (带 deviceId + ts) → KV Store
         ↓
同步到其他设备 (PUSH_PULL)
         ↓
目标设备收到 → 版本比较:
  ├─ 时间戳大者胜 (LWW)
  ├─ 字段级冲突: 按业务规则合并 (如 JSON 字段 merge)
  └─ 结构性数据: CRDT 结构合并
         ↓
收敛 → 触发 dataChange 通知 UI 刷新

4.3 弱网一致性策略

在线: PUSH_PULL 实时同步
弱网: PULL_ONLY 只拉取, 本地修改攒批
离线: 本地正常读写 (高可用), 修改进同步队列
恢复: 增量同步 + 冲突合并

4.4 一致性实测（模拟）

场景	并发修改	合并结果	数据丢失
LWW 同 key	2 设备同时改	时间戳大者	有(后写覆盖)
G-Counter 步数	2 设备各 +1000	2000	无
OR-Set 标签	2 设备增删	并集+墓碑	无
版本向量检测	并发修改	检测到冲突	可追溯

五、问题排查与性能优化

坑	现象	原因	解决
同步丢数据	手表步数覆盖手机	LWW 后写覆盖	CRDT 计数器
时间戳错判	时钟不准谁输赢乱	LWW 依赖设备时钟	版本向量 + 设备id兜底
同步延迟	改完不即时	PULL_ONLY	PUSH_PULL
数据不一致	多设备状态不同	无合并策略	明确冲突解决规则
离线修改丢失	恢复后少了	无同步队列	修改进队列
同步冲突报错	版本冲突异常	未处理冲突	onConflict 回调
覆盖丢失	并发写同 key	默认 LWW	业务层版本合并

5.1 时钟问题的工程兜底

设备时钟不可靠 → 不要完全依赖 ts
方案1: 服务端时间戳 (NTP 同步后打点)
方案2: ts 相同用 deviceId 字典序兜底
方案3: 结构性数据用 CRDT 而非 LWW

5.2 同步策略选择

场景	推荐同步	原因
聊天/协作文档	PUSH_PULL	双向实时
设备采集上报	PUSH_ONLY	单向上报
弱网只读场景	PULL_ONLY	只拉不推
离线攒批	恢复后 PUSH	攒批合并推

六、高阶总结与最佳实践

1. 移动分布式必然弱一致：P 必选（网络会分区），在 C 与 A 之间取舍，鸿蒙默认走"高可用 + 最终一致"。
2. 冲突解决策略要按数据类型选：
   • 计数器/集合等结构性数据 → CRDT（数学上无冲突）；
   • 配置/文本等整体覆盖数据 → LWW（简单够用）；
   • 复杂协同（协作文档） → 版本向量 + 字段级合并。
3. 时钟不可靠是 LWW 的软肋：ts 相同用 deviceId 兜底，或改用 CRDT。
4. 同步策略按方向选：双向实时用 PUSH_PULL，单向上报用 PUSH_ONLY。
5. 离线可用是移动场景的底线：离线读写 + 同步队列 + 恢复合并，保证不丢数据。

一句话记住：一致性不是"同步"，而是"冲突怎么收敛"——CRDT 让结构性数据天然收敛，LWW 让简单数据快速收敛，版本向量让并发可检测。