DevOps知识中心
DevOps知识中心

排查 Elasticsearch 集群健康问题：分步指南

在 Elasticsearch 中遇到黄色或红色集群状态了吗？这份全面、分步的指南将引导您完成关键诊断过程。学习如何使用重要的 Cat API、理解分配解释，并应用实用解决方案来解决未分配的主分片和副本分片。通过掌握节点连接错误、磁盘空间限制和手动分片重新路由等故障排除技术，以实现快速恢复，从而确保数据安全和集群弹性。

33 浏览量

Elasticsearch 集群健康状况故障排除：分步指南

Elasticsearch 是一个健壮的分布式系统，但与任何分布式架构一样，它需要主动监控和偶尔干预才能保持最佳健康状态。集群健康状态是确定部署的运行就绪性和数据安全性的最关键指标。当集群从 绿色 变为 黄色 或，关键地，变为 红色 时，数据完整性或可用性就会受到威胁。

本综合指南提供了诊断和解决常见 Elasticsearch 集群健康问题的专家步骤，特别关注从黄色和红色状态恢复。我们将使用实用的 Cat API 和分步检查来快速识别根本原因并实施纠正措施。

1. 理解 Elasticsearch 集群健康状态

在进行故障排除之前，必须了解每个集群健康颜色代表的含义。健康状态由集群节点之间主分片和副本分片的分配状态决定。

状态 含义 影响
绿色 所有主分片和副本分片都已成功分配。 集群完全运行并具有弹性。
黄色 所有主分片都已分配，但一个或多个副本分片未分配。 数据可用，但集群缺乏对节点故障的完全弹性。
红色 至少有一个主分片未分配（因此不可用）。 包含故障分片的索引的数据丢失或无法访问。需要关键操作。

2. 初步诊断：检查集群健康状况

任何故障排除过程的第一步是使用集群健康 API 和节点 API 确认当前状态并收集基本指标。

步骤 2.1：检查集群健康状况

使用 _cat/health API 获取高级摘要。?v 参数提供详细输出，包括节点数和总分片数。

GET /_cat/health?v

示例输出（黄色状态）：

epoch      timestamp cluster       status node.total node.data shards  pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
1678233600 09:00:00  my-cluster    yellow 3          3         10     5    0    0        5 0             -                  50.0%

如果状态为黄色或红色，请注意 unassign 下方的值。

步骤 2.2：检查节点状态和内存

确保所有预期的节点都已连接并正常运行。此外，检查堆利用率（对性能和稳定性至关重要）。

GET /_cat/nodes?v&h=name,node.role,version,heap.percent,disk.total,disk.used,disk.avail

如果此列表中缺少某个节点，您可能遇到连接问题或服务已停止。

3. 解决红色集群状态（主分片失败）

红色状态意味着数据立即不可访问。目标是尽快将主分片重新联机。

步骤 3.1：识别未分配的主分片

使用 _cat/shards API 精确定位导致问题的确切索引和分片。特别是查找标记为 UNASSIGNED 且角色为 p（主）的条目。

GET /_cat/shards?v | grep UNASSIGNED

示例输出：

index_logs 0 p UNASSIGNED

步骤 3.2：检查分配解释

这是最重要的诊断步骤。分配解释 API 告诉您特定分片（或任何未分配分片）为何无法分配。

GET /_cluster/allocation/explain

红色状态的常见原因：

  1. 节点故障： 拥有主分片的节点已崩溃或已从集群中移除。如果故障节点有足够的副本在其他节点上，则主分片应自动提升副本。如果所有副本（主副本和副本副本）都在故障节点上，则除非节点恢复，否则分片将丢失。
  2. 数据损坏： 磁盘上的主分片文件已损坏，导致节点无法初始化它们。

步骤 3.3：红色状态的操作计划

  • 场景 A：节点离线（首选）
    • 如果持有主分片的节点只是离线，请恢复节点服务（例如，重新启动 Elasticsearch 或修复网络问题）。节点重新加入集群后，主分片应会恢复。
  • 场景 B：主分片丢失（最后的手段）
    • 如果节点永久丢失且不存在副本，则数据已丢失。您必须使用 allocate_empty_primary 命令手动跳过恢复。警告：这将创建一个全新的、空的初始分片，导致该索引段永久丢失数据。
POST /_cluster/reroute
{
  "commands" : [
    {
      "allocate_empty_primary" : {
        "index" : "[index-name]", 
        "shard" : [shard-id],
        "node" : "[target-node-name]", 
        "accept_data_loss" : true
      }
    }
  ]
}

最佳实践： 在诉诸 allocate_empty_primary 之前，请务必验证该索引是否存在快照或备份。

4. 解决黄色集群状态（副本分片失败）

黄色状态意味着集群运行正常但存在漏洞。主要目标是分配丢失的副本。

步骤 4.1：使用分配解释

如果状态为黄色，请使用 _cluster/allocation/explain API（第 3.2 节）来了解为何无法分配副本。副本的解释通常更直接。

黄色状态的常见原因：

原因代码 解释 修复
NO_AVAILABLE_NODES 集群大小太小（例如，副本数为 2，但只有 2 个节点）。 添加更多数据节点或减少 number_of_replicas。
NOT_ENOUGH_DISK_SPACE 节点达到了低或高水位线阈值。 删除旧索引、释放磁盘空间或调整磁盘水位线。
ALLOCATION_DISABLED 分片分配已被集群设置显式禁用。 使用 PUT /_cluster/settings 重新启用路由。
PRIMARY_NOT_ACTIVE 主分片仍在初始化或恢复中。 等待主分片变为活动状态（绿色）。

步骤 4.2：检查节点要求和约束

确保集群满足副本分配的基本要求：

  1. 节点计数： 对于 N 个副本，您至少需要 N+1 个数据节点，以确保主副本和副本副本永远不会在同一节点上。
  2. 磁盘水位线： 当磁盘使用量超过高水位线（默认 90%）时，Elasticsearch 会停止将分片分配给节点。
# 检查磁盘分配设置
GET /_cluster/settings?flat_settings=true&filter_path=*watermark*

# 示例：将高水位线设置为 95%（临时！）
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.disk.watermark.high": "95%"
  }
}

步骤 4.3：手动重新路由（如果分配逻辑失败）

在极少数情况下，如果标准分配过程似乎停滞不前，尽管有足够资源，您可以使用 allocate_replica 命令手动强制将副本分配给特定的健康节点。

POST /_cluster/reroute
{
  "commands" : [
    {
      "allocate_replica" : {
        "index" : "[index-name]", 
        "shard" : [shard-id],
        "node" : "[target-node-name]"
      }
    }
  ]
}

5. 高级故障排除和常见陷阱

如果红色或黄色状态持续存在，根本原因可能超出了标准的碎片分配逻辑。

5.1 网络连接和脑裂

在分布式系统中，分区（脑裂）会导致严重问题。如果主节点候选节点无法通信，集群可能无法选举稳定的主节点，从而导致分片未分配。

  • 操作： 验证所有节点之间的网络连接，特别是主节点候选节点之间的连接。
  • 配置检查： 确保您的 discovery.seed_hosts 列表准确无误，并且在集群引导过程中正确使用了 cluster.initial_master_nodes 设置。

5.2 高 JVM 内存压力

过度的堆使用（通常高于 75%）会导致频繁、长时间的垃圾回收（GC）暂停。在这些暂停期间，节点可能看起来无响应，导致主节点将其删除，从而导致分片未分配。

  • 操作： 监控堆使用情况（_cat/nodes?h=heap.percent）。如果持续偏高，请考虑升级节点内存、优化索引过程或实施索引生命周期管理 (ILM)。

5.3 分片分配过滤

意外应用分配过滤器（使用节点属性，如标签或 ID）可能会阻止分片分配给可能符合条件的节点。

# 检查索引级别的分配规则
GET /[index-name]/_settings
# 查找：index.routing.allocation.require.*

# 重置索引分配规则（如果需要）
PUT /[index-name]/_settings
{
  "index.routing.allocation.require": null
}

快速恢复摘要清单

状态 主要诊断工具 关键操作步骤
黄色 GET /_cluster/allocation/explain 1. 检查磁盘空间。 2. 验证节点数与副本数。 3. 查看分配过滤规则。 4. 等待主副本恢复。
红色 GET /_cat/shards?v | grep UNASSIGNED 1. 检查先前托管节点的日志。 2. 尝试重新启动故障节点。 3. 如果确认主副本丢失且不存在备份，请使用 allocate_empty_primary（有数据丢失风险）。

通过系统地利用 _cat API 和关键的 _cluster/allocation/explain 端点，您可以快速查明集群健康状况下降的原因，并实施必要的纠正步骤，将集群恢复到稳定的绿色状态。