v2 → v3 离线迁移

本文用一个具体例子，把原 v2 的用户、凭据、会话和消息迁入全新 v3 单节点集群。按顺序操作：备份 → 写计划 → 跑迁移 → 启动验收 → 切换。

多节点集群请使用迁移参考中的三节点计划，列全所有来源节点，在一台迁移机统一执行；不要按本例只取一个节点的数据。

本次实战用什么环境

下面假设你有一台独立的 Linux 迁移机，迁移完成后也在这台机器上启动 v3。示例不包含插件和外部集成，先在隔离环境演练。

你需要把 v2 主机名、原数据目录、节点 ID、分片数换成实际值。其余路径可以沿用本例；以下命令在迁移机有权写入 /srv 的 Bash 终端中执行。

开始前确认三件事：

• 来源已完整停机，目标是全新空集群。 v3 不能直接打开 v2 数据目录，也不支持在线增量迁移。
• 按 wkcli 安装说明准备同一版本的 wkcli 和 wukongim，并核对交付摘要。当前文档版本为 v3.0.0-beta.21。其他 v2 版本、自定义构建、有插件或外部集成的部署，先查兼容性要求。
• 磁盘要同时容纳完整冷备、工作空间、归档、目标数据和验收前快照。先演练测量峰值空间和完整耗时，再确定正式停机窗口。

1. 取一份完整冷备

先在原部署停止业务写入口，等待日志应用、拓扑变更和通知队列排空，再正常停止 v2 并关闭自动拉起。保留旧程序、配置和环境变量。下面复制的是已经停止变化的数据目录，不能对运行中的库直接复制。

在迁移机执行：

umask 077
mkdir -p /srv/v2-snapshots/node1001/data
rsync -a --numeric-ids --partial \
  root@v2-a:/opt/wukongim/data/ /srv/v2-snapshots/node1001/data/

复制成功后，再校验一次：

rsync -anc --numeric-ids --delete --itemize-changes \
  root@v2-a:/opt/wukongim/data/ /srv/v2-snapshots/node1001/data/

通过标准：退出码为 0，且没有文件差异输出。 这里的 -n 表示只检查，不会删除文件。路径末尾的 / 要保留；不要只复制消息文件或漏掉隐藏文件。已有完整冷备时，直接从冷备位置复制即可，不需要重启 v2。

演练取完冷备后可以恢复原 v2 业务。正式切换时必须再次停写、停机，取得最新冷备，用新的工作目录重做后续步骤；演练期间新增的数据不会自动补进旧迁移结果。

2. 保存迁移计划

先检查工具并创建本次工作目录：

wkcli version --output json
wukongim version --output json

两个程序的 version、commit、build_source 必须一致。确认后执行；如果 /srv/wkmigrate 已存在，换一个新路径并同步修改下文路径，不要覆盖上次结果。

mkdir /srv/wkmigrate && mkdir -p /srv/wkmigrate/{reports,work,targets}

将下面内容保存为 /srv/wkmigrate/plan.json，修改来源节点、分片数和本次创建时间：

{
  "version": 1,
  "source_commit": "a888f89533d0e7d1b2030e06504ca97f1ad891d4",
  "sources": [
    {"node_id": 1001, "data_dir": "/srv/v2-snapshots/node1001/data", "shard_count": 8}
  ],
  "target": {
    "cluster_id": "migration-v3-new",
    "created_at": "2026-09-12T00:00:00Z",
    "slot_count": 12,
    "hash_slot_count": 256,
    "replicas": 1,
    "channel_replicas": 1,
    "nodes": [
      {"node_id": 1, "addr": "127.0.0.1:7001", "data_dir": "/srv/wkmigrate/targets/node1"}
    ]
  }
}

source_commit 是工具支持的 v2 读取规则，保持此值，不是填你猜测的镜像版本。目标使用 12 个物理 Slot、256 个逻辑哈希槽和 1 副本。所有路径都是迁移机上的绝对路径，互不包含；不要提前创建 targets/node1。

这份计划不启用去重、排除 CMD／流消息或重新编号。遇到兼容性阻塞，按文末说明处理，不要为了通过检查直接套用数据丢弃策略。

3. 执行迁移，看到 offline_verified

保持 v3 停机，在迁移机一次执行下面的命令块。某一步失败会立即停止，报告保存在 reports 目录中。

(
  set -e
  umask 077
  wkcli migrate prepare --plan /srv/wkmigrate/plan.json \
    --workspace /srv/wkmigrate/work/prepare \
    > /srv/wkmigrate/reports/prepare.json 2> /srv/wkmigrate/reports/prepare.stderr
  wkcli migrate export --plan /srv/wkmigrate/plan.json \
    --workspace /srv/wkmigrate/work/prepare --archive /srv/wkmigrate/source-archive \
    > /srv/wkmigrate/reports/export.json 2> /srv/wkmigrate/reports/export.stderr
  wkcli migrate import --plan /srv/wkmigrate/plan.json \
    --workspace /srv/wkmigrate/work/import --archive /srv/wkmigrate/source-archive \
    > /srv/wkmigrate/reports/import.json 2> /srv/wkmigrate/reports/import.stderr
  wkcli migrate verify --plan /srv/wkmigrate/plan.json \
    --workspace /srv/wkmigrate/work/verify --archive /srv/wkmigrate/source-archive \
    > /srv/wkmigrate/reports/verify.json 2> /srv/wkmigrate/reports/verify.stderr
  cat /srv/wkmigrate/reports/verify.json
)

cutover_ready: false 是正常的：离线数据已经验证，接下来还要启动服务和验证业务。保留冷备、归档、计划和所有报告。

4. 启动 v3，验证真实业务

首次启动会改变数据库。先保存一份校验通过且从未启动过的目标快照；在本例中，确认快照路径不存在后执行：

test ! -e /srv/wkmigrate/targets-before-start && \
  cp -a /srv/wkmigrate/targets /srv/wkmigrate/targets-before-start && \
wukongim config init --config /srv/wkmigrate/wukongim.toml

确认快照复制成功，并保存初始化时显示的管理员密码。编辑生成的 wukongim.toml，修改以下两处，保留其余配置及生成的密钥：

同时核对生成值与计划一致：node.id=1，cluster.listen_addr="127.0.0.1:7001"，cluster.nodes=[{id=1,addr="127.0.0.1:7001"}]，initial_slot_count=12、hash_slot_count=256、slot_replica_n=1、channel_replica_n=1。保留 gateway.token_auth_on=true。若原 v2 的 whitelistOffOfPerson=false，还需设置 message.person_whitelist_enabled=true。

确认没有遗留的 WK_ 环境变量覆盖这些值，然后校验并前台启动：

wukongim config validate --config /srv/wkmigrate/wukongim.toml && \
  wukongim -config /srv/wkmigrate/wukongim.toml

保持这个终端运行，在迁移机另开一个终端检查：

curl --fail http://127.0.0.1:5001/readyz

/readyz 成功后，用你自己的客户端或 Chat Demo验证下面四项。默认仅监听回环地址；远程访问可按 Linux 部署使用 SSH 转发。

• **能登录：**用原 UID、原 Token 和相同 device_flag 登录，错误 Token 应被拒绝；不要重新注册账号覆盖原凭据。
• **旧数据正确：**检查单聊和群聊的早期、最近及跨页消息，核对正文、消息 ID、序号、会话列表、已读和未读状态。
• **能继续收发：**在隔离演练数据上发新消息，确认接收、未读数和重试去重正确，新序号大于原频道当前尾部。
• **重启后还在：**正常停止并重新启动 v3，再次检查历史、新消息和未读状态。

本例的写入验收用于演练。正式迁移也要完成验收，但写入测试应使用隔离副本；生产目标在切换前保持无业务写入。已启动的目录不能再作为初始导入状态执行 verify，也不能再次 import 覆盖。

5. 正式切换

完成演练后，在正式停机窗口使用最新完整冷备和新的工作目录重做迁移，完成离线校验及运行、客户端验收。保持原 v2 停写，将 v3 按 Linux 部署交给服务管理器运行，确认它使用已校验的配置和同一数据目录，再把业务后端与客户端的连接／路由入口指向 v3，逐步恢复流量。

如果使用了参考页中的重新编号策略，切换时还要处理客户端历史缓存和同步游标，保留登录凭据，并先安置未发送消息及草稿。工具不会自动清理客户端缓存。

v2 与 v3 不得同时接收同一业务的写入。 v3 接收新生产写入之前，可以关闭 v3 入口，按演练流程恢复原 v2 数据、程序及路由；之后不能直接切回旧 v2，否则会丢失新数据。工具不提供 v3 → v2 反向增量迁移。

卡住了，先看哪里

例如 prepare 失败，先查看这两个文件：

cat /srv/wkmigrate/reports/prepare.stderr
cat /srv/wkmigrate/reports/prepare.json

其他阶段换成对应文件名。保留失败现场和日志，不要重复整段命令覆盖报告，也不要删除源数据或修改标记强行通过。

完整的重试条件、插件策略、数据转换和业务验收清单均在迁移参考中，按遇到的问题查阅即可。