集群部署

TMQTT 支持多节点集群部署，实现高可用和水平扩展。集群采用 Gossip 节点发现 + Raft 共识 + gRPC 通信 的架构。

---

集群架构概览

客户端 → [负载均衡器] → ┌─ 节点 A（活跃）─┐
                      ├─ 节点 B（活跃）─┼─ 互相 Gossip 通信
                      └─ 节点 C（活跃）─┘
                           ↕ gRPC
                    [Raft 共识组]（用于会话状态同步）

组件	说明
Gossip 协议	节点自动发现、健康检测、成员管理
Raft 共识	保证集群关键数据（如路由表）的一致性
gRPC	节点间高性能通信通道
负载均衡	将客户端连接分散到各节点

---

集群配置

在 config.toml 中添加 [cluster] 配置段：

配置项	说明
seed	集群通信监听地址，如 127.0.0.1:7000
seed_nodes	种子节点地址列表，用于新节点发现集群
lb.strategy	负载均衡策略（见下文）
lb.enabled	是否启用负载均衡

负载均衡策略

策略	说明
least_connections	将新连接分配给当前连接数最少的节点（默认）
round_robin	轮询分配到各节点
weighted	按权重比例分配流量

---

节点生命周期

新节点加入

新节点启动时，通过 seed_nodes 中的地址发现集群，自动完成：

1. 加入 Gossip 成员组
2. 与集群同步路由表和状态
3. 开始接受客户端连接

无需停服，在线扩容。

节点下线（Drain 模式）

通过管理 API 将节点设为 Drain 状态：

1. 节点停止接受新连接
2. 现有连接的消息正常处理
3. 等待客户端自然断开（或主动关闭）后重连到其他节点

适合滚动升级和维护窗口。

节点灰度发布（金丝雀）

支持为节点设置版本标签，负载均衡器可以根据版本号将部分流量导向新版本节点，实现渐进式升级。

---

节点状态

集群中每个节点有明确的生命周期状态：

状态	含义
Starting	正在启动，尚未加入集群
Active	正常运行，处理客户端连接
Draining	正在排空连接，不接受新连接
Leaving	正在离开集群
Left	已离开集群
Failed	健康检查失败，疑似异常

可通过管理 API 或集群管理 API 查看各节点状态。

---

典型部署架构

三节点集群

最常用的高可用方案，任意一个节点故障不影响整体服务：

节点 A: 10.0.1.1:1883  ── seed: 10.0.1.1:7000
节点 B: 10.0.1.2:1883  ── seed: 10.0.1.2:7000
节点 C: 10.0.1.3:1883  ── seed: 10.0.1.3:7000

每个节点的 seed_nodes 配置其他节点地址即可自动组网。

前置负载均衡

在集群前部署 Nginx 或 HAProxy，将客户端 MQTT 连接分发到各节点：

# Nginx TCP 负载均衡示例
stream {
    upstream tmqtt_cluster {
        least_conn;
        server 10.0.1.1:1883;
        server 10.0.1.2:1883;
        server 10.0.1.3:1883;
    }
    server {
        listen 1883;
        proxy_pass tmqtt_cluster;
    }
}

---

滚动升级

集群模式下的推荐升级流程：

1. 对目标节点发送 Drain 指令
2. 等待该节点现有连接迁移完毕
3. 停止该节点，部署新版本
4. 启动新版本节点，自动重新加入集群
5. 对下一个节点重复以上步骤

全程不影响其他节点服务，实现零停机升级。

Copyright (c) 2026 桃子 TaoZi.Pub https://taozi.pub | MIT License