---
title: "期望主节点数量配置"
date: 2026-02-27
lastmod: 2026-02-27
description: "gateway.expected_master_nodes 配置项用于控制集群启动时期望的主节点数量（已弃用）。"
tags: ["Gateway", "集群恢复", "主节点", "已弃用"]
summary: "配置项作用 #  gateway.expected_master_nodes 配置项用于指定集群在恢复状态时期望拥有的主节点数量。
当设置此值后，Gateway 服务会等待直到集群中有指定数量的主节点可用，然后才开始恢复集群状态。
配置项属性 #   配置路径: gateway.expected_master_nodes 数据类型: integer 默认值: -1（表示未设置） 最小值: -1 是否可选: 是 弃用状态: ⚠️ 已弃用  配置项详解 #  工作机制 #  集群启动过程 │ ↓ 读取配置 expected_master_nodes = 3 │ ↓ 检测当前主节点数量 │ ├──────── 当前数量 < 期望数量 │ │ │ ↓ │ 延迟恢复，等待更多主节点 │ │ │ ↓ │ 继续检测... │ └──────── 当前数量 ≥ 期望数量 │ ↓ 开始恢复集群状态 恢复逻辑 #  // 简化的代码逻辑 if (expectedMasterNodes !"
---


## 配置项作用

`gateway.expected_master_nodes` 配置项用于指定集群在恢复状态时期望拥有的**主节点数量**。

当设置此值后，Gateway 服务会等待直到集群中有指定数量的主节点可用，然后才开始恢复集群状态。

## 配置项属性

- **配置路径**: `gateway.expected_master_nodes`
- **数据类型**: `integer`
- **默认值**: `-1`（表示未设置）
- **最小值**: `-1`
- **是否可选**: 是
- **弃用状态**: ⚠️ **已弃用**

## 配置项详解

## 工作机制

```
集群启动过程
    │
    ↓
读取配置 expected_master_nodes = 3
    │
    ↓
检测当前主节点数量
    │
    ├──────── 当前数量 < 期望数量
    │              │
    │              ↓
    │         延迟恢复，等待更多主节点
    │              │
    │              ↓
    │         继续检测...
    │
    └──────── 当前数量 ≥ 期望数量
                   │
                   ↓
              开始恢复集群状态
```

## 恢复逻辑

```java
// 简化的代码逻辑
if (expectedMasterNodes != -1) {
    if (nodes.getMasterNodes().size() < expectedMasterNodes) {
        // 延迟恢复
        enforceRecoverAfterTime = true;
        reason = "expecting [" + expectedMasterNodes + "] master nodes, " +
                 "but only have [" + nodes.getMasterNodes().size() + "]";
    }
}
```

## 配置建议

## ⚠️ 重要提示

此配置项**已被标记为弃用**，建议使用以下替代方案：

1. **控制主节点数量**: 使用 `discovery.zen.minimum_master_nodes`
2. **控制数据节点数量**: 使用 `gateway.expected_data_nodes`
3. **控制总体节点数量**: 使用 `gateway.expected_nodes`

## 使用替代配置

```yaml
# 推荐使用以下配置替代

# 控制主节点选举所需的最小节点数
discovery.zen.minimum_master_nodes: 2

# 控制数据节点数量
gateway.expected_data_nodes: 3

# 控制总体节点数量
gateway.expected_nodes: 5
```

## 代码示例

## easysearch.yml 配置（已弃用）

```yaml
# 不推荐使用此配置
gateway:
  expected_master_nodes: 3  # 期望 3 个主节点才开始恢复
```

## 推荐的替代配置

```yaml
# 使用 discovery.zen.minimum_master_nodes
cluster:
  discovery:
    zen:
      minimum_master_nodes: 2  # 防止脑裂

# 使用 gateway.expected_data_nodes
gateway:
  expected_data_nodes: 3  # 期望 3 个数据节点
```

## 相关配置

| 配置项 | 状态 | 作用 |
|--------|------|------|
| `gateway.expected_master_nodes` | ⚠️ 已弃用 | 期望的主节点数量 |
| `gateway.expected_data_nodes` | ✅ 推荐 | 期望的数据节点数量 |
| `gateway.expected_nodes` | ⚠️ 已弃用 | 期望的总节点数量 |
| `discovery.zen.minimum_master_nodes` | ✅ 推荐 | 主节点选举所需最小节点数 |
| `gateway.recover_after_master_nodes` | ⚠️ 已弃用 | 恢复所需的主节点数 |

## 使用场景

## 原本的使用场景（已弃用）

此配置原适用于以下场景：

- **大型集群启动**: 确保有足够的主节点参与集群恢复
- **逐步启动**: 协调大型集群的逐步启动过程
- **防止过早恢复**: 在主节点数量不足时防止过早开始恢复

## 推荐的替代方案

| 需求 | 推荐配置 |
|------|----------|
| 防止脑裂 | `discovery.zen.minimum_master_nodes` |
| 确保数据节点数量 | `gateway.expected_data_nodes` |
| 控制恢复时机 | `gateway.recover_after_data_nodes` |

## 配置组合示例

## 生产环境配置（推荐）

```yaml
cluster:
  discovery:
    zen:
      # 防止脑裂：设置为 (master_eligible_nodes / 2) + 1
      minimum_master_nodes: 2

gateway:
  # 确保有足够的数据节点才恢复
  expected_data_nodes: 3

  # 超时后强制恢复
  recover_after_time: 5m
  recover_after_data_nodes: 2
```

## 注意事项

1. **已弃用**: 此配置已被弃用，虽然仍可使用，但建议迁移到替代配置。

2. **仅限主节点**: 此配置只计算有资格成为主节点的节点，不包括纯数据节点。

3. **与 minimum_master_nodes 的区别**:
   - `expected_master_nodes`: 控制何时开始恢复
   - `minimum_master_nodes`: 控制主节点选举

4. **动态更新**: 此配置不支持动态更新，修改后需要重启节点。

5. **设置为 -1**: 值为 -1 表示不等待特定数量的主节点。

6. **升级迁移**: 如果使用此配置，建议在升级时迁移到新的配置方式。