企业官网建设流程全解析

• 即时通讯
• 后端

本文是 WuKongIM v2→v3 离线迁移系列取证报告之一，聚焦"消息副本差异定位"这一迁移阻断的核心环节。文章完整还原 2026-09-08 对真实停机备份（full-source-43 捕获）所做的消息副本枚举与逐项解码，说明为什么"副本有差异"不能直接推导出"消息丢失"，也不能按最大序号合并，并串联权威来源核验、历史前缀证明等后续证据链，帮助读者掌握迁移工具在副本不一致时如何安全地确定权威来源。

背景：一次在消息副本比较处停下的全量预检

WuKongIM 从 v2（v2.2.5-20260422，提交a888f89533d0e7d1b2030e06504ca97f1ad891d4）向 v3 原生集群迁移时，迁移工具会在停机备份上执行多轮只读预检。2026-09-08 的full-source-43是其中一次完整捕获：它采用了显式 User 时间归档的新预检（即 用户时间字段报告 中所述的metadata.archive_user_timestamps=true），在元数据阶段全部完成后，在消息副本比较处失败，退出码 1。

这次预检的关键运行事实：

• 耗时1312.16 秒，峰值 RSS217169920 字节；
• 原 601 个文件共1704886531 字节，扫描前后摘要完全一致，无资源保护中断；
• 未生成目标目录，未发布PREPARED检查点、转换结果或选择摘要；
• 消息副本冲突之外，活动插件缺少正式兼容映射的门槛也同时保留（该候选早于 plugin-artifacts-44，不包含新的原程序兼容规则）。

这与 阻断项台账 中记录的full-source-43一致：24786 个 User 原行、49572 个时间字段完整归档后，最终错误为 Message 副本冲突及原插件业务门槛。也就是说，"元数据全部通过"不等于"消息副本一致"，消息层是最晚也最容易暴露源端差异的一环。

全量消息候选枚举：一份可复核的统计底数

在元数据比较完成之后，迁移工具对已收集的全部消息候选进行了独立枚举，得到如下统计：

几点解读：

• 1025242 条物理候选是包含尾部（tail）记录在内的原始物理行集合，它同时跨越三份源副本，不能当作逻辑消息总数；
• 683007 对比较对是"当前 Leader vs 正式副本"这一权威视角下的逐条配对，是判断"谁缺了谁"的基准；
• 27 个不同值对应 27 个逻辑键，两者数量一致，说明每把逻辑键只出现一处值差异，没有同一键上的多重分歧；
• 74 项缺失检查项是正式副本侧的缺额计数，是后续逐项解码的核心对象。

需要特别强调的是：这份枚举是观察结论而非修复结论。报告明确指出，"27 个不同值"的观察不能代替缺失消息判定，也不能据此选择最大序号或放宽权威检查。

27 个不同值：全部落在频道尾部记录

对 27 个不同值逐类核对后发现一个高度集中的规律：

27 个不同值均为Message Other 类别的频道尾部记录，全部是当前 Leader 尾部较大，最大差距为17；没有发现同一主消息键的字段对撞。

这意味着在 683007 对比较中，主消息（普通消息、CMD 等）的相同键上没有内容冲突，差异全部来自"尾部记录"这一特殊的附加记录形态——它记录频道当前的持久尾部状态，不属于主消息序列。Leader 尾部比正式副本尾部更大，直观上像是"Leader 多了一段历史"，但从迁移证据的角度，它只能说明副本之间存在持久化进度差异，不能证明 Leader 多出的部分已经获得了历史提交确认或客户端 ACK。

74 项缺失逐项解码：71 个逻辑键、29 个频道

后续逐项解码确认了 74 个缺失检查项的真实构成：

• 71 个不同逻辑键，分布在29 个频道；
• 按消息类别拆分：普通消息 54 项、CMD 消息 17 项、尾部记录 3 项；没有流消息；
• 按缺失方向拆分：68 项是当前 Leader 有记录而其他正式副本缺少；6 项是其他副本有记录而当前配置 Leader 缺少。

两个方向都有缺失，说明差异不是单向的"某个 follower 落后"，而是需要分别核对"Leader 超额"与"Leader 缺额"两类情况。报告特别警告了两种看似合理、实则错误的处理方式：

1. 不得按最大序号直接合并——74 项是副本检查项（replica check items），不是需要丢弃的逻辑消息数；
2. 用户批准排除 CMD 也不能解决问题——CMD 只占 17 项，普通消息的 54 项缺失以及 Leader 缺失的 6 项并不会因此消失。

正确的做法是：结合原配置、复制日志和旧读取／提交语义确定权威，在此之前当前不放行 PREPARED。

权威判定原则：为什么"最大序号"不能成为规则

从 权威来源专项核验（authority-19）到本报告的共识是一致的：迁移工具从不使用"最多消息、最高序号或无条件的多数表决"来确定来源。原因在于：

• 尾部较大不等于已提交：原版 v2 的pkg/cluster/channel/storage.go:GetState会把最后持久消息的序号直接作为 AppliedIndex，末尾序号不是独立的历史提交证据（详见 历史前缀报告 对固定 v2 源码的引用）；
• 副本缺额是物理事实，不是业务丢弃量：HistoryPrefixCopy.MissingSuffix在迁移 usecase 源码中明确注释为"physical replica deficit, not data loss"（见 history_prefix.go）；
• 选择规则必须只认当前配置 Leader 的完整原行，且同时满足正式副本多数完整、其余副本严格前缀、配置命令链无删除无换主等条件——这就是 操作手册 中"history": {"leader_quorum_prefixes": true}选项的语义：它要求当前 Leader 与正式副本多数拥有完全一致的完整历史，其他副本是严格前缀，并核对源 Slot、当前配置和完整保留配置命令；当前 Leader 缺失历史、同任期换主、成员变更、删除、内容冲突或中间缺洞均不能通过。

从源码结构看，history_prefix.go 中的HistoryPrefixReport.CandidateNode只能取自当前配置 Leader，注释明确写道："never a longest follower chosen to replace an empty or shorter Leader"。这正是本报告"不选择最大序号"原则在实现层的落点。

后续证据链：29 个频道如何被逐一收口

本报告记录的是"差异被定位、但权威未定"的阶段。后续增量证据在系列报告中逐步收口：

1. history-evidence-46（历史前缀报告）从full-source-43捕获的原始行与原始配置命令重新读取这 29 个差异频道：全部频道均有两个正式副本保存完全相同的最高完整历史，其余副本是严格前缀；逐行比较包含原 MessageID、序号、任期及所有原始存储字段的 SHA256，没有同序号内容冲突和中间缺洞。较短副本合计缺少 69 个物理消息行——这再次强调是"副本缺额"而非迁移丢弃数量。

2. 28 个频道同时满足当前 Leader 完整、正式多数完整、其他副本严格前缀及保留配置命令检查；剩余 1 个频道当前 Leader 1001 没有消息／尾部，正式副本 1002、1003 一致保存两条消息，保留的四条配置命令在三节点一致，存在同任期换主（Leader 1002 → 1001）但频道任期仍为 1 的历史，未发现删除——该频道保持阻断。

3. recovery-48完成完整真实源选择：29/29 频道全部处理，其中 1 个按用户批准以摘要绑定的指定副本恢复两条原消息（见 阻断项台账 与 缺失会话核对报告）。

4. 最终验收（最终功能验收报告）确认：权威来源最终结果为 28 个频道满足完整正式多数／前缀／配置证据，1 个按已批准的摘要绑定决定恢复 2 条原消息；全量离线校验 1,005,297 条消息副本全部通过。

这条链条展示了迁移工具的取证纪律：先枚举差异，再逐项解码，再重新捕获证明，最后才允许显式恢复——每一步都不允许用早期诊断代替重新验证。

证据与边界：私有证据如何管理

本报告的运行证据位于私有目录tmp/server-rehearsal-20260908/message-conflicts-45/，其访问规则值得迁移运维人员注意：

• summary.json与conflicts.jsonl使用身份摘要（identity digest），可在报告中引用；
• original-message-pairs.jsonl及后续 details 原行文件属于私有源证据，不得公开；
• 原工作空间只用于读取候选，没有生成 PREPARED、转换结果或选择摘要。

这与整个迁移取证体系的约定一致：公开报告只承载"能证明什么"的摘要证据，而原始正文、凭据与源身份始终留在私有证据目录，防止迁移证据本身成为泄密渠道。

结论：副本差异定位的工程纪律

从本报告可以提炼出 WuKongIM v2→v3 迁移在"消息副本不一致"场景下的四条核心纪律：

1. 枚举先行：先给出物理候选、比较对、不同值与缺失项的全量统计底数，任何结论都基于可复核的数字；
2. 差异分类：区分尾部记录差异与主消息差异、区分 Leader 超额与 Leader 缺额、区分普通消息／CMD／尾部记录，不同类别对应不同处理路径；
3. 拒绝捷径：最大序号合并、排除 CMD、无条件多数表决都不是权威判定的合法依据；
4. 证据重放：prepare 与归档重建必须从原始捕获重新计算证明，不接受旧诊断或缓存结论，当前不放行 PREPARED 直到权威确定。

这套纪律最终让 29 个差异频道全部收敛：28 个通过完整 Leader／正式多数／严格前缀证明，1 个经用户批准完成摘要绑定的显式恢复，全量离线校验通过。对希望复现这一过程的读者，可对照 操作手册、迁移 CLI 说明 与迁移 usecase 的 history_prefix.go，并结合真实停机备份按diagnose → authority → prepare → export → import → verify顺序推进。需要说明的是，本报告及其后续验收均基于约 1.59 GiB 的真实备份，任何耗时数据都不能外推为 100 GiB / 4 小时的大规模性能承诺，后者仍在等待测试环境。

• 即时通讯
• 后端