Redis 8.4 CLUSTER MIGRATION 怎么迁移槽位：IMPORT、STATUS 与 CANCEL 验收

Redis 集群做槽位调整的时候，传统多步操作很容易把“槽位标识已经修改”和“全量数据迁移完成”混为一谈。Redis 开源 8.4.0 新增的 CLUSTER MIGRATION 把槽位导入、任务状态查询和取消操作统一归到同一套迁移任务体系里：目标主节点用 IMPORT 接收指定槽位范围，拿到任务 ID 后用 STATUS 跟进进度，遇到异常再分别到源、目标节点执行取消操作。

Redis 8.4 的变化：槽位迁移变成可跟踪任务

CLUSTER MIGRATION 从 Redis 开源 8.4.0 开始提供。它的目标不是替代日常集群扩缩容的所有工具，而是把一次原子槽位迁移的启动、观察和取消动作统一起来。命令属于 @admin、@slow、@dangerous ACL 类别，生产账号不能只开读权限。

最小语法只有三个分支：

CLUSTER MIGRATION IMPORT start-slot end-slot [start-slot end-slot ...]
CLUSTER MIGRATION STATUS [ID task-id | ALL]
CLUSTER MIGRATION CANCEL ID task-id | ALL

先确认目标节点，再提交 IMPORT

IMPORT 要在目标 master 上发起。下面的例子把 0–1000 和 2000–3000 两段槽位交给当前节点；真实环境应先用 CLUSTER NODES 或集群管理工具确认当前连接确实落在目标节点。

redis-cli -h redis-target -p 6379 CLUSTER NODES
redis-cli -h redis-target -p 6379 \
  CLUSTER MIGRATION IMPORT 0 1000 2000 3000

成功返回的是任务 ID，不是“所有键已经迁完”的布尔值。把这个 ID 写入变更单，后续所有状态查询和异常处置都围绕它展开。

STATUS 看哪些字段，才不会误判迁移成功

先查全部任务，确认系统里没有上一轮遗留的重试：

redis-cli -h redis-target -p 6379 \
  CLUSTER MIGRATION STATUS ALL

再用任务 ID 精确查看。状态结果至少要核对 slots、source、dest、state、last_error、retries 和 write_pause_ms。其中 state=completed 只说明任务完成；如果 last_error 不为空，仍应停下变更，先查源节点和目标节点的日志。

写暂停是另一个容易漏掉的指标。Redis 文档给出的相关配置包括 cluster-slot-migration-handoff-max-lag-bytes 和 cluster-slot-migration-write-pause-timeout；前者影响何时进入交接，后者限制源节点暂停写入的最长时间。不要只看任务最终成功，还要把暂停毫秒数与业务峰值窗口对照。

迁移期间的键统计为什么会对不上

槽位导入或整理尚未完成时，KEYS、SCAN、DBSIZE、CLUSTER GETKEYSINSLOT 和 CLUSTER COUNTKEYSINSLOT 可能过滤掉未归属槽位的键。这不适合拿来做迁移中的最终数据核对。

INFO KEYSPACE 会继续反映实际键数。验收时建议把“命令视图暂时不完整”和“数据真的丢失”分开：等待任务完成后再做槽位级核对，并保留迁移前后的业务抽样读写结果。

异常时怎么 CANCEL，才能把重试链收干净

取消单个任务需要 task ID：

redis-cli -h redis-target -p 6379 \
  CLUSTER MIGRATION CANCEL ID 24cf41718b20f7f05901743dffc40bc9b15db339

如果要取消当前节点可见的全部任务，可以使用 CANCEL ALL。但不要把“源节点已经取消”当成整次迁移结束。Redis 官方说明：源节点取消不会自动停止目标节点上的迁移，目标端可能继续重试。因此故障处置至少按下面顺序复查：

1. 在发起 IMPORT 的目标 master 上查询任务状态并取消。
2. 在原持有槽位的源 master 上查询同一个 task ID，确认没有继续重试。
3. 两端再次运行 STATUS ALL，记录 state、last_error 和 retries。
4. 恢复业务读写后，再做槽位归属、热点 key 和应用错误率核对。

上线前的最小验收清单

• 版本：目标节点和源节点均确认支持 Redis Open Source 8.4.0 或更高版本。
• 权限：变更账号具备 CLUSTER MIGRATION 所需管理权限，并且审计记录包含 task ID。
• 任务：STATUS 显示 completed，last_error 为空，retries 没有持续增长。
• 业务：写暂停时长落在业务可接受范围，错误率和延迟没有跨过发布门槛。
• 回退：源、目标两端都能查询并取消任务，值班人员知道取消不会自动传播。

常见问题

CLUSTER MIGRATION 是 Redis 7.4 的命令吗？

不是。官方命令文档标注它从 Redis Open Source 8.4.0 开始提供，旧版本应继续使用与自身版本匹配的集群迁移方案。

IMPORT 返回 task ID 后能马上切换流量吗？

不建议。task ID 只代表任务已创建；至少要等 STATUS 的 state 完成，并结合错误字段、写暂停和业务指标做验收。

为什么 STATUS 的 last_error 为空仍要看 retries？

空错误字段代表当前没有记录错误，但 retries 能帮助发现迁移过程是否反复尝试。两者应和 state 一起判断。

取消源节点上的任务后还会继续迁移吗？

可能会。目标节点上的任务不会因源节点取消而自动停止，必须到目标端再次查询并按 task ID 处理。

Redis 8.4 的这个能力适合把槽位调整纳入可审计的变更流程。真正的完成标准不是命令返回成功，而是任务状态、错误字段、暂停窗口、槽位归属和业务指标都能对上。