CacheCloud 应用在线迁移实战指南：基于主从 Failover 的客户端无感知迁移全流程解析-平芜编程栈

后端
运维

【免费下载链接】cachecloud

搜狐视频(sohu tv)Redis私有云平台：支持Redis多种架构(Standalone、Sentinel、Cluster)高效管理、有效降低大规模redis运维成本，提升资源管控能力和利用率。平台提供快速搭建/迁移，运维管理，弹性伸缩，统计监控，客户端整合接入等功能。(CacheCloud is a Redis cloud management platform. It supports Standalone, Sentinel, and Cluster architectures for Redis, effectively reducing large-scale Redis operation and maintenance costs, and improving resource management and utilization. The platform provides rapid construction/migration, operation and maintenance management, elastic scaling, statistical monitoring, client integration and access and other functions)

项目地址：https://gitcode.com/gh_mirrors/ca/cachecloud

点击查看免费下载

导读

本文基于 CacheCloud 官方运维文档 appMigrate.md 展开，系统讲解 Redis 私有云平台 CacheCloud 中"应用在线迁移"功能的完整操作流程与底层实现原理。通过阅读本文，你将掌握：如何在"应用运维"页面发起不更换 appId 的实例迁移、迁移过程中八个关键步骤的操作要点、以及 Standalone / Sentinel / Cluster 三种架构下主从 Failover 的执行细节，从而在机房搬迁、资源调整、机器下电等场景中实现业务无感知的应用迁移。

一、应用迁移是什么

CacheCloud 的"应用迁移"是一种不更换应用 appId的在线迁移方式。它利用 Redis 主从复制架构，通过新老 Slave 节点替换 + 主从 Failover的组合动作，把应用实例平滑地从一组物理机迁移到另一组物理机上。由于整个过程围绕主从复制与角色切换展开，客户端连接的应用 ID 保持不变，因此对客户端是完全无感知的——这正是该迁移方案的核心价值。

从代码结构看，该功能由 AppMigrateController（路由前缀/manage/app/migrate）提供后端接口，由 appMigrate.html 提供前端向导页面，二者共同构成一个 8 步的"应用迁移工具"。

二、入口：进入 CacheCloud 后台

在 CacheCloud 后台的"应用运维"页面，选择要进行迁移的应用，点击"应用迁移"按钮，即可进入迁移向导。前端向导 appMigrate.html 会加载并展示应用的基本信息：应用 ID、Redis 类型（2为 Cluster 集群、5为 Sentinel、6为 Standalone）、内存总容量、实例容量、应用机器数、master/slave 节点数，以及源实例信息。

对应后端入口为AppMigrateController.init，它会一次性取回应用详情（appStatsCenter.getAppDetail）、全量机器状态（machineCenter.getMachineStats）、当前 Redis 实例信息，以及 Sentinel 实例信息（如果应用是 Sentinel 架构），并加载可用机房列表供迁移选择。

三、八步迁移流程详解

应用迁移整体包含八个主要步骤，前端以 Bootstrap Wizard 的形式逐步推进（对应 appMigrate.html 中appInfo → createVersion → slaveChange → msFailover → addNewSlave → instanceCheck → downOldSlave → migrateComplete的步骤条），每一步完成后点击"继续"进入下一步。

步骤 1：应用信息

查看源应用的实例 IP、角色（master/slave/sentinel）和 Redis 版本等信息，选择迁移的目标机房和迁移机器。

实操要点：

页面会列出所有可用机器及其资源占用（已用/总核数、已用/总内存、宿主机/机架信息），可按"专用- / 测试- / 混合-"部署类型筛选。
支持点击"自动挑选机器"，前端调用autoSelectMachine()向后端selectMachine接口提交type / useType / room / machineNum / mem / masterNum / slaveNum参数，由 AppMigrateController.selectMachine 依据架构类型计算候选机器：Sentinel 架构masterMachineNum = 1 + slaveNum，Standalone 架构为1，Cluster 架构等于机器总数，随后按目标内存、CPU 需求从有效机器中筛选。
若应用是 Sentinel 架构（type=5），还需单独为 Sentinel 节点选择迁移机器，可调用selectSentinelMachine接口自动挑选；源码中要求 Sentinel 数量不小于 3 且为奇数，不足时系统会自动补足为 3 或sentinelNum + 1。

步骤 2：应用迁移计划

这一步主要查看节点的变更信息：新增实例（Slave）的 IP 和端口号，以及待下线的旧实例清单，确认无误后点击继续，进入新老 Slave 节点的替换。

对应后端接口为 AppMigrateController.checkPlan，其内部做了三件事：

校验迁移机器参数非空（machineInfo为空直接报"迁移机器参数异常"）；
校验迁移机器上 Redis 版本/环境（源码中相关版本检查逻辑当前处于注释状态，异常时返回"迁移机器Redis版本检查异常"）；
计算迁移计划：收集当前状态良好（GOOD_STATUS）的 master、sentinel 节点，通过getRedisInfo按轮询（取模）算法为每个 master 分配一个目标 slave 机器（尽量避免主从落在同一物理机），通过getDownInstanceInfo收集需要下线的 slave / sentinel 实例，最终返回"新增实例信息"与"下线实例信息"两个清单，前端合并展示在"节点变更信息"文本域中。

步骤 3：新老 Slave 节点替换

替换完成之后查看最新实例信息，点击继续，进行主从切换。

对应后端接口为 AppMigrateController.nodeReplace，执行顺序是：

先通过shutdownInstance关闭待下线的旧 slave 节点（逐个调用instanceDeployCenter.shutdownExistInstance）；
再通过startInstance在目标机器上启动新的 Redis 实例：对每个当前 master，调用redisDeployCenter.addSlave(appId, masterInstanceId, slaveIp)建立主从关系，然后sleep 15 秒等待 master 的 PSYNC 同步，并用slaveIsPsync检测新 slave 是否已追上主库偏移；
若为 Sentinel 架构，额外通过startSentinelInstance调用redisDeployCenter.addSentinel启动新 Sentinel；
最后返回迁移后的"最新实例信息"与实例日志链接。

步骤 4：主从 Failover

完成主从节点切换，点击继续，添加新的 Slave。

对应后端接口为 AppMigrateController.msFailover，核心是调用redisConfigTemplateService.slaveFailover(appId)。查看 RedisConfigTemplateServiceImpl.slaveFailover 的实现可以看到其关键逻辑：

Cluster 架构：调用redisDeployCenter.clusterFailover(appId, instanceId, "force")执行CLUSTER FAILOVER FORCE强制切换；
Sentinel 架构：调用redisDeployCenter.sentinelFailover(appId)触发 Sentinel 主导的故障转移；
failover 发起后，通过redisCenter.getRedisReplicationStatus轮询检测复制状态（间隔 2 秒、最多重试 30 次），直到确认切换完成；
若 failover 失败，接口直接返回"failover失败，请查看日志!"，迁移流程中止等待排查。

Failover 之后，msFailover会重新拉取实例列表，识别出当前已变为 slave 的旧 master 节点，将其 ID 记录到downInstanceIds，供后续下线使用。

步骤 5：添加 Slave

添加新的 Slave，恢复迁移前的副本数量与容灾能力。

对应后端接口为 AppMigrateController.addNewSlave：对 failover 后新的 master 节点，再次调用startInstance（内部addSlave+ sleep 15s + PSYNC 检测）为目标机器添加从节点；Sentinel 架构下同时补充新的 Sentinel 实例，最后刷新最新实例信息与日志。

步骤 6：新实例状态检测

检查新实例的连接状态是否异常，点击继续，下线老的 Slave。

对应后端接口为 AppMigrateController.appStatusCheck（路由appCheck）。该步骤是迁移链路上的健康闸门：只有新实例状态检查通过，才允许继续执行下线操作；前端也会在此时把"下线实例"信息展示给运维人员确认。源码中该接口目前主要承担状态检查的框架职责，实际运行中建议结合 CacheCloud 的实例监控（连接数、运行状态）一并确认，遇到异常可回到上一步排查日志。

步骤 7：下线 Slave

下线老的 Slave，释放源机器资源。

对应后端接口为 AppMigrateController.downSlave：通过shutdownInstance(downInstanceIds, appId)逐一下线旧 slave 实例（内部调用instanceDeployCenter.shutdownExistInstance）。注意前端逻辑：若应用为 Sentinel 架构，此步骤会将 Redis 的下线 ID 与 Sentinel 的下线 ID 拼接后一并提交，即旧 slave 与旧 sentinel 同时下线。

步骤 8：迁移完成

完成迁移，前端跳回应用页面，迁移流程收尾。

对应后端接口为 AppMigrateController.migrateComplete（路由complete），返回成功后前端window.location.reload()刷新页面，即可在"应用运维"中看到迁移后的新实例拓扑。

四、源码级原理剖析：为什么能做到客户端无感知

整个迁移过程的核心设计思想，可以从源码中得到完整印证：

appId 全程不变：迁移过程中所有后端接口都以appId为操作维度（如addSlave(appId, masterInstanceId, ip)、clusterFailover(appId, ...)），数据模型层面实例只发生"角色与位置"的变化，应用 ID 与客户端接入地址（Sentinel 的监控域名 / Cluster 的任一节点）均不变化，因此对客户端无感知。
先建后拆、角色平移：迁移链路遵循"新增 Slave → 主从 Failover → 补充 Slave → 下线老节点"的顺序。任意时刻应用都保有完整的 master + slave 副本，避免迁移窗口期内出现单点。
PSYNC 与偏移量检测保障数据一致性：每次addSlave后程序固定等待 15 秒让新 slave 完成全量/增量同步，并通过slaveIsPsync、getRedisReplicationStatus校验主从偏移，确认同步完成后才继续下一步，从机制上防止数据丢失。
架构差异化处理：Cluster 走CLUSTER FAILOVER FORCE，Sentinel 走 Sentinel 自身的故障转移接口，Standalone（单主）则在 failover 时整体由新 slave 顶替主位——三套路径在 RedisConfigTemplateServiceImpl.slaveFailover 中按appDesc.getType()分流，前端向导也据此决定是否展示 Sentinel 机器选择区。

此外，仓库中还提供了面向容器/物理机整机搬迁场景的强制迁移（forceMigrate）能力，见 MigrateServiceImpl.forceMigrate：以"源 IP → 目标 IP"为粒度，将源机器上所有 Cluster 实例按 appId 分组，异步并发执行"获取 slave0 → failover 并校验 → 下线旧节点 → 添加新 slave"的循环，失败节点最多重试 3 轮。这可以视作页面八步流程的自动化批量版本，适用于批量搬迁场景。

五、操作注意事项

迁移机器必须预先就绪：目标机器需能被 CacheCloud 通过 SSH 管理、拥有足够的剩余内存与 CPU，并在页面上处于可选状态；Redis 版本检查异常时会在"应用迁移计划"步骤直接拦截。
迁移过程中如遇错误：向导页面会明确提示——"如果在迁移过程中遇到错误警告，请登录服务器查看日志解决后再继续执行"。Failover 失败、addSlave 失败都会返回明确错误信息，不要跳过失败步骤强行推进。
部分步骤可跳过：前端向导为"新老 Slave 节点替换"和"添加 Slave"步骤提供了"跳过"按钮（skip()），用于某些架构下无需替换/追加 slave 的场景；非必要不建议跳过，否则可能影响最终副本数。
Sentinel 架构的奇偶约束：自动挑选 Sentinel 机器时，系统会保证 Sentinel 数量不小于 3 且为奇数，迁移前请确认目标机房的 Sentinel 资源充足。
迁移范围限定：页面版八步流程面向单个应用；若需要整机/多应用批量迁移，可评估 MigrateServiceImpl 中forceMigrate的容器迁移路径。

六、小结

CacheCloud 的"应用在线迁移"以主从复制与 Failover 为基石，通过八步向导将"换机器"这一高风险运维动作拆解为可检查、可回退、可审计的流程：新增 slave 保证数据不丢，failover 实现角色切换，状态检测把关健康度，最后下线老节点释放资源，全程 appId 不变、客户端无感知。配合仓库中 AppMigrateController 的接口实现与 appMigrate.html 的向导逻辑，读者既可以按图索骥完成单应用迁移，也能理解其底层调用链，为后续的批量迁移与自动化运维打下基础。