Redis MIGRATE 命令详细教程MIGRATE用于将一个或多个 Key 从当前 Redis 实例原子地迁移到另一个 Redis 实例。迁移过程中 Key 不会同时存在于两个实例操作是原子的在任意时刻Key 要么在源实例要么在目标实例。MIGRATE常用于在线数据迁移、集群扩容、数据搬迁等场景。本文基于 Redis 通用 Key 操作介绍MIGRATE。Redis 命令本身不区分大小写因此MIGRATE、migrate和Migrate的效果相同文档统一使用大写形式。MIGRATE自 Redis 2.6 起可用COPY、REPLACE选项从 Redis 3.0 开始支持KEYS选项从 Redis 3.0.6 开始支持AUTH从 Redis 4.0 开始支持AUTH2从 Redis 6.0 开始支持。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、命令概览1. 基本语法MIGRATE host port key| destination-db timeout [COPY] [REPLACE] [AUTH password | AUTH2 username password] [KEYS key [key ...]]参数说明参数说明host目标 Redis 实例的主机地址port目标 Redis 实例的端口key要迁移的单个 Key或使用空字符串配合KEYS选项迁移多个 Keydestination-db目标实例的逻辑数据库编号如0、1timeout超时时间单位为毫秒是 I/O 操作的最大等待时间COPY迁移后不在源端删除 Key默认行为是删除源端 KeyREPLACE替换目标实例上已存在的同名 Key默认遇到同名 Key 会返回错误AUTH password目标实例的密码认证Redis 4.0AUTH2 username password目标实例的 ACL 用户名和密码认证Redis 6.0KEYS key [key ...]迁移多个 Key此时key参数传空字符串返回值场景返回值迁移成功OK源端 Key 不存在NOKEY2. 最简单的示例假设目标实例运行在192.168.1.100:6380将当前实例的user:1001迁移过去SET user:1001 Alice MIGRATE 192.168.1.100 6380 user:1001 0 5000返回OK迁移成功后user:1001从当前实例删除出现在目标实例的DB 0中。在目标实例上验证SELECT 0 GET user:1001返回Alice二、MIGRATE 的基本用法1. 迁移单个 KeySET session:abc123 token-data MIGRATE 192.168.1.100 6380 session:abc123 0 5000返回OK表示迁移成功。迁移后源端session:abc123不存在EXISTS返回0。目标端DB 0session:abc123存在EXISTS返回1。2. 源端 Key 不存在迁移不存在的 KeyMIGRATE 192.168.1.100 6380 no-such-key 0 5000返回NOKEYNOKEY表示源端没有找到指定的 Key迁移未执行。3. 迁移到不同的逻辑数据库将 Key 迁移到目标实例的DB 1SET cache:item data MIGRATE 192.168.1.100 6380 cache:item 1 5000迁移后 Key 出现在目标实例的DB 1中。4. 超时时间timeout单位为毫秒是 I/O 操作连接、传输的最大等待时间。对于大 Key 的迁移需要设置较大的超时时间MIGRATE 192.168.1.100 6380 big-list-key 0 30000设置 30 秒超时。超时后迁移可能失败或返回错误。5. COPY — 保留源端 Key默认情况下MIGRATE会从源端删除 Key。使用COPY选项后源端 Key 不会被删除SET user:1001 Alice MIGRATE 192.168.1.100 6380 user:1001 0 5000 COPY迁移后源端user:1001仍然存在。目标端user:1001也存在。相当于复制 Key 到目标实例。6. REPLACE — 替换目标端同名 Key默认情况下如果目标端已存在同名 KeyMIGRATE会返回错误。使用REPLACE选项可以强制覆盖MIGRATE 192.168.1.100 6380 user:1001 0 5000 REPLACE迁移后目标端的同名 Key 会被新值覆盖。7. COPY 和 REPLACE 组合使用MIGRATE 192.168.1.100 6380 user:1001 0 5000 COPY REPLACE保留源端 Key同时覆盖目标端的同名 Key。三、迁移多个 Key从 Redis 3.0.6 开始可以使用KEYS选项迁移多个 Key。此时key参数传空字符串1. 基本用法SET user:1001 Alice SET user:1002 Bob SET user:1003 Charlie MIGRATE 192.168.1.100 6380 0 5000 KEYS user:1001 user:1002 user:1003返回OK三个 Key 同时迁移到目标实例。如果在迁移过程中任何一个 Key 在源端被修改或删除整个迁移操作会失败。2. 部分 Key 不存在多 Key 迁移时部分 Key 不存在不会导致失败不存在的 Key 会被跳过MIGRATE 192.168.1.100 6380 0 5000 KEYS user:1001 not-exist user:1002存在的 Key 正常迁移not-exist被跳过。如果所有 Key 都不存在返回NOKEY。3. 与通配符的区别KEYS选项接受的是明确的 Key 列表不是 glob 模式。不能直接使用user:*作为模式# 错误user:* 不是通配符模式而是字面 Key 名称 MIGRATE 192.168.1.100 6380 0 5000 KEYS user:* # 正确使用 SCAN 获取 Key 列表然后逐批迁移如需按模式迁移先用SCAN获取匹配的 Key 列表再批量传入MIGRATESCAN 0 MATCH user:* COUNT 100 # 获取 Key 列表后 MIGRATE 192.168.1.100 6380 0 5000 KEYS user:1001 user:1002 user:1003四、认证选项1. AUTH — 密码认证目标实例设置了requirepass时使用AUTH选项提供密码Redis 4.0MIGRATE 192.168.1.100 6380 user:1001 0 5000 AUTH mysecret2. AUTH2 — 用户名和密码认证目标实例启用了 ACLRedis 6.0使用AUTH2选项提供用户名和密码MIGRATE 192.168.1.100 6380 user:1001 0 5000 AUTH2 migrate-user mysecret3. AUTH 与 AUTH2 不能同时使用AUTH和AUTH2互斥根据目标实例的认证方式选择其一。五、MIGRATE 的原子性1. 原子迁移保证MIGRATE是原子操作。在迁移过程中Key 在源端和目标端的状态变化如下阶段源端状态目标端状态迁移前Key 存在Key 不存在或不使用 REPLACE 时报错序列化传输中Key 仍存在Key 不存在目标端写入完成Key 仍存在Key 存在源端删除完成Key 已删除Key 存在在任意时刻Key 要么存在于源端要么存在于目标端或极短的两者都存在过渡状态。2. 失败回滚如果迁移过程中发生错误如目标端不可达、超时等MIGRATE会返回错误信息。源端 Key 不受影响仍然存在。目标端可能没有 Key如果迁移未完成。3. 大 Key 的迁移大 Key如包含百万元素的 Hash、List、Set的迁移可能需要较长时间。MIGRATE的实现方式是在源端执行DUMP序列化 Key 的值。将序列化数据传输到目标端。在目标端执行RESTORE反序列化并恢复。确认目标端恢复成功后从源端删除 Key。对于大 Key确保设置足够的timeout值避免因超时导致迁移失败。六、MIGRATE 与相关命令的区别1. MIGRATE 与 DUMP RESTOREMIGRATE内部使用的就是DUMPRESTORE的组合但封装成了原子操作# MIGRATE 内部等效流程简化 DUMP key # 源端序列化 DEL key # 源端删除 RESTORE key 0 dump-data # 目标端恢复手动分步执行DUMPRESTORE不是原子的中间可能出现数据丢失或竞态条件。优先使用MIGRATE。2. MIGRATE 与 COPY特性MIGRATECOPY操作范围跨实例迁移同实例内复制源端 Key默认删除COPY 选项保留保留目标端另一个 Redis 实例当前实例的不同 Key 名原子性原子操作原子操作COPY用于同实例内复制 KeyMIGRATE用于跨实例迁移 Key。3. MIGRATE 与 CLUSTER SETSLOT在 Redis Cluster 中CLUSTER SETSLOT用于槽位迁移。内部也会使用MIGRATE来迁移属于该槽位的 Key。MIGRATE是底层迁移机制CLUSTER SETSLOT是集群层面的管理接口。4. MIGRATE 与 MOVEMOVE将 Key 在同一实例的不同逻辑数据库之间移动而MIGRATE跨实例迁移MOVE user:1001 1 # 移动到当前实例的 DB 1 MIGRATE 192.168.1.100 6380 user:1001 1 5000 # 迁移到远程实例的 DB 1特性MIGRATEMOVE跨实例是否原子性原子原子目标端另一个 Redis 实例当前实例的不同 DB大小限制适合大 Key适合单个 Key适用场景数据搬迁、迁移逻辑库间转移七、不同数据类型的迁移MIGRATE可以迁移任意数据类型的 Key包括 String、Hash、List、Set、Sorted Set、Stream 等。迁移过程对数据类型透明——序列化和反序列化保留了完整的数据类型和内部编码。HSET user:1001 name Alice age 30 MIGRATE 192.168.1.100 6380 user:1001 0 5000RPUSH queue:jobs job-a job-b job-c MIGRATE 192.168.1.100 6380 queue:jobs 0 5000SADD tags redis python java MIGRATE 192.168.1.100 6380 tags 0 5000ZADD leaderboard 100 player1 200 player2 MIGRATE 192.168.1.100 6380 leaderboard 0 5000迁移后目标端的 Key 保持相同的数据类型和内部结构。八、过期时间的迁移MIGRATE会保留 Key 的过期时间。如果 Key 设置了 TTL生存时间迁移后目标端的 Key 仍然会在原定的过期时间点过期。SET session:abc token EX 3600 MIGRATE 192.168.1.100 6380 session:abc 0 5000迁移后在目标端执行TTL session:abc返回一个正数表示剩余生存时间。注意迁移过程耗时会影响剩余 TTL。注意过期时间的绝对过期时刻是基于 Unix 时间戳的如果源端和目标端的系统时间存在差异可能导致 Key 在目标端的实际过期时间与预期不同。九、事务、Pipeline 与并发场景1. 在事务中使用MIGRATE是写命令可以放入事务队列但由于MIGRATE涉及网络 I/O在事务中使用可能导致长时间阻塞MULTI MIGRATE 192.168.1.100 6380 user:1001 0 5000 MIGRATE 192.168.1.100 6380 user:1002 0 5000 EXEC不推荐在事务中大量使用MIGRATE因为每条MIGRATE都是网络操作事务执行时间可能很长。2. 多 Key 迁移的原子性使用KEYS选项的多 Key 迁移是原子的——所有指定的 Key 作为一个批次迁移要么全部成功要么全部失败不存在的 Key 被静默跳过。3. 并发安全MIGRATE本身是原子的但迁移过程中其他客户端对源端 Key 的修改可能导致迁移失败。例如源端 Key 在DUMP后、DEL前被其他客户端修改。源端 Key 在迁移过程中被EXPIRE过期。迁移过程中对源端 Key 的并发修改会导致MIGRATE返回错误源端数据保持不变。4. Pipeline 批量迁移需要迁移大量 Key 时可以使用多 Key 的MIGRATE分批执行而不是逐个迁移MIGRATE 192.168.1.100 6380 0 5000 KEYS key1 key2 key3 ... key100每批次控制 Key 数量和总数据大小避免单次迁移过大导致超时。十、在常见客户端中的使用方式1. redis-cli# 迁移单个 Keyredis-cli MIGRATE192.168.1.1006380user:100105000# 带 COPY 选项redis-cli MIGRATE192.168.1.1006380user:100105000COPY# 带 REPLACE 选项redis-cli MIGRATE192.168.1.1006380user:100105000REPLACE# 迁移多个 Keyredis-cli MIGRATE192.168.1.100638005000KEYS user:1001 user:1002 user:1003# 带认证redis-cli MIGRATE192.168.1.1006380user:100105000AUTHmysecret2. Pythonredis-pyimportredis clientredis.Redis(hostlocalhost,port6379,decode_responsesTrue)client.set(user:1001,Alice)# 迁移单个 Keyresultclient.migrate(192.168.1.100,6380,user:1001,0,5000)print(result)# bOK# 迁移多个 Keyclient.set(user:1002,Bob)client.set(user:1003,Charlie)resultclient.migrate(192.168.1.100,6380,,0,5000,keys[user:1002,user:1003])print(result)# bOK# 带 COPY 和 REPLACEclient.set(cache:item,data)resultclient.migrate(192.168.1.100,6380,cache:item,0,5000,copyTrue,replaceTrue)print(result)3. Node.jsnode-redisimport{createClient}fromredis;constclientcreateClient();awaitclient.connect();awaitclient.set(user:1001,Alice);// 迁移单个 Keyconstresultawaitclient.migrate(192.168.1.100,6380,user:1001,0,5000);console.log(result);// OKawaitclient.quit();4. JavaJedisimportredis.clients.jedis.Jedis;try(JedisjedisnewJedis(localhost,6379)){jedis.set(user:1001,Alice);// 迁移单个 KeyStringresultjedis.migrate(192.168.1.100,6380,user:1001,0,5000);System.out.println(result);// OK// 迁移多个 Keyjedis.set(user:1002,Bob);jedis.set(user:1003,Charlie);resultjedis.migrate(192.168.1.100,6380,0,5000,user:1002,user:1003);System.out.println(result);// OK}注意不同客户端对MIGRATE的参数封装可能不同使用前请查阅对应客户端文档。十一、典型使用场景1. 在线数据迁移将数据从旧 Redis 实例迁移到新实例实现平滑切换MIGRATE new-host 6379 user:1001 0 5000逐个或分批迁移 Key迁移过程中业务可以继续访问数据已迁移的 Key 在新实例未迁移的在旧实例。2. 集群扩容新增 Redis 节点后将部分 Key 迁移到新节点以实现负载均衡MIGRATE new-node-host 7001 0 5000 KEYS cache:a cache:b cache:c3. 数据备份到另一实例使用COPY选项将数据复制到备份实例MIGRATE backup-host 6379 user:1001 0 5000 COPY源端 Key 保留目标端获得副本。4. 跨环境数据搬迁从开发环境迁移到测试环境或从测试环境迁移到预发布环境MIGRATE test-host 6379 session:abc123 0 50005. Redis Cluster 槽位迁移在 Redis Cluster 中将一个槽位的数据从源节点迁移到目标节点。Redis 集群内部使用MIGRATE来完成 Key 的迁移MIGRATE target-node-host target-port key 0 5000配合CLUSTER SETSLOT命令完成槽位迁移流程。6. 分片数据平衡根据 Key 的访问热度将热点 Key 迁移到独立实例MIGRATE hotkey-host 6379 hot:counter 0 5000十二、性能与使用建议时间复杂度O(N)其中 N 为迁移的 Key 数量。单个 Key 的迁移时间取决于 Key 的大小和网络传输速度。MIGRATE是写命令ACL 类别为keyspace、write、slow、dangerous会修改源端和目标端的数据。合理设置timeout值。迁移大 Key 时需要更长的超时时间建议按 Key 大小动态调整小 KeyString1000-2000 毫秒。中等 Key数百元素3000-5000 毫秒。大 Key数万元素10000-30000 毫秒甚至更长。迁移大量 Key 时使用多 Key 的KEYS选项分批迁移而不是逐个迁移减少网络往返。每批次建议不超过数百个 Key 或数 MB 数据。迁移前先评估 Key 大小避免迁移超大 Key 导致超时MEMORY USAGE big-key如果目标端需要认证使用AUTH或AUTH2选项提供凭据。迁移过程中源端和目标端的系统时间差异会影响过期 Key 的行为确保两端时间同步如使用 NTP。生产环境中避免在高峰期执行大量MIGRATE操作因为迁移会占用网络带宽和 CPU 资源。如果迁移失败检查目标实例是否可达、端口是否开放、密码是否正确、目标 DB 是否存在。集群模式下MIGRATE可以直接使用不受槽位限制但集群层面的槽位迁移应使用CLUSTER SETSLOT流程。十三、常见问题排查问题 1MIGRATE 返回 IOERRIOERR表示在迁移过程中发生了 I/O 错误。可能的原因目标实例不可达网络不通、端口未开放。目标实例内存已满无法写入。超时时间太短大 Key 传输未完成。# 测试目标实例连通性redis-cli-h192.168.1.100-p6380PING解决方案检查网络连通性、增大timeout值、确认目标实例内存充足。问题 2MIGRATE 返回 BUSYKEYBUSYKEY表示目标端已存在同名 Key。使用REPLACE选项强制覆盖MIGRATE 192.168.1.100 6380 user:1001 0 5000 REPLACE问题 3MIGRATE 返回 NOKEYNOKEY表示源端没有找到指定的 Key。可能的原因Key 名称拼写错误或包含不可见字符。Key 在当前逻辑数据库中不存在SELECT切换的库影响可见范围。Key 已过期或被其他客户端删除。EXISTS user:1001 SELECT 0问题 4MIGRATE 返回 ERR syntax error语法错误。常见原因KEYS选项使用时key参数未传空字符串。AUTH和AUTH2同时使用。参数顺序不正确。# 正确的多 Key 迁移语法 MIGRATE host port db timeout KEYS key1 key2 # 正确的认证语法 MIGRATE host port key db timeout AUTH password问题 5大 Key 迁移超时大 Key 的DUMP 传输 RESTORE过程耗时较长。解决方案增大timeout值如 30000 毫秒或更长。迁移前检查 Key 大小预估传输时间MEMORY USAGE big-key对于超大 Key考虑先在源端拆分如将大 Hash 分片为多个小 Hash再分别迁移。如果超时后源端数据仍在可以重试迁移。问题 6迁移后过期时间异常源端和目标端系统时间不同步会导致过期 Key 的 TTL 行为异常。确保两端使用 NTP 同步时间。迁移后用TTL验证TTL migrated-key十四、完整练习下面的示例演示从准备数据、单个 Key 迁移、多 Key 迁移、COPY 和 REPLACE 选项使用到验证迁移结果的完整流程。需要两个 Redis 实例源端localhost:6379目标端localhost:6380# 清理源端 FLUSHDB # 准备数据 SET user:1001 Alice SET user:1002 Bob SET user:1003 Charlie HSET product:2001 name Phone price 999 LPUSH queue:jobs job-a job-b SET session:token token-data EX 3600 SET existing:target old-value # 1. 迁移单个 Key MIGRATE 127.0.0.1 6380 user:1001 0 5000 EXISTS user:1001 # 2. 迁移不存在的 Key MIGRATE 127.0.0.1 6380 no-such-key 0 5000 # 3. 使用 COPY 保留源端 MIGRATE 127.0.0.1 6380 user:1002 0 5000 COPY EXISTS user:1002 # 4. 多 Key 迁移 MIGRATE 127.0.0.1 6380 0 5000 KEYS user:1003 product:2001 # 5. 迁移带过期的 Key MIGRATE 127.0.0.1 6380 session:token 0 5000 # 在目标端验证连接到 6380 端口 # SELECT 0 # GET user:1001 # GET user:1002 # GET user:1003 # HGETALL product:2001 # LRANGE queue:jobs 0 -1 注意queue:jobs 未迁移 # TTL session:token # GET existing:target 注意未迁移仍为旧值 # 6. 使用 REPLACE 覆盖目标端同名 Key # 先在目标端创建同名 Key在 6380 端口执行 # SET existing:target target-value # 回到源端迁移并覆盖 MIGRATE 127.0.0.1 6380 existing:target 0 5000 REPLACE # 7. 迁移不同数据类型 MIGRATE 127.0.0.1 6380 queue:jobs 0 5000 EXISTS queue:jobs # 验证所有迁移结果 DBSIZE KEYS *预期结果MIGRATE ... user:1001 ...返回OK迁移后EXISTS user:1001返回0。MIGRATE ... no-such-key ...返回NOKEY。MIGRATE ... user:1002 ... COPY返回OK迁移后EXISTS user:1002返回1COPY 保留源端。MIGRATE ... KEYS user:1003 product:2001返回OK两个 Key 被迁移。MIGRATE ... session:token ...返回OK迁移后目标端TTL session:token返回正数。MIGRATE ... existing:target ... REPLACE返回OK目标端旧值被覆盖。MIGRATE ... queue:jobs ...返回OKList 类型成功迁移。最终源端剩余 Key 为使用COPY的user:1002DBSIZE反映剩余数量。十五、命令速查表需求命令迁移单个 Key 到另一实例MIGRATE host port key db timeout迁移并保留源端 KeyMIGRATE host port key db timeout COPY迁移并覆盖目标端同名 KeyMIGRATE host port key db timeout REPLACE迁移多个 KeyMIGRATE host port db timeout KEYS key1 key2 ...带密码认证迁移MIGRATE host port key db timeout AUTH password带 ACL 认证迁移MIGRATE host port key db timeout AUTH2 user pass同实例内复制 KeyCOPY source destination同实例内移动 Key 到另一 DBMOVE key db序列化 Key 的值DUMP key从序列化数据恢复 KeyRESTORE key ttl serialized-value异步删除 KeyUNLINK key [key ...]集群槽位迁移CLUSTER SETSLOT slot NODE node-id检查 Key 内存占用MEMORY USAGE key测试实例连通性PING总结MIGRATE的核心作用是将 Key 从当前 Redis 实例原子地迁移到另一个 Redis 实例MIGRATE host port key| destination-db timeout [COPY] [REPLACE] [AUTH password] [KEYS key ...]使用时重点注意六点MIGRATE是原子操作迁移过程中 Key 不会同时存在于两个实例COPY选项除外。默认迁移后源端 Key 被删除使用COPY选项可保留源端 Key。目标端存在同名 Key 时默认返回BUSYKEY错误使用REPLACE选项强制覆盖。多 Key 迁移使用空字符串作为key参数配合KEYS选项传入 Key 列表。合理设置timeout值迁移大 Key 时需要更长的超时时间。迁移会保留 Key 的数据类型、内部编码和过期时间但源端和目标端的系统时间差异可能影响过期 Key 的行为。