集群初始主节点配置

配置项作用 #

cluster.initial_master_nodes 配置项指定在集群首次初始化时的候选主节点列表。此配置仅在集群第一次启动时使用，用于确定集群的投票配置（Voting Configuration），防止脑裂。

配置项类型 #

该配置项为静态配置，需要在启动时设置。仅在集群首次初始化时生效。

默认值 #

空列表（需要手动配置）

是否必需 #

首次启动必需（多节点集群）

配置格式 #

# 单个节点
cluster.initial_master_nodes:
  - "node-1"

# 多个节点（推荐）
cluster.initial_master_nodes:
  - "node-1"
  - "node-2"
  - "node-3"

# 简写格式（已弃用）
cluster.initial_master_nodes: node-1,node-2,node-3

工作原理 #

集群初始化过程：

┌─────────────────────────────────────────────────────────────────┐
│                    集群首次启动初始化流程                        │
└─────────────────────────────────────────────────────────────────┘

节点同时启动
    │
    ├── node-1 (主节点候选)
    ├── node-2 (主节点候选)
    └── node-3 (主节点候选)
         │
         ▼
每个节点读取 initial_master_nodes
    │
    ├── node-1: 发现自己、node-2、node-3 在列表中
    ├── node-2: 发现自己、node-1、node-3 在列表中
    └── node-3: 发现自己、node-1、node-2 在列表中
         │
         ▼
节点间相互发现
    │
    ▼
选举主节点
    │
    ├── node-1 当选为主节点
    └── node-2、node-3 成为数据节点
         │
         ▼
集群形成
    │
    ▼
配置持久化到集群状态
    │
    ▼
后续启动不再需要此配置

投票配置 #

主节点选举基于投票配置：

投票配置 (Voting Configuration):
- 由 initial_master_nodes 定义的节点组成
- 用于主节点选举投票
- 形成仲裁多数（quorum）

仲裁计算:
quorum = (投票配置中的节点数 / 2) + 1

示例 1: 3 个节点
quorum = (3 / 2) + 1 = 2
需要至少 2 票才能选出主节点

示例 2: 5 个节点
quorum = (5 / 2) + 1 = 3
需要至少 3 票才能选出主节点

使用场景 #

1. 三节点集群（推荐） #

# 节点 1 配置
cluster.name: production
node.name: node-1
discovery.seed_hosts: ["192.168.1.10:9300", "192.168.1.11:9300", "192.168.1.12:9300"]
cluster.initial_master_nodes:
  - "node-1"
  - "node-2"
  - "node-3"
network.host: 192.168.1.10

# 节点 2 配置
cluster.name: production
node.name: node-2
discovery.seed_hosts: ["192.168.1.10:9300", "192.168.1.11:9300", "192.168.1.12:9300"]
cluster.initial_master_nodes:
  - "node-1"
  - "node-2"
  - "node-3"
network.host: 192.168.1.11

# 节点 3 配置
cluster.name: production
node.name: node-3
discovery.seed_hosts: ["192.168.1.10:9300", "192.168.1.11:9300", "192.168.1.12:9300"]
cluster.initial_master_nodes:
  - "node-1"
  - "node-2"
  - "node-3"
network.host: 192.168.1.12

2. 五节点集群（高可用） #

cluster.initial_master_nodes:
  - "master-1"
  - "master-2"
  - "master-3"
  - "master-4"
  - "master-5"

容错能力： 允许 2 个节点故障

3. 单节点开发环境 #

# 使用单节点模式，不需要此配置
discovery.type: single-node

集群规模	initial_master_nodes	仲裁数	容错节点数
3 节点	3 个节点	2	1
5 节点	5 个节点	3	2
7 节点	7 个节点	4	3

配置要点 #

1. 节点名称匹配 #

# ✅ 正确配置
node.name: node-1
cluster.initial_master_nodes:
  - "node-1"

# ❌ 错误配置
node.name: node-1
cluster.initial_master_nodes:
  - "node-2"  # 节点名称不匹配

2. 所有节点配置一致 #

所有候选主节点的 initial_master_nodes 配置应该相同：

# 所有节点都配置相同的列表
cluster.initial_master_nodes:
  - "node-1"
  - "node-2"
  - "node-3"

3. 仅首次启动需要 #

首次启动成功后可以移除此配置：

# 首次启动后，可以注释掉或删除此配置
# cluster.initial_master_nodes:
#   - "node-1"
#   - "node-2"
#   - "node-3"

集群初始化失败排查 #

问题 1：节点未加入集群

# 检查日志
tail -f logs/easysearch.log

可能原因：

cluster.name 不一致
node.name 与 initial_master_nodes 不匹配
discovery.seed_hosts 配置错误

问题 2：形成多个独立集群

原因：节点的 initial_master_nodes 配置不一致

解决方案：确保所有节点使用相同的配置

问题 3：无法选举主节点

原因：投票配置中的节点数不足仲裁要求

解决方案：确保至少配置 3 个候选主节点

与 discovery.seed_hosts 的区别 #

配置项	作用	使用时机
`cluster.initial_master_nodes`	定义投票配置	首次启动
`discovery.seed_hosts`	节点发现地址	每次启动

工作流程：

首次启动:
1. discovery.seed_hosts → 发现其他节点
2. cluster.initial_master_nodes → 确定投票配置
3. 选举主节点
4. 集群形成

后续启动:
1. discovery.seed_hosts → 发现其他节点
2. 读取持久化的集群状态
3. 加入已有集群

完整配置示例 #

# ==================== 节点 1 ====================
cluster.name: production
node.name: node-1
node.roles: [master, data]

# 网络配置
network.host: 192.168.1.10
http.port: 9200
transport.port: 9300

# 发现配置
discovery.seed_hosts:
  - "192.168.1.11:9300"
  - "192.168.1.12:9300"

# 初始主节点配置（仅在首次启动时需要）
cluster.initial_master_nodes:
  - "node-1"
  - "node-2"
  - "node-3"

# ==================== 节点 2 ====================
cluster.name: production
node.name: node-2
node.roles: [master, data]

network.host: 192.168.1.11
http.port: 9200
transport.port: 9300

discovery.seed_hosts:
  - "192.168.1.10:9300"
  - "192.168.1.12:9300"

cluster.initial_master_nodes:
  - "node-1"
  - "node-2"
  - "node-3"

# ==================== 节点 3 ====================
cluster.name: production
node.name: node-3
node.roles: [master, data]

network.host: 192.168.1.12
http.port: 9200
transport.port: 9300

discovery.seed_hosts:
  - "192.168.1.10:9300"
  - "192.168.1.11:9300"

cluster.initial_master_nodes:
  - "node-1"
  - "node-2"
  - "node-3"

监控建议 #

# 查看集群状态
GET /_cluster/state

# 查看投票配置
GET /_cluster/state?filter_path=metadata.cluster_coordination.last_committed_config

# 查看节点信息
GET /_cat/nodes?v

# 查看集群健康
GET /_cluster/health

常见问题 #

问题 1：已存在的集群是否需要此配置？

答：不需要。此配置仅在集群首次启动时使用。

问题 2：配置错误的节点名称会怎样？

答：节点将无法加入集群，可能导致无法达到仲裁数。

问题 3：可以只配置一个节点吗？

答：技术上可以，但不推荐。单节点集群无高可用性。

问题 4：首次启动后可以修改此配置吗？

答：可以，但不会生效。配置已持久化到集群状态中。

注意事项 #

仅首次启动：只在集群第一次启动时生效
节点名称匹配：必须与实际的 node.name 完全匹配
奇数原则：配置奇数个候选主节点（3, 5, 7…）
配置一致：所有节点的此配置应该相同
与 seed_hosts 配合：必须同时配置 discovery.seed_hosts
持久化后可删除：首次成功后可以移除此配置
单节点例外：使用 discovery.type: single-node 时不需此配置

标签

集群配置节点发现集群初始化