11.5 常见问题与解决方案 (Troubleshooting)

文档摘要

11.5 常见问题与解决方案 (Troubleshooting) Elasticsearch 常见问题与解决方案 (Troubleshooting) 11.5.1 集群健康状态问题集群健康状态是 Elasticsearch 首要关注的指标。通过集群健康 API 可以快速了解集群的整体运行状况。常见问题：集群状态为 Red (红色): 表明集群功能严重受损，通常意味着有主分片或副本分片未分配，数据丢失风险极高。集群状态为 Yellow (黄色): 表明集群功能部分受损，通常意味着所有主分片已分配，但部分副本分片未分配，集群具有一定的数据冗余风险，且容错能力下降。解决方案及代码实践： 1. 查看集群健康状态: 使用 API 可以获取集群健康状态的详细信息。

11.5 常见问题与解决方案 (Troubleshooting)

Elasticsearch 常见问题与解决方案 (Troubleshooting)

11.5.1 集群健康状态问题

集群健康状态是 Elasticsearch 首要关注的指标。通过集群健康 API 可以快速了解集群的整体运行状况。

常见问题：

集群状态为 Red (红色): 表明集群功能严重受损，通常意味着有主分片或副本分片未分配，数据丢失风险极高。
集群状态为 Yellow (黄色): 表明集群功能部分受损，通常意味着所有主分片已分配，但部分副本分片未分配，集群具有一定的数据冗余风险，且容错能力下降。

解决方案及代码实践：

1. 查看集群健康状态:

使用 _cluster/health API 可以获取集群健康状态的详细信息。


curl -X GET "localhost:9200/_cluster/health?pretty"

返回结果示例 (红色状态):


{
  "cluster_name" : "elasticsearch",
  "status" : "red",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 5,
  "active_shards" : 5,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 5,
  "delayed_unassigned_shards" : 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch" : 0,
  "task_max_waiting_in_queue_millis" : 0,
  "active_shards_percent_as_number" : 50.0
}

返回结果示例 (黄色状态):


{
  "cluster_name" : "elasticsearch",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 5,
  "active_shards" : 5,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 0,
  "delayed_unassigned_shards" : 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch" : 0,
  "task_max_waiting_in_queue_millis" : 0,
  "active_shards_percent_as_number" : 100.0
}

2. 排查未分配分片 (Unassigned Shards):

当集群状态为 Red 或 Yellow 时，通常需要关注 unassigned_shards 的数量。使用 _cluster/allocation/explain API 可以解释分片未分配的原因。


curl -X GET "localhost:9200/_cluster/allocation/explain?pretty"

返回结果示例 (解释分片未分配的原因):


{
  "index" : "my_index",
  "shard" : 0,
  "primary" : true,
  "current_state" : "unassigned",
  "unassigned_info" : {
    "reason" : "CLUSTER_RECOVERY",
    "at" : "2024-08-23T08:00:00.000Z",
    "last_allocation_status" : "no_attempt"
  },
  "can_allocate" : "no",
  "allocate_explanation" : "cannot allocate because cluster is recovering",
  "node_allocation_decisions" : [
    {
      "node_id" : "node-1",
      "node_name" : "node-1",
      "transport_address" : "192.168.1.10:9300",
      "node_attributes" : {
        "ml.machine_memory" : "8589934592",
        "xpack.installed" : "true",
        "ml.max_jvm_size" : "1073741824"
      },
      "decisions" : [
        {
          "decider" : "same_shard",
          "decision" : "NO",
          "explanation" : "the shard cannot be allocated to the same node it was recently allocated to [[my_index][0], node[node-1], previous shard data exists on disk, reuse_store: [true], recover_state: [RECOVER_AFTER_RESTART], recovering: [false], primary: [true]]"
        },
        {
          "decider" : "disk_space",
          "decision" : "NO",
          "explanation" : "the node is above the high disk watermark threshold, preventing allocation [90.0% free disk space used of more than 85.0%]"
        }
      ]
    }
  ]
}

常见未分配原因及解决方案：

CLUSTER_RECOVERY: 集群正在恢复中，等待恢复完成。通常无需手动干预，等待集群自动恢复。
NODE_LEFT: 节点离开集群，导致分片丢失副本。检查节点状态，确保节点正常运行，如果节点永久离线，Elasticsearch 会尝试在其他节点上重新分配副本。
DISK_SPACE_EXCEEDED: 磁盘空间不足，无法分配分片。清理磁盘空间，或增加磁盘容量。
TOO_MANY_REPLICAS: 副本数量超过可用节点数量。减少副本数量或增加节点数量。
INDEX_CREATED_WITH_TOO_MANY_SHARDS: 索引分片数过多，超过节点承载能力。重新评估索引分片策略，考虑减少分片数或增加节点数。

3. 手动重新路由分片 (Reroute Allocation):

在某些情况下，可以手动重新路由分片，例如强制分配未分配的主分片，或将分片移动到特定节点。

强制分配主分片 (谨慎操作，可能导致数据丢失):


curl -X POST "localhost:9200/_cluster/reroute?retry_failed=true&pretty" -H 'Content-Type: application/json' -d'
{
  "commands" : [
    {
      "allocate_primary" : {
        "index" : "my_index",
        "shard" : 0,
        "node" : "node-1",
        "allow_primary" : true
      }
    }
  ]
}
'

移动分片到指定节点:


curl -X POST "localhost:9200/_cluster/reroute?retry_failed=true&pretty" -H 'Content-Type: application/json' -d'
{
  "commands" : [
    {
      "move" : {
        "index" : "my_index",
        "shard" : 0,
        "from_node" : "node-1",
        "to_node" : "node-2"
      }
    }
  ]
}
'

注意： 手动重新路由分片需要谨慎操作，务必理解其影响，并做好数据备份。

Mermaid 图 - 集群健康状态:

11.5.2 索引问题

索引是 Elasticsearch 中数据组织的基本单元。索引问题会直接影响数据写入和查询。

常见问题：

索引创建失败: 由于 mapping 配置错误、索引设置冲突等原因导致索引无法创建。
索引写入性能下降: 写入速度变慢，bulk 请求延迟增加。
索引 mapping 冲突: 尝试写入与 mapping 定义不符的数据类型。
索引只读 (Read-only Index): 索引被设置为只读，无法写入数据。

解决方案及代码实践：

1. 索引创建失败排查:

检查请求体 (Request Body): 仔细检查创建索引的请求体，包括 mapping 定义和 settings 配置，确保语法正确，参数有效。
查看 Elasticsearch 日志: 查看 Elasticsearch 节点日志，通常会记录索引创建失败的详细错误信息，例如 mapping 解析错误、设置冲突等。

创建索引示例 (包含 mapping):


curl -X PUT "localhost:9200/my_index?pretty" -H 'Content-Type: application/json' -d'
{
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "content": { "type": "text" },
      "timestamp": { "type": "date" }
    }
  },
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1
  }
}
'

2. 索引写入性能优化:

Bulk 请求优化: 使用 bulk API 批量写入数据，减少网络开销和 Elasticsearch 开销。合理设置 bulk 请求的大小，通常建议在几 MB 到几十 MB 之间。
Refresh 策略调整: 降低 refresh 频率 (例如 index.refresh_interval: 30s)，减少 refresh 操作带来的资源消耗，但会牺牲数据可见性的实时性。
Translog 设置优化: 调整 translog 的 durability 和 sync_interval 设置，平衡数据安全性和写入性能。
硬件资源检查: 检查 Elasticsearch 节点的 CPU、内存、磁盘 I/O 等资源使用情况，确保资源充足。

Bulk 写入示例 (Python Elasticsearch client):


from elasticsearch import Elasticsearch
from elasticsearch.helpers import bulk
es = Elasticsearch("http://localhost:9200")
actions = [
    {
        "_index": "my_index",
        "_source": {
            "title": "Document 1",
            "content": "This is the content of document 1."
        }
    },
    {
        "_index": "my_index",
        "_source": {
            "title": "Document 2",
            "content": "This is the content of document 2."
        }
    }
]
success, errors = bulk(es, actions)
print(f"Bulk indexed {success} documents, {errors} errors.")

3. 索引 mapping 冲突解决:

当尝试写入与 mapping 定义不符的数据类型时，Elasticsearch 会抛出 mapping 冲突错误。

查看错误信息: 仔细阅读错误信息，明确冲突字段和期望的数据类型。
更新 mapping (谨慎操作): 如果需要修改 mapping，可以尝试使用 _mapping/put API 更新 mapping。 注意： mapping 修改通常具有限制，特别是对于已存在的字段，数据类型修改可能导致数据丢失或查询异常。
重新索引数据: 更安全的方式是创建新的索引，使用新的 mapping 定义，并将数据从旧索引重新索引到新索引。

更新 mapping 示例 (添加新字段):


curl -X PUT "localhost:9200/my_index/_mapping?pretty" -H 'Content-Type: application/json' -d'
{
  "properties": {
    "new_field": { "type": "keyword" }
  }
}
'

4. 索引只读模式解除:

索引被设置为只读模式通常是为了防止误操作或进行数据维护。

查看索引 settings: 使用 _settings API 查看索引的 settings 配置，确认 index.blocks.read_only 或 index.blocks.read_only_allow_delete 是否为 true。
更新索引 settings: 使用 _settings API 将 index.blocks.read_only 或 index.blocks.read_only_allow_delete 设置为 false，解除只读模式。

解除索引只读模式示例:


curl -X PUT "localhost:9200/my_index/_settings?pretty" -H 'Content-Type: application/json' -d'
{
  "index.blocks.read_only": false
}
'

Mermaid 图 - 索引问题排查流程:

11.5.3 查询问题

查询是 Elasticsearch 的核心功能。查询问题会直接影响搜索结果的准确性和响应速度。

常见问题：

查询无结果或结果不准确: 查询语句编写错误、mapping 配置不当、数据索引问题等都可能导致查询结果异常。
查询性能下降 (慢查询): 查询语句复杂、索引数据量过大、资源不足等原因都可能导致查询速度变慢。
查询超时: 查询执行时间超过设定的超时时间，导致查询失败。

解决方案及代码实践：

1. 查询结果排查:

检查查询语句: 仔细检查查询语句的语法和逻辑，确保查询条件、过滤条件、聚合等设置正确。使用 _validate/query API 可以验证查询语句的有效性。
分析查询语句: 使用 _explain API 可以分析查询语句的执行计划，了解查询是如何被分解和执行的，有助于定位性能瓶颈和理解查询结果。
检查 mapping 配置: 确认查询字段的 mapping 类型是否与查询需求匹配，例如 text 类型字段是否使用了 keyword 查询。
检查数据索引: 确认数据是否已成功索引到 Elasticsearch 中，可以使用 term 查询或 match_all 查询验证索引是否存在数据。

验证查询语句示例:


curl -X POST "localhost:9200/my_index/_validate/query?explain&pretty" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match": {
      "title": "elasticsearch"
    }
  }
}
'

分析查询语句示例:


curl -X POST "localhost:9200/my_index/_explain?pretty" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match": {
      "title": "elasticsearch"
    }
  }
}
'

2. 查询性能优化 (慢查询优化):

Profile API 分析: 使用 Profile API 可以详细分析查询的每个阶段的性能消耗，例如 query 阶段、fetch 阶段等，找出性能瓶颈。
Query DSL 优化: 优化查询语句，避免使用过于复杂的查询，尽量使用更高效的查询类型，例如 term 查询代替 match 查询 (当需要精确匹配时)，使用 filter context 替代 query context (当不需要计算相关性评分时)。
索引优化: 优化索引 mapping，例如合理选择字段类型，使用合适的 analyzer，使用 doc_values 提升聚合和排序性能。
Cache 机制利用: Elasticsearch 提供了多种缓存机制，例如 node query cache, shard request cache, query cache 等。合理配置和利用缓存可以显著提升查询性能。
硬件资源升级: 如果查询性能瓶颈在于硬件资源不足，可以考虑升级 Elasticsearch 节点的 CPU、内存、磁盘 I/O 等资源。

使用 Profile API 分析查询性能:


curl -X POST "localhost:9200/my_index/_search?profile&pretty" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match": {
      "title": "elasticsearch"
    }
  }
}
'

Query DSL 优化示例:

使用 term 查询代替 match 查询 (精确匹配):


// 慢查询 (match 查询，会进行分词和模糊匹配)
{
  "query": {
    "match": {
      "title": "Elasticsearch Best Practices"
    }
  }
}
// 快查询 (term 查询，精确匹配)
{
  "query": {
    "term": {
      "title.keyword": "Elasticsearch Best Practices" // 假设 title 字段有 keyword 子字段
    }
  }
}

使用 filter context 替代 query context (不需要评分):


// 慢查询 (query context, 计算评分)
{
  "query": {
    "bool": {
      "must": {
        "match": { "content": "search" }
      },
      "filter": {
        "range": { "timestamp": { "gte": "now-1d" } }
      }
    }
  }
}
// 快查询 (filter context, 不计算评分)
{
  "query": {
    "bool": {
      "must": [
        { "match": { "content": "search" } }, // 仍然需要评分的 query
        { "range": { "timestamp": { "gte": "now-1d" } } } // 移动到 filter context
      ]
    },
    "filter": {
      "range": { "timestamp": { "gte": "now-1d" } }
    }
  }
}

3. 查询超时处理:

调整超时时间: 根据实际查询需求和集群性能，适当调整查询超时时间 (timeout 参数)。
优化查询性能: 通过上述查询性能优化方法，缩短查询执行时间，避免查询超时。
熔断机制: 在客户端或应用层实现熔断机制，当查询超时次数过多时，暂时停止发送查询请求，避免雪崩效应。

设置查询超时时间示例:


curl -X POST "localhost:9200/my_index/_search?timeout=10s&pretty" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match_all": {}
  }
}
'

Mermaid 图 - 查询问题排查和优化流程:

11.5.4 节点和集群问题

节点和集群层面的问题会影响 Elasticsearch 的整体稳定性。

常见问题：

节点宕机或失联: 节点硬件故障、网络问题、JVM 异常等都可能导致节点宕机或与集群失联。
集群脑裂 (Split-Brain): 网络分区导致集群分裂成多个独立的子集群，可能导致数据不一致和数据丢失。
资源瓶颈: CPU、内存、磁盘 I/O 等资源不足导致集群性能下降甚至崩溃。
JVM 内存溢出 (OOM): JVM 堆内存不足导致 JVM 崩溃。

解决方案及代码实践：

1. 节点宕机或失联处理:

监控告警: 配置完善的监控告警系统，及时发现节点宕机或失联。
自动故障转移: Elasticsearch 具有自动故障转移机制，当主节点宕机时，会自动选举新的主节点。当数据节点宕机时，会自动将受影响的分片副本分配到其他节点。
节点重启: 如果节点只是临时故障，可以尝试重启节点恢复。
节点替换: 如果节点硬件故障无法修复，需要替换故障节点。

2. 集群脑裂预防和解决:

discovery.seed_hosts 和 discovery.seed_providers 配置: 正确配置 discovery.seed_hosts 或 discovery.seed_providers，确保节点能够正确发现集群中的其他节点。
minimum_master_nodes 设置: 合理设置 discovery.zen.minimum_master_nodes (Elasticsearch 7 之前) 或 cluster.initial_master_nodes (Elasticsearch 7 及之后)，防止脑裂发生。通常建议设置为 (node_count / 2) + 1。
网络隔离: 确保集群节点之间的网络连接稳定可靠，避免网络分区。
监控脑裂: 监控集群状态和节点连接情况，及时发现脑裂迹象。
手动恢复 (谨慎操作): 如果发生脑裂，可能需要手动干预，例如强制选举主节点，或将部分节点从错误的子集群中移除。 注意： 手动恢复脑裂需要谨慎操作，务必理解其影响，并做好数据备份。

3. 资源瓶颈解决:

监控资源使用情况: 使用监控工具 (例如 Elasticsearch Exporter for Prometheus, Marvel/Kibana Monitoring) 监控集群的 CPU、内存、磁盘 I/O、JVM 内存等资源使用情况。
优化资源配置: 根据监控数据，调整 Elasticsearch 节点的资源配置，例如增加 CPU 核数、内存大小、磁盘容量等。
优化数据模型和查询: 优化数据模型和查询语句，减少资源消耗。
集群扩容: 如果资源瓶颈长期存在，可以考虑水平扩容集群，增加节点数量。

4. JVM 内存溢出 (OOM) 解决:

调整 JVM 堆内存大小: 根据集群负载和数据量，合理调整 JVM 堆内存大小 (-Xms 和 -Xmx 参数)。通常建议设置为物理内存的 50% 左右，但不超过 31GB (避免 Compressed Oops 性能下降)。
排查内存泄漏: 如果 JVM 频繁发生 OOM，可能存在内存泄漏问题。可以使用 JVM 监控工具 (例如 VisualVM, JConsole) 排查内存泄漏原因。
优化数据模型和查询: 优化数据模型和查询语句，减少内存消耗。
GC 调优: 调整 JVM GC 参数，优化垃圾回收效率。

Mermaid 图 - 节点和集群问题排查流程:

11.5.5 日志分析

Elasticsearch 日志是排查问题的重要信息来源。

重要日志文件：

gc.log (垃圾回收日志): 记录 JVM 垃圾回收信息，用于分析 JVM 性能问题。
elasticsearch.log (主日志): 记录 Elasticsearch 运行时的各种事件，包括错误、警告、信息等。
slow_log (慢日志): 记录执行时间超过阈值的慢查询和慢索引请求，用于分析性能瓶颈。

日志分析方法：

关键词搜索: 使用关键词 (例如 error, warn, exception, slow) 搜索日志文件，快速定位异常信息。
时间范围过滤: 根据问题发生的时间范围，过滤日志，缩小分析范围。
日志级别过滤: 根据日志级别 (例如 ERROR, WARN, INFO, DEBUG, TRACE) 过滤日志，关注特定级别的日志信息。
日志聚合分析工具: 使用日志聚合分析工具 (例如 ELK Stack, Splunk, Graylog) 对 Elasticsearch 日志进行集中管理和分析，提高日志分析效率。

代码实践 - 使用 grep 命令搜索日志关键词 (Linux/macOS):


# 搜索 elasticsearch.log 中包含 "error" 关键词的日志行
grep "error" elasticsearch.log
# 搜索 slow_log 中执行时间超过 1 秒的慢查询日志
grep "took\[1s" slow_log

Mermaid 图 - 日志分析流程:

11.5.6 常用 Troubleshooting 工具和技巧

Cluster Health API: _cluster/health - 快速了解集群健康状态。
Cluster Allocation Explain API: _cluster/allocation/explain - 解释分片未分配的原因。
Nodes Stats API: _nodes/stats - 查看节点和集群的统计信息，包括 CPU, 内存, 磁盘, JVM 等。
Nodes Hot Threads API: _nodes/hot_threads - 查看节点热线程信息，分析 CPU 瓶颈。
Indices Stats API: _stats - 查看索引的统计信息，包括文档数, 存储大小, 分片信息等。
Indices Segments API: _segments - 查看索引段信息，了解索引合并情况。
Tasks API: _tasks - 查看集群中正在运行的任务，例如索引创建, 分片分配, 查询等。
Profile API: _search?profile - 详细分析查询性能。
Explain API: _explain - 分析查询语句执行计划。
Validate Query API: _validate/query - 验证查询语句有效性。
Slow Logs: 配置 slow query log 和 slow index log，记录慢查询和慢索引请求。
Monitoring Tools: 使用 Elasticsearch 官方的 Monitoring 功能 (原 Marvel) 或第三方监控工具 (例如 Prometheus + Grafana, Kibana Monitoring) 监控集群状态和性能指标。
日志分析工具: 使用 ELK Stack, Splunk, Graylog 等日志聚合分析工具管理和分析 Elasticsearch 日志。

总结:

Elasticsearch Troubleshooting 涉及多个层面，从集群健康状态到索引、查询、节点、集群以及日志分析。掌握常用的 Troubleshooting 工具和技巧，结合代码实践和日志分析，能够帮助我们快速定位和解决 Elasticsearch 常见问题，保障集群的稳定性和性能。在实际应用中，建议结合监控告警系统，提前预防和发现潜在问题，并定期进行性能优化和容量规划，确保 Elasticsearch 集群高效稳定运行。

作者与出处

原作者：灏天文库

来源：灏天文库

原文： https://aiknowledge.cn/collection/206-elasticsearch%E6%90%9C%E7%B4%A2%E5%BC%95%E6%93%8E%E5%AE%9E%E6%88%98%E6%95%99%E7%A8%8B

整理：灏天文库整理

由灏天文库平台收录，内容或由平台用户上传，仅供学习交流