网关与恢复配置 #

本页介绍 easysearch.yml 中与集群完全重启后分片恢复行为相关的配置项。这些都是静态设置，修改后需要重启节点生效。

分片恢复的限流参数（如 indices.recovery.max_bytes_per_sec）属于动态配置，通过集群配置 API 修改。

为什么需要网关恢复设置？ #

当整个集群重启时，各节点可能以不同的速度启动。如果集群在只有部分节点加入时就立即开始分片恢复，会导致：

不必要的数据搬运：节点 A 先启动，集群把本该在节点 B 上的分片副本重新分配给 A；等 B 启动后又要搬回去。
大量网络 I/O：分片数据在节点间来回传输。
恢复时间变长：所有数据都要重新复制一遍。

网关设置让集群等到足够数量的节点加入后再开始恢复，避免上述问题。

gateway.recover_after_nodes #

gateway.recover_after_nodes: 2

项目	说明
参数	`gateway.recover_after_nodes`
默认值	`-1` (禁用)
属性	静态
说明	集群中至少有多少个节点加入后才开始恢复分片。已弃用：建议改用 `recover_after_data_nodes` 和 `recover_after_master_nodes` 以获得更精确的控制

gateway.expected_nodes #

gateway.expected_nodes: 3

项目	说明
参数	`gateway.expected_nodes`
默认值	`-1` (禁用)
属性	静态
说明	集群预期的总节点数。当加入的节点数达到此值时，立即开始恢复（不等待 `recover_after_time`）。已弃用：建议改用 `expected_data_nodes`

gateway.recover_after_time #

# 生产环境建议显式设置
gateway.recover_after_time: 5m

项目	说明
参数	`gateway.recover_after_time`
默认值	`0ms` (无延迟)
属性	静态
说明	达到 `recover_after_nodes` 后，再等待多长时间才开始恢复。给剩余节点留出加入集群的时间窗口。如果在此期间达到 `expected_nodes`，则提前开始恢复。生产环境建议设为 `5m`

数据节点专用参数 #

如果集群中有角色分离（专用 master + 专用 data），可以单独设置数据节点的恢复条件：

参数	默认值	说明
`gateway.expected_data_nodes`	`-1`	预期的数据节点数。达到后立即开始恢复
`gateway.recover_after_data_nodes`	`-1`	至少有多少数据节点加入后才开始恢复
`gateway.expected_master_nodes`	`-1`	预期的 master 候选节点数（已弃用）
`gateway.recover_after_master_nodes`	`0`	至少有多少 master 候选节点加入后才开始恢复（已弃用），默认跟随 `discovery.zen.minimum_master_nodes`

恢复流程示意 #

集群全量重启
    │
    ▼
等待节点加入...
    │
    ├── 节点数 < recover_after_nodes → 继续等待
    │
    ├── 节点数 ≥ recover_after_nodes
    │       │
    │       ├── 节点数 = expected_nodes → 立即恢复
    │       │
    │       └── 等待 recover_after_time
    │               │
    │               └── 超时 → 开始恢复
    │
    ▼
开始分片恢复（先恢复 primary，再恢复 replica）

恢复条件详解 #

恢复的触发逻辑 #

集群恢复需要满足以下任一条件（按优先级）：

检查基本限制条件（必须先满足）：
- 如果 recover_after_nodes 设置：数据节点数 + master节点数 < recover_after_nodes → 等待
- 如果 recover_after_data_nodes 设置：数据节点数 < recover_after_data_nodes → 等待
- 如果 recover_after_master_nodes 设置：master节点数 < recover_after_master_nodes → 等待
检查期望节点条件（满足任一则可恢复）：
- 如果设置了 expected_* 参数且条件满足 → 立即恢复（跳过超时）
- 如果设置了 recover_after_time → 等待指定时间后恢复
默认行为（都未设置时）：
- 立即开始恢复

源码验证 #

根据 GatewayService.java 源码中的 clusterChanged 方法：

// 恢复被阻止的条件（任一满足则不恢复）
if (recoverAfterNodes != -1 && (nodes.getMasterAndDataNodes().size()) < recoverAfterNodes)
    // 不恢复：总节点数不足
else if (recoverAfterDataNodes != -1 && nodes.getDataNodes().size() < recoverAfterDataNodes)
    // 不恢复：数据节点数不足
else if (recoverAfterMasterNodes != -1 && nodes.getMasterNodes().size() < recoverAfterMasterNodes)
    // 不恢复：主节点数不足
else
    // 检查期望节点：满足则立即恢复，否则等待 recover_after_time

⚠️ 参数弃用说明 #

参数	状态	替代方案
`recover_after_nodes`	已弃用	使用 `recover_after_data_nodes` + `recover_after_master_nodes`
`expected_nodes`	已弃用	使用 `expected_data_nodes`
`expected_master_nodes`	已弃用	使用 `expected_data_nodes` 代替
`recover_after_master_nodes`	已弃用	使用 `discovery.zen.minimum_master_nodes` 代替

为什么弃用？ 新参数提供更精确的控制，区分数据节点和主节点，避免配置歧义。

配置示例 #

三节点集群（推荐配置） #

# 推荐：使用数据节点控制而非总节点数
gateway.recover_after_data_nodes: 2
gateway.expected_data_nodes: 3
gateway.recover_after_time: 5m

含义：2 个数据节点加入后开始计时；5 分钟内第 3 个数据节点也加入则立即恢复；5 分钟后仍只有 2 个数据节点也开始恢复。

三节点集群（传统配置 - 已弃用） #

gateway.recover_after_nodes: 2
gateway.expected_nodes: 3
gateway.recover_after_time: 5m

角色分离集群（3 master + 5 data） #

# 按数据节点数控制
gateway.recover_after_data_nodes: 3
gateway.expected_data_nodes: 5
gateway.recover_after_time: 10m

大规模集群（20+ 节点） #

# 推荐：分别控制数据节点和主节点
gateway.recover_after_data_nodes: 15
gateway.expected_data_nodes: 20
gateway.recover_after_master_nodes: 2
gateway.recover_after_time: 15m