PeerID 管理

快速概览

在 Loro 的分布式系统中，PeerID 是区分每个编辑会话的唯一标识，用于在无需协调的情况下确保操作 ID 不会冲突。

核心概念

PeerID：为每个客户端 / 会话分配的 64 位唯一标识
Operation ID：由 (peerId, counter) 组成，用于唯一标识每个操作
Counter：每个 peer 独立维护、从 0 开始递增的计数器

interface OpId {
  peerId: `${number}`;  // 唯一的 peer 标识；用字符串表示，因为 JS 不支持 64 位整数
  counter: number;      // 单调递增的计数器
}

PeerID 分配

默认：自动分配

const  = new (); // 自动获取随机 PeerID
// 安全，无需协调

提示：每个 LoroDoc 实例都会生成新的 PeerID，即便加载的是同一份文档。

手动分配

const  = new ();
.("123123123");  // 只能设置 64 位整数（字符串表示）

⚠️ 警告：手动分配需要谨慎避免冲突。

如果你要复用某个 PeerID，请确保将该文档的本地数据（快照、更新或持久缓存）与该 ID 一同保存，并在获取或应用任何远端更新之前先加载它。这样才能确保 (peerId, counter) 对应的是同一批操作。否则，新操作可能会复用已有的 Operation ID，导致副本出现不一致。

计数器系统

每个 peer 都维护一个从 0 开始的单调计数器：

const  = new ();
.("1");
const  = .("text");
 
.(0, "H");    // Operation ("1", 0)
.(1, "i!");   // 产生 Operation ("1", 1) 与 ("1", 2)
.(.()); // { "1": 2 }

特性：单调、连续、按 peer 独立维护且可持久化。

常见误区

❌ 请勿：

直接使用用户 ID 作为 PeerID（同一用户可能有多台设备）
使用固定不变的 ID
未经管理地重复使用同一 ID
允许多个浏览器标签页或进程并行复用同一个 PeerID —— 如需复用，请通过锁等机制协调，确保同一时间只有一个会话为该 ID 产生操作