rocketmq主从自动切换需dledger或controller模式支持，传统async_master/slave不支持；dledger基于raft秒级选主，controller解耦控制与数据平面，均要求≥3节点法定多数，配置不当将导致消息丢失或选举失败。
RocketMQ 的主从自动切换能力，不是靠简单配置就能生效的，而是依赖特定架构模式和组件协同工作的结果。它经历了从手动干预到全自动演进的过程，核心在于“谁来决定谁当主、何时切换、怎么保证不丢消息”。
主从自动切换的前提：必须启用 DLedger 或 Controller 模式
传统 Master-Slave（brokerRole=ASYNC_MASTER/SLAVE）本身**不支持自动切换**，Master 宕机后 Slave 只能读，不能接管写请求。真正实现自动切换，需满足以下任一条件： - 使用 RocketMQ 4.5+ 的 **DLedger 模式**：Broker 进程内嵌 DLedger 组件，基于 Raft 协议自动选主； - 使用 RocketMQ 5.0+ 的 **Controller 模式**：Controller 组件（可内嵌于 NameServer 或独立部署）统一管理 Broker 角色选举，解耦控制平面与数据平面。两者都要求至少 3 个节点组成法定多数（quorum），例如 3 节点集群允许 1 节点故障仍能完成选举。
DLedger 模式下自动切换如何触发
当 Master（即当前 Leader）不可用时，切换由 DLedger 内部 Raft 机制驱动： - 所有节点定期发送心跳，超时（默认 3 秒）未收到 Leader 心跳即启动新一轮选举； - 候选节点发起投票请求，获得多数派（≥2/3）响应后成为新 Leader； - 新 Leader 向客户端广播角色变更，并开始接受生产者写入； - 原 Slave 节点在升级为 Leader 后，自动承担读写职责，消费者无需重连即可继续消费。整个过程无需人工介入，典型切换耗时在 3～5 秒内，属于秒级故障转移。
Controller 模式下的自动切换逻辑
Controller 是一个独立的 Raft 集群，专门负责 Broker 角色调度： - 每个 Broker 向 Controller 上报存活状态与同步进度（SyncStateSet）； - Controller 实时监控 Master 健康状况，一旦判定其失联且超过阈值，立即发起角色重分配； - 切换决策基于数据一致性：仅从 SyncStateSet 中的节点中选举新 Master，避免“脏主”（enableElectUncleanMaster=false 是关键安全开关）； - 角色变更通过 Notify 机制推送给所有 NameServer 和 Broker，路由信息实时更新。相比 DLedger，Controller 模式将选举逻辑抽离，Broker 保持轻量存储角色，更适合云原生环境和大规模集群运维。
关键配置与避坑要点
要让自动切换真正可靠，这些细节不能忽略： - 法定节点数必须满足 Raft 要求：3 节点集群最少需 2 个在线才能选举；单节点 Controller 无法容错； - 日志同步必须可达：异步复制（ASYNC_MASTER）下切换可能丢失最新消息，金融场景务必使用 SYNC_MASTER 或 DLedger/Controller 的强一致写入； - controllerStorePath 不可共享或误删：Controller 的本地日志是状态恢复依据，重启依赖该目录； - 禁用 unclean election：设置 enableElectUncleanMaster=false，防止数据严重滞后的节点被误选为主； - 客户端需支持动态路由刷新：Producer/Consumer 应开启 autoUpdateTopicRouteInfo=true（默认开启），及时获取新 Master 地址。自动切换不是开箱即用的功能，而是架构选择、配置校验和运行时保障共同作用的结果。
