---
title: "网关期望节点数配置"
date: 2026-01-08
lastmod: 2026-01-08
description: "控制集群恢复时期望的节点数量配置项说明"
tags: ["集群配置", "网关配置", "集群恢复"]
summary: "配置项作用 #  gateway.expected_nodes 配置项指定集群恢复时期望的节点数量。当集群重启时，此配置控制必须有多少个节点加入后才开始恢复集群状态。
配置项类型 #  该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。
默认值 #  -1（禁用此检查） 是否必需 #  可选配置项（已弃用）
取值范围 #  -1 ~ 正整数 配置格式 #  # 禁用（默认） gateway.expected_nodes: -1 # 期望 3 个节点后恢复 gateway.expected_nodes: 3 # 期望 5 个节点后恢复 gateway.expected_nodes: 5 相关配置项 #     配置项 默认值 说明     gateway.expected_nodes -1 期望的总节点数（已弃用）   gateway.expected_data_nodes -1 期望的数据节点数   gateway.expected_master_nodes -1 期望的主节点数（已弃用）   gateway."
---


## 配置项作用

`gateway.expected_nodes` 配置项指定集群恢复时期望的节点数量。当集群重启时，此配置控制必须有多少个节点加入后才开始恢复集群状态。

## 配置项类型

该配置项为**静态配置**，需要在启动时设置，修改后需要重启节点才能生效。

## 默认值

```
-1（禁用此检查）
```

## 是否必需

**可选配置项**（已弃用）

## 取值范围

```
-1 ~ 正整数
```

## 配置格式

```yaml
# 禁用（默认）
gateway.expected_nodes: -1

# 期望 3 个节点后恢复
gateway.expected_nodes: 3

# 期望 5 个节点后恢复
gateway.expected_nodes: 5
```

## 相关配置项

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `gateway.expected_nodes` | -1 | 期望的总节点数（已弃用） |
| `gateway.expected_data_nodes` | -1 | 期望的数据节点数 |
| `gateway.expected_master_nodes` | -1 | 期望的主节点数（已弃用） |
| `gateway.recover_after_nodes` | -1 | 恢复前最少节点数（已弃用） |
| `gateway.recover_after_data_nodes` | -1 | 恢复前最少数据节点数 |
| `gateway.recover_after_time` | 0 | 恢复前等待时间 |
| `gateway.recover_after_master_nodes` | 0 | 恢复前最少主节点数（已弃用） |

## 工作原理

集群恢复过程：

```
┌─────────────────────────────────────────────────────────────────┐
│                    集群重启恢复流程                              │
└─────────────────────────────────────────────────────────────────┘

节点启动
    │
    ▼
等待其他节点
    │
    ├── gateway.expected_nodes: 3
    │
    └── 检查当前节点数
         │
         ├── 节点数 < 3
         │   │
         │   └── 继续等待，阻塞集群恢复
         │
         └── 节点数 >= 3
              │
              ▼
         开始集群恢复
              │
              ├── 从持久化存储读取集群状态
              ├── 恢复索引元数据
              └── 开始分片分配
```

## 使用场景

### 1. 小型集群（3 节点）

```yaml
gateway.expected_nodes: 3
gateway.expected_data_nodes: 2
```

**效果：** 必须至少 3 个节点（其中 2 个为数据节点）加入才开始恢复。

### 2. 大型集群（7 节点）

```yaml
gateway.expected_nodes: 7
gateway.expected_data_nodes: 5
```

**效果：** 确保大多数节点加入后才开始恢复，避免数据不一致。

### 3. 禁用检查（默认）

```yaml
gateway.expected_nodes: -1
```

**效果：** 节点启动后立即恢复，无需等待其他节点。

## 与 recover_after_time 的配合

```yaml
# 方式 1：仅节点数控制
gateway.expected_nodes: 3

# 方式 2：仅时间控制
gateway.recover_after_time: 5m

# 方式 3：节点数或时间（先到者触发）
gateway.expected_nodes: 3
gateway.recover_after_time: 5m
# 3 个节点加入后，或 5 分钟后开始恢复
```

## 推荐配置

| 场景 | expected_nodes | expected_data_nodes | 说明 |
|-----|---------------|---------------------|------|
| 开发/测试 | -1 | -1 | 禁用检查 |
| 生产（3节点） | 3 | 2 | 确保完整集群 |
| 生产（5节点） | 5 | 3 | 高可用要求 |
| 生产（7节点） | 7 | 5 | 大型集群 |

## 集群重启最佳实践

```yaml
# 完整配置示例
gateway.expected_nodes: 3
gateway.expected_data_nodes: 2
gateway.recover_after_time: 5m
```

**行为：**

1. 如果 3 个节点在 5 分钟内加入 → 立即恢复
2. 如果 5 分钟后节点数不足 → 也开始恢复

## 弃用说明

此配置项已被弃用，建议使用以下配置替代：

| 旧配置 | 新配置 |
|-------|-------|
| `gateway.expected_nodes` | 无直接替代 |
| `gateway.expected_master_nodes` | 无直接替代 |
| `gateway.recover_after_nodes` | `gateway.recover_after_data_nodes` |

## 监控建议

```bash
# 查看集群状态
GET /_cluster/health

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

# 查看集群是否在恢复中
GET /_cluster/state
```

## 常见问题

**问题 1：集群无法启动**

**可能原因：** 配置的期望节点数无法达到

**解决方案：**

1. 检查网络连接
2. 检查节点配置
3. 降低期望节点数或设置为 -1

**问题 2：恢复等待时间过长**

**可能原因：** 某些节点无法加入集群

**解决方案：**

```yaml
# 添加超时时间
gateway.recover_after_time: 5m
```

## 注意事项

1. **已弃用**：此配置项已弃用，新部署应避免使用
2. **静态配置**：修改需要重启节点
3. **集群恢复**：影响集群重启时的恢复行为
4. **配合使用**：应与 `recover_after_time` 配合使用
5. **规划节点数**：根据实际集群规模设置合理的值