WuKongIM v2→v3 迁移阻断项台账解读：验收证据链、拓扑恢复与生产切换边界

• 即时通讯
• 后端

本文围绕 WuKongIM 仓库中的《v2 → v3 迁移阻断项台账》（docs/superpowers/reports/2026-09-08-v2-migration-blockers.md）展开。该台账记录了在codex/v2-v3-migration工作树上，将未经修改的 v2 集群停机数据离线迁移到全新 v3 集群过程中，各项 P0/P1 验收项的"实际完成边界"：哪些已经拿到可复现证据、哪些仍阻断、哪些按用户决定延后。读完本文，你将掌握 WuKongIM 官方迁移验收的完整口径——包括权威源判定、离线导入闭环、消息序号映射、插件兼容规则、拓扑故障恢复矩阵，以及"离线校验通过 ≠ 生产可切换"的边界纪律，并能据此在自己的迁移演练中设计可核对的证据清单。

一、台账背景：什么算"已验收"，什么不算

台账更新于 2026-09-08，工作树codex/v2-v3-migration。迁移的源是**未经修改的v2.2.5-20260422（提交a888f89533d0e7d1b2030e06504ca97f1ad891d4）**停机备份：601 个文件、1,704,886,531 字节，迁入全新的 v3 集群，源服务不需要升级。完整操作流程见操作手册，最终结论汇总见最终验收报告。

台账开篇就划定了三项明确不在本次结论内的工作：

• 生产切换：尚未向现有 v3 导入或切换生产流量，切流仍须落实业务客户端适配和运维窗口；
• 业务 App 自有缓存适配：仅验证了 Web SDK 1.3.5 / Chromium 的真实源缓存重置规则，未知业务 App 的持久化表/键未提供；
• 100 GiB / 4 小时性能测试：用户明确延后，等待测试环境。

后续deployment-57已按用户新增测试环境授权迁入/root/wukongim，实际入口、SDK、插件、两次整集群重启及监控均通过，原 v3 已备份，迁入后集群保留运行（见服务器测试迁移）。台账特别强调：不把历史组件测试、单节点扫描或规划输出当作完整迁移证明——这正是本文要反复强调的证据纪律。

二、P0 阻断项逐条解读

2.1 完整真实源权威与业务副本一致性

这是迁移的第一个 P0，核心是"从哪些节点取业务数据、副本之间不一致时怎么定权威"。台账给出了完整的处理链条：

• history-evidence-46：从原始捕获重查 29 个差异频道，28 个通过完整当前 Leader、正式多数、严格前缀及配置日志检查；对应显式历史策略已接入 prepare／归档重建，并通过三节点来源到单／三节点目标测试。
• 1 个频道当前 Leader 为空且存在同任期换主／成员变化，用户已批准恢复两份一致的 2 条普通消息。
• recovery-48：完成完整真实源选择，29/29 通过、1 个显式恢复，来源选择摘要和原插件 profile 均已生成；独立核对恢复的两条原消息全部字段一致。
• visibility-49：加入限定的已读会话决定后，全量 prepare 亦已成功。

配套的权威来源专项核验展示了这条链路的工具化支撑：authority命令两轮加锁读取源库，每轮核对扫描前后文件摘要、两轮摘要也必须相同；第一轮采集配置及保留的 Slot 配置命令，第二轮按原序号比较限定频道的全部持久化字段摘要。它对每个带迁移标记频道给出四类结论：

candidate_node仅是诊断结论，不会写入选择清单、不清除原库标记、不生成PREPARED。prepare会从原始捕获记录独立重建证据，不能用该报告直接放行。

2.2 活动插件迁移

P0 第二项"活动插件迁移"在本轮只验收了唯一已批准的程序。runtime-56在真实源迁出的隔离三节点集群中，使用原 AI 示例程序、原绑定及批准的配置，完成三轮真实 SDK 验证：自动 Receive、配置对应回复、实时接收和持久化历史，并跨两次整集群重启核对旧回复。台账明确：未知程序仍阻断，不据此认证其他插件。

插件的兼容边界由plugin_artifacts的 profile 机制固定（见程序迁移报告）：唯一 profilewk-ai-example-receive-linux-amd64-v1固定原程序 11,856,443 字节，SHA256 为671b3436d1a8d765371077009b1dfd6dec4528a1ce9cdc0dbebe2cfddc5b3224，仅接受版本 0.0.1、唯一 Receive 方法、优先级 1、name-only 字符串配置。程序按 1 MiB 分块写入不可变工作空间，导出归档包含全部分块；目标通过原生目录扫描安装为plugins/<plugin_no>.wkp（权限 0500）。原插件历史在重启后的完整性另由插件恢复验收覆盖：三节点 12 条自动回复、12 条直接 hook 回复，两次重启后逐条核对完整字段。

2.3 真实源转换与离线导入闭环

这是最重的一个 P0，台账给出了完整闭环要求：完整 prepare → export → 移除源访问后的独立归档重建 → 隔离空目标 import/retry/verify，且必须比较原始业务字段及全部计划副本，不能以单节点物理行数充当逻辑总量。真实数据的完整数字链如下：

台账还记录了两次真实教训：首次归档导入因演练漏建目标父目录而停止（未写目标数据）；archive-53 verify因只读 catalog 分页漏计失败，修复后同一节点读到 5103 频道／335099 消息。完整的中间过程见归档演练报告。消息副本差异的逐项定位见消息副本定位：27 个不同值均为 Message Other 类别的频道尾部记录（当前 Leader 尾部较大，最大差距 17），74 个缺失检查项对应 71 个逻辑键、29 个频道。

2.4 消息规则与序号映射

流消息和 CMD 排除、去重后保留最新、频道压紧为 1…N、读删位置映射，均已通过组件和原生运行测试。recovery-48的完整权威源消息转换规划是：337022 → 335099 条，排除 1660 CMD、15 流、248 重复；150 个频道、122876 条保留消息改序。

序号映射的真实运行验证来自runtime-56浏览器场景：

• 旧尾序号 150 → 保留 147 条的频道：清旧缓存、保留凭据、重新同步全部 147 条原字段，新消息为 148、未读为 1；
• 另一 100 条历史频道跨两次整集群重启追加序号为 101、102、103。

计划中启用这些规则的方式（详见CLI 说明）：

{ "messages": { "keep_latest_duplicates": true, "exclude_cmd": true, "exclude_streams": true, "compact_sequences": true }, "exclusions": { "legacy_stream_storage": true } }

其中 CMD 判断遵循固定 v2 版本的 SyncOnce、默认____cmd命令频道和systemcmdonline保留频道，不读取正文猜测；流消息按原Setting的1<<1标志或非空StreamNo识别。保留消息按原顺序连续编号 1…N，原生 v3 首条新消息分配 N+1；每条普通会话的已读和删除位置映射为"原位置之前（含）仍保留的消息数量"。prepare 成功会输出带校验和的sequence_mapping，并可从归档独立重建：

wkcli migrate export-map --plan /absolute/plan.json \ --workspace /absolute/map-workspace --archive /absolute/source-archive

2.5 现场运行与切换

隔离运行验收已完成：runtime-56真实浏览器原凭据登录、历史/会话/未读、收发、插件及两次整集群重启全部通过；601 个原源文件不变；原 v2 始终停机，现有 v3 健康且容器 ID/启动时间未变。但台账措辞非常谨慎：尚未向现有 v3 导入或切换生产流量；切流仍须落实业务客户端适配和运维窗口。测试环境切换（deployment-57）的验收细节见服务器测试迁移：255 个初始数据文件与完整校验一致，262 个上传文件在服务器再次核对大小、权限和 SHA256；原对外端口保留（API 15001、管理端 18080、TCP 15100/15101/15102、WebSocket 15200/15201/15202）；错误 token 连接被明确拒绝（鉴权失败原因码 2）。

2.6 原生故障恢复与拓扑验收

该 P0 已完成，且是最有说服力的部分（见拓扑与恢复报告）：

• 原生无迁移三节点 Leader 故障对照通过（27.575 秒）；
• 3→5 正式构建连续三轮通过（49.09、40.45、42.42 秒）；
• 最终矩阵 1→1、1→3、3→1、3→3、3→5 全部通过，总计 158.304 秒，覆盖历史/凭据、幂等追加、完整重启、Leader 故障及全节点历史。

台账特别注明：修复均为独立原生回归确认的恢复/复制/错误隔离问题，没有新增 v2 存储格式。过程中的关键修复包括：Channel RPC v8 同时传递 RedDot 和 SyncOnce（旧版本无法表达置位标记时明确返回错误）、原生 Learners 投影让新副本追平（不把 learner 计入 quorum）、Slot FSM 快照恢复的元数据隔离等。

三、P1 项与延后验收

3.1 客户端旧缓存与序号游标切换（P1）

已按用户批准策略完成 Web SDK 1.3.5 / Chromium 的真实源验收：用旧源行构建私有消息缓存，清除消息/游标但保留原凭据，重载页面并从 v3 无旧游标同步，逐条核对保留历史及后续新消息（浏览器 SDK 验证）。具体业务 App 的持久化表/键尚未提供，不能认证其缓存适配或自定义正文渲染；Android/iOS/Flutter/HarmonyOS 原包未执行。客户端执行顺序在操作手册中有严格定义：先停止发送并关闭旧连接，记录迁移代次；保留 UID、token、设备标识和业务登录状态；删除旧消息缓存、会话列表派生缓存、历史翻页位置和消息同步序号；第一次同步不得提交旧message_seq或旧翻页位置，全部首次同步成功后才标记该账号完成新迁移代次。清理范围不能对整个 origin 调用localStorage.clear()，否则可能同时删除登录凭据。

3.2 改变源/目标节点数（P1）

已完成 1→1、1→3、3→1、3→3、3→5 原版 v2 测试库全流程矩阵；插件配置分配扩缩容、归档及原生安装已有plugin-topology-40证据。改变节点数时必须通过plugin_nodes显式指定目标配置分配：

"plugin_nodes": [ {"source_node": 1001, "target_node": 1}, {"source_node": 1002, "target_node": 2}, {"source_node": 1003, "target_node": 3} ]

每个目标节点必须且只能指定一个配置来源；同一源节点可以供多个目标使用（如单节点来源扩容）。台账没有把每一种任意节点数/插件组合都宣称经过真实源运行测试。

3.3 100 GiB / 4 小时（P1，延后）

用户明确延后，等待测试环境。台账给出硬性口径：当前真实备份约 1.59 GiB，功能演练耗时不能外推为 100 GiB 性能承诺；没有大规模吞吐证据，未通过该性能验收。操作手册还列出资源约束：原生 Slot Raft 快照桥接当前上限为每个物理 Slot 256 MiB 元数据，事件同步每页保留投影上限 8 MiB，每个不可拆分 proposal 的原生编码与传输计费不超过 1 MiB。

3.4 最终候选交付（P1）

最终全量单元检查通过：206 个有测试包、13 个无测试包，失败 0；正式拓扑矩阵、原生定向回归、go-vet、格式和 FLOW 检查通过（FLOW 检查 79 份合规、0 份无效）。runtime-56Linux/amd64 正式服务端候选已完成服务器验收，实测 Linux 服务端 SHA256 为907cb6de4a98d04c1101a440fe7f5d155e1b7ffd37960153f8cd476d7d120207，Linux 迁移工具 SHA256 为1faa67d91a29a4014ee327e395817e0ec6e8995a1b63fb1325655b9d2b46f120。台账特别记录：此前因本机磁盘耗尽失败的检查已保留日志，清理可重建缓存后完整重跑通过，不算作成功证据。

四、已有明确证据的基础问题与语义边界

台账单列了三个已有明确证据的基础问题：RedDot 使用 v3 原生字段保留；通用冷历史恢复已独立复现与修复；空历史 API 同步 main 既有修复并通过普通空频道及全流消息排除后的单节点/三节点 HTTP、追加和重启测试。

同时，台账用四条"读报告纪律"避免误读：

1. prepare现在保留插件失败，但将其延后到可独立进行的源副本检查之后，并与后续错误共同报告。
2. replica_comparison_complete仅表示原业务副本比较完成；plugin_business_rows是原始物理插件记录数，不是逻辑绑定数。
3. 插件不兼容时 selection digest 为空，转换和导出拒绝，且不发布workflow/PREPARED。
4. 失败 CLI 可以输出status=blocked的部分证据，退出码仍为 1。

这些语义在源码中有直接对应。迁移计划结构定义在 internal/usecase/migration/workflow.go：Plan包含Sources、Target、Exclusions、Messages、Metadata、History、PluginNodes、PluginConfigs、PluginArtifacts等字段，ReadPlan（同文件 L52-L97）拒绝未知字段、固定version=1、把source_commit钉定到固定 v2 schema 提交，并限制源节点数量（1–1024）、分片数（1–1024）和绝对路径。SourceSelection结构定义在 internal/usecase/migration/selection_types.go：ReplicaComparisonComplete被显式注释为"仅诊断证据，兼容阻断仍阻止 selection digest 和 PREPARED 检查点"，PluginBusinessRows只统计"仍需验证可执行文件/运行映射的捕获物理注册数，不含配置"。Prepare的阶段编排（workflow.go）依次执行 source capture → plugin settings → plugin artifact capture/validation → empty-channel certification → source identity catalog → source index validation → source authority and replica comparison → native record conversion，最后发布workflow/PREPARED。

五、从台账到可执行流程：九步离线迁移

台账的验收口径最终落到操作手册的流程：停止业务写入 → 原版 v2 收敛并排空通知 → 正常停止全部 v2 节点 → 保存完整停机备份 →diagnose（列出兼容缺口）→prepare→export→import→ 停机verify→ 隔离启动 v3 并做业务验收 → 切换流量。工具由wkcli migrate子命令提供（源码在 internal/usecase/migration 与 cmd/wkcli/internal/migrate/README.md），构建方式：

GOWORK=off go build -o /srv/tools/wkcli ./cmd/wkcli GOWORK=off go build -o /srv/tools/wukongim-v3 ./cmd/wukongim /srv/tools/wkcli migrate --help

一个三节点迁移的示例计划（地址、路径、分片数按实际部署填写）：

{ "version": 1, "source_commit": "a888f89533d0e7d1b2030e06504ca97f1ad891d4", "sources": [ {"node_id": 1, "data_dir": "/srv/v2-snapshots/node1", "shard_count": 8}, {"node_id": 2, "data_dir": "/srv/v2-snapshots/node2", "shard_count": 8}, {"node_id": 3, "data_dir": "/srv/v2-snapshots/node3", "shard_count": 8} ], "target": { "cluster_id": "production-v3-migrated", "created_at": "2026-09-06T08:00:00Z", "slot_count": 12, "hash_slot_count": 256, "replicas": 3, "channel_replicas": 3, "nodes": [ {"node_id": 101, "addr": "10.20.0.11:7000", "data_dir": "/srv/wkmigrate/node101"}, {"node_id": 102, "addr": "10.20.0.12:7000", "data_dir": "/srv/wkmigrate/node102"}, {"node_id": 103, "addr": "10.20.0.13:7000", "data_dir": "/srv/wkmigrate/node103"} ] } }

关键约束：目标节点 ID 为 1–1023、端口 1–65535、hash_slot_count固定 256、物理slot_count为 1–256、两类副本数均不能超过节点数；所有路径必须绝对且互不包含；导入前先创建目标data_dir的父目录，目标目录本身必须不存在（工具排他创建并写入导入身份）。各阶段命令依次为：

# diagnose：源级兼容普查，输出有界 JSON 摘要 + 带校验和的完整 JSONL /srv/tools/wkcli migrate diagnose --plan /srv/wkmigrate/plan.json \ --workspace /srv/wkmigrate/diagnostic-workspace > /srv/wkmigrate/diagnostic.json # prepare：离线检查并生成转换清单 /srv/tools/wkcli migrate prepare --plan /srv/wkmigrate/plan.json \ --workspace /srv/wkmigrate/scratch > /srv/wkmigrate/reports/prepare.json # export：封存带校验和的分块归档 /srv/tools/wkcli migrate export --plan /srv/wkmigrate/plan.json \ --workspace /srv/wkmigrate/scratch --archive /srv/wkmigrate/archive \ > /srv/wkmigrate/reports/export.json # import：生成全新 v3 数据目录（目标服务未启动） /srv/tools/wkcli migrate import --plan /srv/wkmigrate/plan.json \ --workspace /srv/wkmigrate/scratch --archive /srv/wkmigrate/archive \ > /srv/wkmigrate/reports/import.json # verify：首次启动 v3 之前独立核对全部业务数据 /srv/tools/wkcli migrate verify --plan /srv/wkmigrate/plan.json \ --workspace /srv/wkmigrate/scratch --archive /srv/wkmigrate/archive \ > /srv/wkmigrate/reports/verify.json

verify成功为退出码 0、status: "offline_verified"；校验器重新解码归档中的权威源记录，不使用转换器的目标行或成功计数作为预期值，逐字段核对所有目标副本的凭据、成员/权限、会话/CMD 状态、事件投影和消息完整内容，同时核对 Controller WAL/快照、Slot 快照与整套发布文件指纹。启动后的隔离业务验收需覆盖：集群健康、原凭据登录（错误 token 拒绝）、历史分页首尾与跨页、权限和会话、/message/eventsync投影、新写入（新消息 ID 不与旧记录冲突、seq 超过原尾部、同幂等键重试不重复）、重启与故障（重启后结果不变；多节点集群丢失一个 Leader 后恢复读写且历史不丢）。

对于交付包的隔离演练，仓库提供了 scripts/migration/rehearse-offline.py（说明见 scripts/migration/README.md）：以只读挂载方式执行 delivered Linux amd64 二进制的prepare → export → import → retry → verify，先--dry-run校验路径与二进制哈希，执行阶段默认保留 2 GiB 主机磁盘、每阶段 90 分钟、每容器 1.5 GiB 内存/4 CPU。

六、证据管理与解读纪律

台账末尾集中给出了"看证据"的方法论：

• 源检查运行证据位于私有tmp/server-rehearsal-20260908/full-source-39/；process.json仅是定位线索，是否运行必须查看实际进程或工具会话；最终结果以execution.json、stdout.json、stderr.log及源文件前后摘要为准。
• full-source-39耗时 1540.35 秒、峰值 RSS 242450432 字节，601 个源文件前后完全一致，隔离目标目录未生成；它没有完成消息副本比较，没有生成 PREPARED——时间差异的字段范围、日志证据和归档测试见用户时间字段报告。
• full-source-43耗时 1312.16 秒、峰值 RSS 217169920 字节，24786 个 User 原行、49572 个时间字段完整归档，最终错误为 Message 副本冲突及原插件业务门槛，同样没有 PREPARED。

一个反复出现的数字要正确解读：335099 是保留的业务消息条数，1,005,297 是三节点全部消息副本之和（三副本会计三次）；6499231 行归档包含原始物理记录及迁移证据，不是业务消息条数；plugin_business_rows是物理插件记录数，不是逻辑绑定数。逻辑消息数与所有副本之和不同——这正是"不以单节点物理行数充当逻辑总量"的落点。

七、结论：离线闭环已完成，切换仍需三个前置条件

从台账可以得出一个清晰的阶段结论：

1. 隔离功能验收已完成：权威源一致性、活动插件（唯一已批准程序）、真实源转换与离线导入闭环、消息规则与序号映射、隔离运行、原生故障恢复与拓扑矩阵（1→1 / 1→3 / 3→1 / 3→3 / 3→5）均拿到可复现证据；
2. 测试服务器迁移已完成：deployment-57迁入/root/wukongim并保留运行；
3. 生产切换仍未完成，且台账明确了三个前置条件：业务客户端缓存适配（按迁移代次清旧消息缓存与序号游标、保留凭据）须由实际客户端接入并阻止旧版本携带旧游标回连；指定切换窗口内的业务验收须完成；100 GiB / 4 小时性能验收等待测试环境。

换言之，"离线数据相等（offline_verified）"与"服务已通过业务验收"是两件事——cutover_ready: false是有意保留的边界。对于任何计划迁移 WuKongIM v2 到 v3 的团队，这份台账本身就是一份可复用的验收模板：把每项验收拆成"可执行的命令 + 可复现的数字 + 不可外推的边界"，成功与否只认退出码、最终 JSON 和源文件前后摘要。

• 即时通讯
• 后端