即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载本文围绕 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 配置命令第二轮按原序号比较限定频道的全部持久化字段摘要。它对每个带迁移标记频道给出四类结论分类含义台账中的实际结果consistent_formal_replicas配置证据满足规则正式副本完全一致61 个学习者落后频道中 1002/1003 逐序号摘要一致learner_lag_only正式副本一致差异仅为学习者连续前缀落后61 个频道属于此类conflict配置矛盾、同序号内容不同或有额外消息071 个频道无同序号内容冲突insufficient_evidence缺配置日志、来源节点或明确转换依据1 个历史配置待解释频道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且必须比较原始业务字段及全部计划副本不能以单节点物理行数充当逻辑总量。真实数据的完整数字链如下阶段证据标识关键数字全量 preparevisibility-492051.775 秒、峰值 RSS 239648768 字节601 个源文件前后不变exportarchive-51322 个分片、6,499,231 行、2,676,562,798 字节importarchive-533 个隔离目标、1160.53 秒、源文件不变精确重试 368.99 秒独立 verifyverify-55全部 3 个节点、1,005,297 条消息副本、1559.179 秒、源文件不变台账还记录了两次真实教训首次归档导入因演练漏建目标父目录而停止未写目标数据archive-53 verify因只读 catalog 分页漏计失败修复后同一节点读到 5103 频道335099 消息。完整的中间过程见归档演练报告。消息副本差异的逐项定位见消息副本定位27 个不同值均为 Message Other 类别的频道尾部记录当前 Leader 尾部较大最大差距 1774 个缺失检查项对应 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的11标志或非空StreamNo识别。保留消息按原顺序连续编号 1…N原生 v3 首条新消息分配 N1每条普通会话的已读和删除位置映射为原位置之前含仍保留的消息数量。prepare 成功会输出带校验和的sequence_mapping并可从归档独立重建wkcli migrate export-map --plan /absolute/plan.json \ --workspace /absolute/map-workspace --archive /absolute/source-archive2.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 为907cb6de4a98d04c1101a440fe7f5d155e1b7ffd37960153f8cd476d7d120207Linux 迁移工具 SHA256 为1faa67d91a29a4014ee327e395817e0ec6e8995a1b63fb1325655b9d2b46f120。台账特别记录此前因本机磁盘耗尽失败的检查已保留日志清理可重建缓存后完整重跑通过不算作成功证据。四、已有明确证据的基础问题与语义边界台账单列了三个已有明确证据的基础问题RedDot 使用 v3 原生字段保留通用冷历史恢复已独立复现与修复空历史 API 同步 main 既有修复并通过普通空频道及全流消息排除后的单节点/三节点 HTTP、追加和重启测试。同时台账用四条读报告纪律避免误读prepare现在保留插件失败但将其延后到可独立进行的源副本检查之后并与后续错误共同报告。replica_comparison_complete仅表示原业务副本比较完成plugin_business_rows是原始物理插件记录数不是逻辑绑定数。插件不兼容时 selection digest 为空转换和导出拒绝且不发布workflow/PREPARED。失败 CLI 可以输出statusblocked的部分证据退出码仍为 1。这些语义在源码中有直接对应。迁移计划结构定义在 internal/usecase/migration/workflow.goPlan包含Sources、Target、Exclusions、Messages、Metadata、History、PluginNodes、PluginConfigs、PluginArtifacts等字段ReadPlan同文件 L52-L97拒绝未知字段、固定version1、把source_commit钉定到固定 v2 schema 提交并限制源节点数量1–1024、分片数1–1024和绝对路径。SourceSelection结构定义在 internal/usecase/migration/selection_types.goReplicaComparisonComplete被显式注释为仅诊断证据兼容阻断仍阻止 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构建方式GOWORKoff go build -o /srv/tools/wkcli ./cmd/wkcli GOWORKoff 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.jsonverify成功为退出码 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→3 / 3→1 / 3→3 / 3→5均拿到可复现证据测试服务器迁移已完成deployment-57迁入/root/wukongim并保留运行生产切换仍未完成且台账明确了三个前置条件业务客户端缓存适配按迁移代次清旧消息缓存与序号游标、保留凭据须由实际客户端接入并阻止旧版本携带旧游标回连指定切换窗口内的业务验收须完成100 GiB / 4 小时性能验收等待测试环境。换言之离线数据相等offline_verified与服务已通过业务验收是两件事——cutover_ready: false是有意保留的边界。对于任何计划迁移 WuKongIM v2 到 v3 的团队这份台账本身就是一份可复用的验收模板把每项验收拆成可执行的命令 可复现的数字 不可外推的边界成功与否只认退出码、最终 JSON 和源文件前后摘要。赞分享即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载相关推荐FlashKDA开发者上手指南读懂cutlass子模块与csrc代码组织FlashKDA开发者上手指南读懂cutlass子模块与csrc代码组织 FlashKDA 是 Moonshot AI 开源的高性能 Kimi Delta A即时通讯后端WuKongIM v2→v3 迁移拓扑恢复验收全解析从故障矩阵到最终通过WuKongIM v2→v3 迁移拓扑恢复验收全解析从故障矩阵到最终通过 导读 本文基于 WuKongIM 仓库中 v2→v3 迁移拓扑恢复验收报告 http即时通讯后端JAX 原语Primitives完全指南从自定义 primitive 到 jit/grad/vmap 全变换支持JAX 原语Primitives完全指南从自定义 primitive 到 jit/grad/vmap 全变换支持 导读 本指南基于 JAX 官方教程 do即时通讯后端上一篇ComfyUI IPAdapter Plus终极指南5步快速掌握图像引导生成技术下一篇Jellyfish 前端架构实战指南React 18 TypeScript Vite 驱动的 AI 短剧工作台页面组织、请求层与状态管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考