从 Redis 迁移到 Valkey

适用场景

需要从 Redis 切换到开源许可证更宽松、协议兼容的 Valkey，或希望保持 Redis 客户端和命令不变的同时获得社区持续维护。大多数 Redis 客户端可以直接连接 Valkey。

前置条件

• 确认 Redis 版本和 Valkey 版本的命令兼容性。
• 应用使用的模块、脚本和持久化方式已梳理。
• 准备新 Valkey 实例或集群，容量不低于原实例。
• 保留旧 Redis 作为回滚路径。

步骤

1. 记录旧实例信息：

redis-cli INFO server
redis-cli INFO keyspace
redis-cli CONFIG GET maxmemory
redis-cli CONFIG GET appendonly
redis-cli MODULE LIST

2. 部署 Valkey，保持相同的认证、TLS 和持久化配置。先用测试实例验证客户端兼容性：

valkey-server /etc/valkey/valkey.conf
valkey-cli -h valkey-test -p 6379 PING

3. 建立复制关系，让 Valkey 从 Redis 同步：

valkey-cli -h valkey-test REPLICAOF redis-old 6379
valkey-cli -h valkey-test INFO replication

等待 master_link_status:up 且偏移量追平。

4. 在低峰期停止写入，确认偏移量一致：

redis-cli INFO replication
valkey-cli INFO replication

5. 将 Valkey 提升为主：

valkey-cli -h valkey-test REPLICAOF NO ONE

6. 切换应用连接地址或 DNS。先切一小部分流量，观察错误率和延迟。

7. 验证数据完整性和关键命令：

valkey-cli DBSIZE
valkey-cli --scan --pattern 'user:*' | head
valkey-cli INFO commandstats

验证

• 应用读写正常，连接池没有大量重连。
• DBSIZE 和关键 key 数量与旧实例一致。
• TTL、事务、Lua 脚本、Pub/Sub 和 Stream 行为正常。
• 持久化文件能正常加载，重启后数据不丢。
• 监控中的命中率、内存和连接数与迁移前接近。

回滚

• 保留旧 Redis 实例和原连接地址，切换失败时改回。
• 切换前不要删除旧实例的数据和 AOF/RDB。
• 如果已经写入新数据，回滚前要评估双向同步，避免丢失。
• DNS 切换使用短 TTL，便于快速回退。

常见坑

• 使用了 Redis 专有模块，Valkey 没有对应实现。
• 集群模式下的 slot 分布和客户端配置不兼容。
• ACL 用户、命令重命名和 TLS 配置没有同步迁移。
• 复制偏移量未追平就切换，丢失最后一批写入。
• 应用连接池仍缓存旧地址，DNS 切换后没有生效。
• 持久化格式版本差异导致重启加载失败。
• 没有压测就全量切换，长尾命令性能不同。

相关命令

• redis-cli — 旧实例检查和数据核对
• valkey-cli — 新实例管理与复制
• valkey-server — 启动服务
• redis-benchmark / valkey-benchmark — 压测
• redis-check-aof / valkey-check-aof — 持久化文件检查