跳到主要内容

集群配置

YedMQ 使用 Raft 协调分布式状态。本页说明多节点部署时最关键的配置项，以及当前 REST 管理流程如何配合这些配置工作。

配置示例​

[cluster]
cluster_name = "YedMQ"
node_id = 1001
heartbeat_interval = 10
store_dir = "./store"
session_ttl = 86400
startup_mode = "bootstrap"
nodes = [
    { id = 1001, rpc_address = "node1.example.com:3457", api_address = "node1.example.com:3456" },
    { id = 1002, rpc_address = "node2.example.com:3457", api_address = "node2.example.com:3456" },
    { id = 1003, rpc_address = "node3.example.com:3457", api_address = "node3.example.com:3456" },
]

[cluster.rpc]
external = "0.0.0.0:3457"

主要字段说明​

  • cluster_name：同一集群所有节点共享的逻辑名称
  • node_id：当前节点的唯一数字标识
  • heartbeat_interval：Raft 心跳间隔，单位为秒
  • store_dir：Raft 日志和复制状态的存储目录
  • session_ttl：断开连接后持久会话保留时间，建议在真实部署中显式设置
  • startup_mode：
    • bootstrap：首节点模式，启动时会基于成员列表初始化 raft 组
    • join：扩容节点模式，启动后等待通过集群管理 API 加入
  • nodes：已知节点列表，每个节点包含 rpc_address 和 api_address
  • cluster.rpc.external：节点间 RPC 通信监听地址

当前被复制的状态​

YedMQ 目前维护三个独立的 raft 组：

  • topic 元数据
  • session actor map
  • session state

这也是为什么很多集群 API 会同时操作三个 raft 组。

推荐扩容流程​

  1. 初始节点或初始成员集合使用 startup_mode = "bootstrap" 启动。
  2. 新增节点使用 startup_mode = "join" 启动。
  3. 通过管理 API 把新节点加入集群：
    • POST /api/v1/cluster/learners：先把节点作为 learner 加入三个 raft 组。
    • POST /api/v1/cluster/nodes：一次请求完成 learner 添加和成员变更。
  4. 通过 GET /api/v1/cluster/metrics 检查新节点是否已经稳定加入。

一步完成新增节点的请求示例：

{
  "node_id": 1002,
  "node": {
    "rpc_addr": "10.0.0.2:3457",
    "api_addr": "10.0.0.2:3456"
  },
  "members": [1001, 1002]
}

手动初始化接口​

虽然 bootstrap 模式会在启动时初始化 raft 状态，但当前仍保留了显式初始化接口，适合运维流程或手工操作：

  • POST /api/v1/cluster/init
  • POST /api/v1/cluster/raft/topic/init
  • POST /api/v1/cluster/raft/session_actor_map/init
  • POST /api/v1/cluster/raft/session_state/init