--- title: "集群初始主节点配置" date: 2026-02-10 lastmod: 2026-02-10 description: "配置集群初始化时的候选主节点列表配置项说明" tags: ["集群配置", "节点发现", "集群初始化"] summary: "配置项作用 # 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 成为数据节点 │ ▼ 集群形成 │ ▼ 配置持久化到集群状态 │ ▼ 后续启动不再需要此配置 投票配置 # 主节点选举基于投票配置：" --- ## 配置项作用 `cluster.initial_master_nodes` 配置项指定在集群首次初始化时的候选主节点列表。此配置仅在集群第一次启动时使用，用于确定集群的投票配置（Voting Configuration），防止脑裂。 ## 配置项类型 该配置项为**静态配置**，需要在启动时设置。**仅在集群首次初始化时生效**。 ## 默认值 ``` 空列表（需要手动配置） ``` ## 是否必需 **首次启动必需**（多节点集群） ## 配置格式 ```yaml # 单个节点 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. 三节点集群（推荐） ```yaml # 节点 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. 五节点集群（高可用） ```yaml cluster.initial_master_nodes: - "master-1" - "master-2" - "master-3" - "master-4" - "master-5" ``` **容错能力：** 允许 2 个节点故障 ### 3. 单节点开发环境 ```yaml # 使用单节点模式，不需要此配置 discovery.type: single-node ``` ## 推荐设置建议 | 集群规模 | initial_master_nodes | 仲裁数 | 容错节点数 | |---------|---------------------|-------|-----------| | 3 节点 | 3 个节点 | 2 | 1 | | 5 节点 | 5 个节点 | 3 | 2 | | 7 节点 | 7 个节点 | 4 | 3 | **重要原则：** - 初始主节点数应为奇数（3, 5, 7...） - 避免使用偶数（4 个节点的容错能力与 3 个相同） ## 配置要点 ### 1. 节点名称匹配 ```yaml # ✅ 正确配置 node.name: node-1 cluster.initial_master_nodes: - "node-1" # ❌ 错误配置 node.name: node-1 cluster.initial_master_nodes: - "node-2" # 节点名称不匹配 ``` ### 2. 所有节点配置一致 所有候选主节点的 `initial_master_nodes` 配置应该相同： ```yaml # 所有节点都配置相同的列表 cluster.initial_master_nodes: - "node-1" - "node-2" - "node-3" ``` ### 3. 仅首次启动需要 首次启动成功后可以移除此配置： ```bash # 首次启动后，可以注释掉或删除此配置 # cluster.initial_master_nodes: # - "node-1" # - "node-2" # - "node-3" ``` ## 集群初始化失败排查 **问题 1：节点未加入集群** ```bash # 检查日志 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. 加入已有集群 ``` ## 完整配置示例 ```yaml # ==================== 节点 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" ``` ## 监控建议 ```bash # 查看集群状态 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：首次启动后可以修改此配置吗？** **答：** 可以，但不会生效。配置已持久化到集群状态中。 ## 注意事项 1. **仅首次启动**：只在集群第一次启动时生效 2. **节点名称匹配**：必须与实际的 node.name 完全匹配 3. **奇数原则**：配置奇数个候选主节点（3, 5, 7...） 4. **配置一致**：所有节点的此配置应该相同 5. **与 seed_hosts 配合**：必须同时配置 discovery.seed_hosts 6. **持久化后可删除**：首次成功后可以移除此配置 7. **单节点例外**：使用 discovery.type: single-node 时不需此配置