即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载本文基于 WuKongIM 仓库内的迁移诊断报告《消息协议字段排除 CMD、去重后的影响》整理并扩充。该报告记录了 2026-09-07 在codex/v2-v3-migration工作树中对三个真实停机源节点镜像执行的只读扫描、协议字段影响统计与原生行为复现实验。文中所有结论均以仓库内报告、wkcli migrate实现源码与原生存储/复制代码为依据可作为理解 v2→v3 离线迁移中消息协议兼容边界、规划dedupe-plan报告与 RedDot 保留修复的参考资料。背景为什么需要评估排除 CMD、去重后的消息协议字段影响WuKongIM 从 v2 集群离线迁移到原生 v3 集群时迁移工具wkcli migrate见 migrate 命令实现只读取停机状态下的源数据库不修改 v3 存储逻辑也不新增字段丢弃规则。迁移前的关键问题不是有多少条消息而是当按已批准的策略排除了 CMD 消息、流消息并按规则去重之后剩余保留消息中还有哪些字段是原生 v3 读取/复制路径无法承载的。原文档明确界定了本轮的调查范围暂缓插件问题本轮只继续检查消息不修改 v3 存储逻辑不新增字段丢弃规则用户此前已批准排除旧流分片/元数据、CMD以及按既定规则去重、映射序号。在此基础上报告回答了三个问题dedupe-plan报告如何统计字段影响真实停机备份中保留消息还剩哪些协议字段阻断原生存储路径对 RedDot / StreamNo 的真实行为是什么dedupe-plan报告升级按节点输出protocol_impactdedupe-plan是wkcli migrate的只读规划命令它在独立工作空间中生成 SHA-256 绑定的 JSONL 清单只做影响规划不生成 PREPARED、转换完成标记或目标数据。本轮将报告升级到 v3为每个节点新增protocol_impact统计。统计口径严格继承自原文档在已批准的 CMD 排除、重复消息候选选择之后分别统计保留消息和排除消息的字段同一条消息只在不兼容消息数量中计一次它的各字段分别计数即一消息多字段时消息数不重复累计每个字段最多保留三条不含正文/凭据的样本计数不依赖样本截断节点汇总进入 JSONL 和 SHA-256重跑具有确定性使用新的:dedupe-v3工作空间身份旧工作空间不能原地复用插件不参与本命令的业务放行退出码 0 只表示影响规划完整且无未决去重冲突不代表字段已经兼容。源码中的统计结构protocol_impact的数据结构定义在 dedupe_types.go其核心字段与报告口径一一对应// DedupeProtocolImpact separates retained-field blockers from rows omitted by // the requested policy. Counts are physical rows per node, not unique replicas. type DedupeProtocolImpact struct { Retained uint64 json:candidate_retained RetainedUnsupported uint64 json:candidate_retained_with_unsupported_fields RetainedFields map[string]uint64 json:retained_fields OmittedUnsupported uint64 json:candidate_omitted_with_unsupported_fields OmittedFields map[string]uint64 json:omitted_fields // Samples keeps at most three payload-free retained examples per field. Samples map[string][]DedupeMessage json:retained_samples }从实现上看RetainedFields/OmittedFields按字段名分别累计字段计数不依赖样本条数Samples每个字段最多保留三条不含正文/凭据的样例用于人工核对而不泄露消息内容报告结构DedupeReport同文件 L91-L107以CommandExitCode()决定命令退出码只要ScanComplete为假或存在Unresolved未决冲突退出码即为 1退出码 0 仅表示规划扫描完整。执行流程与工作空间身份dedupe-plan的实际执行入口在 internal/app/migration/app.go工作空间身份在计划摘要上追加:dedupe-v5原文档记录时点该身份为 v3后续因 RedDot 修复与报告演进升级到 v4、v5。核心扫描逻辑在 internal/usecase/migration/dedupe.go逐节点读取停机源的 Message 主行先封存文件清单摘要再对id与client两类去重键分组L126-L130随后统计每频道的候选删除与保留及序号影响。关键的一处实现细节在 dedupe.go 的 L298-L330被 CMD 或流策略排除的消息计入Omitted*统计而未被排除的候选保留消息计入Retained*统计两者分开计数确保排除策略本身不会污染剩余保留字段阻断的判断。真实停机备份扫描结果报告使用本机已经核对过的三个源节点镜像1001 / 1002 / 1003读取时仍进行停机文件清单和一致性检查所有节点数据摘要均与先前完整捕获相同。扫描结果如下源节点原消息物理行排除 CMD排除重复项候选保留保留且有 RedDot保留且有 StreamNo100133566016412473337723331121510023370201660248335112334452151003337021166024833511333445315报告对这张表给出了三条必须遵守的解读约束这些是每节点物理候选不能把三份副本相加当成最终业务消息数。本步骤没有重新完成权威副本选择不同节点的数量差异不在这里被擅自合并未决去重冲突为 015 条流主消息在每个节点均未被去重或 CMD 策略排除保留消息当前仅发现red_dot、stream_no两类协议字段阻断sync_once仅存在于已排除的候选中每节点同时有两种字段的主消息为一条字段数量不能直接相加当成不兼容消息数量。扫描的资源与完整性证据运行耗时 106.787 秒峰值 RSS 212992000 字节203.125 MiB运行参数GOMAXPROCS2、GOMEMLIMIT768MiB原文档明确注明这只是约 1.7 GB 源镜像的诊断扫描不能作为 100 GiB / 四小时完整迁移性能验收明细 SHA-256494ca7d75572ce93e2b362065442ace22650d280508c76b7aac2d0fc6b0badda私有证据位于tmp/server-rehearsal-20260907/messages-34/。15 条流主消息的实际内容扫描显示每个节点恰好有 15 条保留消息带 StreamNo且全部为流主消息。报告从已封存的原始行重新取出45 个物理副本逐行对照本轮摘要结论如下共 15 个不同 MessageID同一消息的三个副本字段摘要相同全部Setting2即旧流标记开启对应源码中的SettingStream 1 1见 pkg/protocol/frame/setting.go10 条原始主消息正文为零字节4 条为 39 字节1 条为 108 字节保留这 15 条主消息不会把已经获准排除的流分片内容重新合并进正文——本轮没有读取或恢复分片正文也没有把空主消息替换成编造的内容。由此得出一个重要结论清空 StreamNo本身并不等于转换成普通消息流标记仍然存在。若以后选择普通消息形式还需明确批准该标记的转换及其业务影响。原生行为复现ReadLog → ApplyFollower 会丢失旧消息字段为了证明底层列存在、写入成功不能替代完整读取/复制兼容性验证报告新增了隔离测试TestNativeFollowerRoundTripLosesLegacyMessageFields分别使用合成的 RedDot 消息与带 Setting2/StreamNo 的消息。复现步骤严格按五个阶段进行迁移工具按现有规则拒绝该消息实验绕过迁移准入仅向临时数据库直接写原有格式的完整消息行原生数据库读取确实能返回 RedDot/StreamNo写入和原有 version-1 proposal 均成功——但报告强调这不是迁移通过的证据经原生 ChannelReadLog→ApplyFollower写入另一临时数据库后MessageID、序号、正文和 Setting 保留但RedDot 变为 falseStreamNo 为空原生 Channel Message/Record DTO 也不承载这两个字段历史 API 读取适配器只从其中设置 SyncOnce没有补回历史 RedDot。测试通过证明不能以底层列存在、写入成功替代完整读取/复制兼容性验证。报告同时注明这是存储适配器实验不是一次新的真实集群故障恢复验收也没有修改该路径原生历史冷启动恢复问题继续作为独立未解决事项。源码侧的印证上述丢失行为可以从原生消息结构中得到印证。ReadLog/ApplyFollower对应的通道日志与复制路径使用 pkg/channel/types.go 中的Record结构承载复制数据其字段仅包含ID/Index/Epoch/Setting/Expire/FromUID/ClientMsgNo/ServerTimestampMS/SyncOnce/RedDot/Payload等没有 StreamNo 字段存储适配器 pkg/channel/store/channel_adapter.go 用encodeDBCompatibleFramerFlags把协议标志压缩进一个掩码字节RedDot 对应flags2历史上 RedDot 位在部分路径上并未完整贯通。这正是底层列存在、写入成功但完整读取后字段丢失的机制来源。RedDot 原值保留与 v3 通用修复原文档开头即附有后续更正用户已决定直接保留 RedDot此前RedDot 仅留档的建议已撤回。完整的修复过程记录在配套报告 RedDot 验证报告 中摘要如下通用 v3 修复在独立codex/red-dot-preservation工作树开发基线223d1eba2f7228806cfd2842d86dd60f9c7583f4同一补丁接入迁移工作树补齐 SendCommand → durable Message → Channel Message/Record → 已有FramerFlags掩码 0x02 的传递链以及持久化读取、复制、恢复、普通历史 API 返回路径复用已有存储位消息键、列、行编码、兼容消息格式、proposal/entry v1 摘要均未改变未新增 v2 专用存储路径未调整 v3 序号/追加校验规则Channel RPC 升级以携带 RedDot并对会丢失 true 值的旧版本编码明确报错Quorum Exchange 同步升级且不回退迁移工具不再把 RedDot 视为不兼容字段其他未支持字段仍阻止完成dedupe-plan报告/工作空间身份随之升级避免复用旧判断结果目标集群各节点必须统一使用修复版本已有 v3 的升级需要停流量并一起升级源 v2 不需要修改、启动或升级。需要特别强调的是现有 v1 proposal 摘要不包含 RedDot本次也没有改变其历史定义因此摘要相等不能单独证明该位相等迁移验收仍须独立比较完整消息字段。该修复不改变 v3 未读计数算法也不处理 StreamNo 或 CMD sync 的其他字段。验证与边界自动化测试迁移用例全包通过5.850 秒v2 适配器全包通过111.909 秒组合根、CLI 与命令包编译通过新测试最初使用错误的存储接收者方法导致 v3 测试包编译失败已改为该原生类型现有的GetMessageBySeq并让带 Setting2 的测试 proposal 使用对应的 Setting 值最终 v3 适配器全包通过6.145 秒包含流标记实验定向测试覆盖CMD/重复项与保留字段分开计数、两字段消息不重复计数、多副本隔离、样本上限、确定性重跑、CLI 接线和工作空间隔离275 个既有原生文件继续与基线ab1ced72450658ba85399b03293ac37c20278721逐字节相同后续 RedDot 修复的验证覆盖 API、节点 RPC、发送契约与运行时、集群适配器、Channel 全子树、Channel RPC、DB 全子树相关单元测试以及单节点/三节点集群从各入口发送 false/true 后从各入口读取历史的组合测试。未做的事项严格准入边界本轮没有运行现场插件、改动原始源库、导入现场 v3 或进行业务切换。报告同时把下列事项明确列为未完成验收三节点原生冷重启历史尾部可见性已由后续独立通用修复关闭见配套报告15 条主消息的 StreamNo/流语义兼容——没有获得清空字段或额外排除的授权暂缓中的插件完整兼容与其余全量 prepare 准入项100 GiB / 四小时性能验收、SDK 缓存/游标切换及最终现场全量迁移验收。待明确的数据策略保留而不是清除原文档对数据策略给出了明确的收尾结论这也是迁移操作中必须遵守的边界此前用户只批准排除旧流分片/元数据和 CMD以及按既定规则去重、映射序号并要求保留 15 条流主消息该授权不包含自动删除历史 RedDot、StreamNo 或 Setting 中的流标记此前提出的RedDot、StreamNo 与流标记仅留档方案没有获批现已撤回RedDot 按用户要求直接保留15 条流主消息继续保留StreamNo/流标记不得擅自清除原生历史冷启动问题和插件完整兼容分别保留准入边界任何迁移决策不得以底层能写入作为放行依据。与整体迁移流程的关系dedupe-plan只是wkcli migrate完整流程diagnose→authority→dedupe-plan→prepare→export→import→verify中的影响规划环节命令清单见 migrate 命令实现。其输出属于诊断/规划而非验收prepare阶段会在源检查开始后可能输出status: blocked预检并部分证据任何插件兼容阻断都会使选择摘要为空并阻止转换/导出实际的 CMD 排除、流消息识别与序号压紧由计划中的messages策略控制keep_latest_duplicates/exclude_cmd/exclude_streams/compact_sequences见 message_transform.go其中流消息按Setting (11) ! 0 || StreamNo ! 识别不根据正文猜测业务类型只有dedupe-plan的字段影响扫描与 prepare/import 的显式策略配合才能判断哪些字段会成为真正的迁移阻断哪些已被排除策略消化。操作者在使用相关命令时可参考 wkcli migrate 命令文档 中关于工作空间隔离、计划摘要与归档重建的要求修改任何消息策略都会改变计划身份必须使用新工作空间和新归档旧工作空间不能原地复用。小结WuKongIM v2→v3 迁移中的消息协议字段影响评估核心方法论可以概括为四句话先按已批准策略排除再统计剩余保留消息的字段阻断物理副本不合并、字段计数不冒充消息计数底层列存在、写入成功不等于读取/复制兼容未获授权的字段StreamNo/流标记一律保留不做擅自清除。dedupe-plan的protocol_impact报告把哪些消息被排除与哪些保留消息还带不兼容字段严格分开配合 RedDot 通用修复与配套验证报告为最终的迁移验收提供了可复核、可重跑的字段级证据链。赞分享即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载相关推荐WuKongIM v2→v3 迁移消息去重规划dedupe-plan与消息序号影响分析WuKongIM v2→v3 迁移消息去重规划dedupe plan与消息序号影响分析 导读 本文围绕 WuKongIM v2→v3 离线迁移中的消息去即时通讯后端WuKongIM v2→v3 离线迁移消息策略CMD 消息排除、最新重复保留与序号压紧实战解析WuKongIM v2→v3 离线迁移消息策略CMD 消息排除、最新重复保留与序号压紧实战解析 本篇技术指南聚焦 WuKongIM 从 v2 到 v3 离线迁即时通讯后端WuKongIM v2→v3 离线迁移流消息排除与频道连续序号保序方案WuKongIM v2→v3 离线迁移流消息排除与频道连续序号保序方案 导读 本文介绍 WuKongIM v2→v3 离线迁移中的一项关键业务策略 流消息即时通讯后端上一篇如何用Ice打造终极macOS菜单栏完整配置与使用指南下一篇League Akari英雄联盟LCU工具包本地数据处理提升游戏效率创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考