企业官网建设流程全解析

• 即时通讯
• 后端

本指南基于 WuKongIM 仓库中 deployment-57（2026-09-08）的实测迁移记录，完整还原将 v2 测试环境数据迁入 v3 三节点集群的流程：从初始产物复用与 SHA256 全量校验、原 v3 环境备份与新产物部署，到凭据、历史、收发、重启、插件、缓存、网络入口、集群健康与监控的逐项目录验收，最后给出交付物与证据留存规范。读完本文，你将掌握一套可复用的“v2 → v3 服务器迁移 + 验收 + 证据封存”完整操作框架，并理解每个验收项背后的源码级判定依据。

迁移背景与目标定义

本次迁移发生在 2026-09-08，对应部署标识deployment-57。用户已明确确认两个目录均为测试环境，并要求把/root/wukongim_v2_bak下的 v2 数据迁入/root/wukongim下的 v3 环境。本次操作的目标是：

• 完成目标目录的测试切换；
• 保留迁入后的三节点集群持续运行；
• 对后续仍会进行的 Demo 验收、嵌入页面程序摘要及新发现的单节点故障未通过项，不在本次结论中提前判定（详见 Chat Demo 验收报告）。

需要特别强调的是，本次记录的是 deployment-57 当时的结果，不能覆盖或替代后续高可用故障观察。这是一次受控的“环境切换”，而非对集群高可用能力的最终认证。

数据来源与产物复用策略

不复跑全链路，复用已验证初始产物

本次迁移复用了由visibility-49生成、verify-55已完整独立校验、且从未启动过的初始迁移产物，没有重新运行整套prepare → export → import → verify流程。这与仓库中的迁移演练工具链完全对应：

• scripts/migration/README.md 中的rehearse-offline.py描述的正是prepare → export → import → retry → verify五段式离线迁移流程；
• 该脚本要求迁移前用sha256sum -c SHA256SUMS在解包目录内校验交付 tarball，且冻结源端——从迁移开始到结束，v2 源必须始终保持停机、不允许升级或改写。

本次部署严格执行了上述纪律，具体核对动作包括：

• 源备份逐文件核对：原 v2 共601 个数据文件、1,704,886,531 字节，迁移前后 SHA256 全部一致；原 v2 始终停机，期间没有升级、启动或改写源备份。
• 初始产物再核对：255 个初始数据文件与原完整校验（verify-55）时一致；数据、配置及程序共262 个上传文件在服务器上再次核对大小、权限和 SHA256。
• 加载检查：服务器端 Compose 配置与产品配置加载检查均通过。

消息量与副本数的对应关系

初始产物保留了335,099 条消息，而全部1,005,297 条消息副本的独立校验来自 verify-55。注意这两者的数量关系：335,099 × 3 = 1,005,297，恰好对应三节点集群下每一条业务消息的 3 份频道副本（channel_replicas = 3）。仓库迁移工具在已知权威保留数时要求验证结果报告N × channel_replicas条消息副本，与本次数字完全吻合。

该校验遵循最终批准规则：排除 CMD 消息、协议流消息和重复记录，压紧序号，并沿用读删位置映射。

切换前的环境备份

正式部署前执行了以下切换动作：

1. 停止原 v3 三节点及本项目 Prometheus；
2. 将原data、conf、compose.yaml和监控配置完整保留到/root/wukongim/migration-backup-20260908-57；
3. 再部署新产物；
4. 不合并、不覆盖旧 v3 业务库，也不操作其他项目的容器。

候选二进制与运行版本核实

三个节点运行的是同一配套候选二进制，SHA256 为：

907cb6de4a98d04c1101a440fe7f5d155e1b7ffd37960153f8cd476d7d120207

核实方式是读取三个运行进程的/proc/<pid>/exe并逐一比对摘要，均与该值匹配；其源码对应提交为655d10028。这一做法的要点在于：Docker 镜像只提供运行环境，候选程序由迁移目录挂载，因此不能仅以基础镜像标签判断版本——必须校验实际运行的进程可执行文件。

这也与迁移工具的约束一致：scripts/migration/README.md 要求--wkcli-sha256与--wukongim-sha256参数必须取自批准交付记录中的二进制哈希，而非不可信文件；并且迁移后的目标节点必须使用同一个交付的wukongim启动，集群 ID、节点 ID、地址、数据路径、Hash Slot 与副本数保持一致。

端口、地址与网络拓扑保留

本次迁移完整保留原对外端口：

安全边界方面：管理账号沿用原配置，三个节点启用原凭据验证；API 节点 2/3 及 Prometheus 9091 仅监听 loopback，不对外暴露。

内部集群拓扑沿用初始产物的已校验计划：节点编号、集群 ID 和内部地址不变，内部地址为127.0.0.1:27101 / 27102 / 27103。由于采用 host 网络，Compose 相应改为 host 网络模式，并同步调整 Prometheus 抓取地址。关键原则是：本次部署没有改写迁移标记或数据库中的集群地址来放宽校验——地址不匹配不应通过篡改数据来绕过，而应通过部署方式（如 host 网络）来适配。

仓库中的三节点示例配置 cmd/wukongim/wukongim-node1.toml.example 展示了同样结构：三节点内部地址（示例为127.0.0.1:7011/7012/7013）、hash_slot_count = 256、slot_replica_n = 3、join_token首次初始化使用，且注释明确指出initial_slot_count仅在首次初始化时生效，已有集群会保留持久化的 Slot 数——这解释了为何迁移部署沿用初始产物计划中的 Slot 数而不重新初始化。

实际目录验收：逐项结果与判定依据

迁移完成后，验收团队按下列维度逐项核验，结果如下：

下面对几个关键项补充源码级判定依据。

readyz 返回 200：公开就绪探针

“公开 API readyz 返回 200”对应仓库中的就绪路由实现 internal/access/api/server.go：handleReadyz调用注入的readyz函数，就绪时返回 HTTP 200 与就绪体，未就绪时返回 HTTP 503。该路由与/healthz、/metrics等一同注册为公开 API 路径，可作为负载均衡与监控的公开入口探针。

鉴权失败原因码 2：ReasonAuthFail

“错误 token 被明确拒绝，鉴权失败原因码 2”可在协议层得到精确对应。在 pkg/protocol/frame/common.go 中，ReasonCode为 uint8 枚举：

ReasonUnknown ReasonCode = iota // 0 未知错误 ReasonSuccess // 1 成功 ReasonAuthFail // 2 认证失败

即原因码2 正是ReasonAuthFail（认证失败）。该原因码在消息发送路径上同样生效：未认证会话的 SEND 会被适配层转换为 SENDACK 结果而非原始协议错误，返回ReasonAuthFail（见 internal/access/gateway/handler.go 与 internal/access/gateway/FLOW.md）。网关侧的token_auth_on开关（见 cmd/wukongim/wukongim.toml.example）要求每个客户端 CONNECT token 与同一 UID/device_flag 下持久化的设备 token 匹配，注释明确提示：仅在受控的兼容迁移期可临时关闭，否则会移除身份校验——本次“错误凭据被拒”的验收结果正是该机制在迁移后的实测验证。

集群健康：quorum ready 与 sync matched

“10 物理 Slot、256 Hash Slots，每 Slot 的 3 个投票副本健康、quorum ready、sync matched”的判定逻辑对应 internal/infra/cluster/opsobserve.go：

• 当某个 Slot 的Quorum == "lost"或Sync == "mismatch"时，集群健康状态降级为degraded（slot_health_degraded），阈值描述为 “quorum ready and assignment matched”；
• 当Quorum != "ready"或Sync != "matched"时，标记为unknown（slot_health_missing）。

因此验收表中的“quorum ready、sync matched”即每个 Slot 的投票副本组达成法定人数、且复制同步处于匹配状态的源码级健康判据。Slot 维度分布式元数据的设计说明可参考 pkg/slot/BOUNDARY.md：每个 Slot 维护独立的 Raft 组，写路径按实体 key 计算 HashSlot 路由，256 个 Hash Slots 与示例配置 cmd/wukongim/wukongim-node1.toml.example 中的hash_slot_count = 256、slot_replica_n = 3一一对应。

旧缓存重置与序号延续

“旧尾序号 150 的频道保留 147 条；清缓存/游标、保留凭据、重载重新同步后新增序号 148、未读 1”验证了迁移后的序号续接能力：历史消息被压紧重排后，客户端清除旧消息缓存与序号游标、同时保留登录凭据，即可基于新的尾序号继续收发，新增消息序号严格大于原频道尾序号，未读数正确累积。这也符合迁移工具 README 的验收指引：检查每个新message_seq严格大于前一频道尾序号，恢复会话/读位置，新对端消息正确计入未读。

探针消息与验收边界

验收探针共新增10 条测试业务消息，保留供后续复查。本次没有认证未知业务 App 的缓存表/键或平台 SDK；浏览器使用私有缓存探针验证已批准的清理规则。需要注意的边界是：已运行的数据目录不再是初始导入状态，不能重新当作未启动产物执行初始化 verify——即“离线校验通过”不等于“流量切换批准”，运行态数据不能再走初始化校验路径。

交付物与证据体系

服务器端交付

服务器当前运行目录为/root/wukongim。工具、程序、说明和结果摘要位于：

/root/wukongim/migration-20260908-57/

其中README.md说明入口、运行管理、备份位置及恢复旧测试环境的步骤；evidence/保存通过结果及校验和。服务器端已检查证据校验和，且 Linux 迁移工具的帮助命令执行成功。

本机私有证据

本机私有证据保存在工作树tmp/server-rehearsal-20260908/deployment-57/，包括：

• deployment-result.json：部署结果；
• accept-result.json：验收结果；
• source-before.json/source-after.json：迁移前后源备份清单（用于前后比对）；
• verify.json：校验结果；
• invalid-token.json：错误凭据拒绝记录；
• health-private.json：私有健康检查记录；
• EVIDENCE_SHA256SUMS：证据校验和清单；
• private-server-logs.tar.gz：私有服务器日志压缩包。

凭据、配置、历史内容及运行日志不提交仓库，保证私密性。这与迁移工具 README 的证据要求一致：输出目录使用 0700 权限与严格文件权限，保留inputs.json、status.json、各阶段 JSON 结果、执行记录与容器检查记录；带校验和的归档与序列映射是必需的迁移产物。

边界声明与后续事项

1. 性能验收延后：本次验证的是指定测试环境的实际部署，100 GiB / 4 小时的性能验收仍按约定延后，本文不构成性能结论。
2. 高可用未最终认证：新发现的单节点故障未通过项与后续实际 Demo 验收，见 Chat Demo 验收报告。
3. 离线校验≠流量切换：offline_verified不是流量切换批准；启动新目标前必须保留已校验的停机版本或完整可复现归档与证据，并使用同一交付二进制启动全部节点。

整套流程沉淀下来的核心经验是：迁移的成功不取决于“跑通”，而取决于每一环节可核对、可复现、可回滚——源端全程冻结并前后 SHA256 一致、初始产物经独立校验、运行二进制以/proc/<pid>/exe实测、验收逐项落到协议原因码与集群健康状态、证据与凭据分离留存。这套方法可直接迁移到同类多节点 IM 集群的版本升级与数据搬迁场景。

• 即时通讯
• 后端