ElasticSearch常用集群API介绍

一、集群健康 API

1. 概述 Elasticsearch 的集群健康 API 用于获取集群的健康状态信息。这对于监控集群状态、发现潜在问题至关重要。集群健康状态分为三种：绿色（所有分片都可用且已复制）、黄色（所有主分片都可用，但部分副本分片不可用）、红色（部分主分片不可用）。
2. API 调用 使用 GET 请求访问 /_cluster/health 端点即可获取集群健康信息。以下是使用 cURL 命令的示例：

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

响应示例：

{
    "cluster_name": "my_cluster",
    "status": "green",
    "timed_out": false,
    "number_of_nodes": 3,
    "number_of_data_nodes": 3,
    "active_primary_shards": 5,
    "active_shards": 10,
    "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
}

在上述响应中，status 字段显示了集群的健康状态，number_of_nodes 表示集群中的节点数，active_primary_shards 和 active_shards 分别表示活动的主分片和所有活动分片的数量等。

3. 深入理解

• 状态含义：绿色状态表明集群处于最佳状态，所有数据都可访问且有副本保障高可用性。黄色状态虽然主分片可用，但副本分片缺失，这意味着在主分片故障时可能无法提供高可用。红色状态下部分主分片不可用，此时集群部分数据不可访问，需要尽快排查修复。
• 影响因素：节点故障、网络问题、磁盘空间不足等都可能导致集群健康状态变化。例如，当一个节点因磁盘空间满而脱机时，该节点上的分片可能变为未分配状态，从而影响集群健康。

二、集群状态 API

1. 概述 集群状态 API 提供了关于集群的详细状态信息，包括节点、分片、路由等。与集群健康 API 相比，它提供了更全面深入的数据，有助于深入分析集群内部运行情况。
2. API 调用 使用 GET 请求访问 /_cluster/state 端点。例如：

curl -X GET "localhost:9200/_cluster/state"

响应内容非常丰富，简化示例如下：

{
    "cluster_name": "my_cluster",
    "version": 23,
    "state_uuid": "Y82XvWm6T86t13246161",
    "master_node": "D9f123456789abcdef",
    "nodes": {
        "D9f123456789abcdef": {
            "name": "node1",
            "transport_address": "192.168.1.10:9300",
            "attributes": {
                "rack": "rack1"
            }
        },
        "E9f123456789abcdef": {
            "name": "node2",
            "transport_address": "192.168.1.11:9300",
            "attributes": {
                "rack": "rack1"
            }
        }
    },
    "routing_table": {
        "indices": {
            "my_index": {
                "shards": {
                    "0": [
                        {
                            "state": "STARTED",
                            "primary": true,
                            "node": "D9f123456789abcdef",
                            "relocating_node": null,
                            "shard": 0,
                            "index": "my_index"
                        },
                        {
                            "state": "STARTED",
                            "primary": false,
                            "node": "E9f123456789abcdef",
                            "relocating_node": null,
                            "shard": 0,
                            "index": "my_index"
                        }
                    ]
                }
            }
        }
    }
}

3. 深入理解

• 节点信息：nodes 部分详细列出了集群中的各个节点，包括节点名称、传输地址以及自定义属性（如示例中的 rack 信息）。这对于了解集群的物理布局和节点特性很有帮助。
• 路由表：routing_table 展示了索引的分片分布情况。通过它可以清晰地看到每个分片位于哪个节点，以及是主分片还是副本分片。这对于分析数据分布、故障排查以及优化集群性能非常关键。例如，当发现某个节点负载过高时，可以通过路由表查看是否有过多分片集中在该节点，进而考虑重新分配分片。

三、集群统计 API

1. 概述 集群统计 API 用于获取集群的各种统计信息，涵盖了节点、索引、存储等多个方面。这些统计数据有助于监控集群资源使用情况、性能瓶颈等。
2. API 调用 通过 GET 请求访问 /_cluster/stats 端点，如：

curl -X GET "localhost:9200/_cluster/stats"

响应示例（简化）：

{
    "_nodes": {
        "total": 3,
        "successful": 3,
        "failed": 0
    },
    "cluster_name": "my_cluster",
    "nodes": {
        "count": {
            "total": 3,
            "data": 3,
            "master": 1,
            "ingest": 3
        },
        "fs": {
            "total": {
                "total_in_bytes": 107374182400,
                "free_in_bytes": 53687091200,
                "available_in_bytes": 42949672960
            }
        },
        "indices": {
            "docs": {
                "count": 1000,
                "deleted": 0
            },
            "store": {
                "size_in_bytes": 10485760
            }
        }
    }
}

3. 深入理解

• 节点统计：nodes.count 部分展示了不同类型节点（如数据节点、主节点、摄取节点）的数量。这有助于了解集群的节点构成。
• 文件系统统计：fs 部分提供了节点文件系统的总空间、可用空间和空闲空间等信息。当可用空间接近阈值时，可能需要考虑清理磁盘或添加新的存储设备，以避免因磁盘空间不足导致节点故障。
• 索引统计：indices.docs 显示了索引中的文档数量和已删除文档数量，indices.store 给出了索引占用的存储空间大小。通过这些数据，可以评估索引的增长趋势，提前规划存储资源。

四、节点信息 API

1. 概述 节点信息 API 用于获取集群中各个节点的详细信息，包括节点配置、插件、统计等。这对于深入了解每个节点的运行状况、排查节点特定问题非常有用。
2. API 调用 使用 GET 请求访问 /_nodes 端点获取所有节点信息，若要获取特定节点信息，可在 /_nodes 后跟上节点 ID，如 /_nodes/node_id。示例：

curl -X GET "localhost:9200/_nodes"

响应示例（简化部分节点信息）：

{
    "_nodes": {
        "total": 3,
        "successful": 3,
        "failed": 0
    },
    "cluster_name": "my_cluster",
    "nodes": {
        "D9f123456789abcdef": {
            "name": "node1",
            "transport_address": "192.168.1.10:9300",
            "host": "192.168.1.10",
            "ip": "192.168.1.10",
            "version": "7.10.2",
            "build_flavor": "default",
            "build_type": "tar",
            "build_hash": "23456789abcdef0123",
            "roles": [
                "master",
                "data",
                "ingest"
            ],
            "attributes": {
                "rack": "rack1"
            },
            "settings": {
                "path": {
                    "data": "/var/lib/elasticsearch/data",
                    "logs": "/var/log/elasticsearch"
                }
            },
            "os": {
                "name": "Linux",
                "version": "5.4.0-80-generic",
                "build": "5.4.0-80-generic",
                "architecture": "x86_64"
            },
            "process": {
                "refresh_interval_in_millis": 1000,
                "max_file_descriptors": 65536
            },
            "jvm": {
                "version": "11.0.11",
                "vm_name": "OpenJDK 64-Bit Server VM",
                "vm_version": "11.0.11+9-LTS",
                "vm_vendor": "AdoptOpenJDK",
                "heap_used_in_bytes": 268435456,
                "heap_max_in_bytes": 1073741824
            }
        }
    }
}

3. 深入理解

• 节点基础信息：包括节点名称、传输地址、版本、构建信息等，这些信息有助于确保集群中各节点的一致性和兼容性。例如，如果在升级部分节点版本时出现问题，可以通过这些信息确认版本差异。
• 角色和属性：roles 字段明确了节点承担的角色（主节点、数据节点、摄取节点等），attributes 中的自定义属性（如 rack）有助于对节点进行分类管理，如在多机架环境中进行资源分配和故障隔离。
• 系统和 JVM 信息：os 部分展示了节点操作系统相关信息，process 提供了进程相关设置，jvm 给出了 JVM 的版本、堆使用情况等。通过 JVM 堆使用信息，可以监控节点内存使用是否合理，避免因内存不足导致节点性能下降或崩溃。

五、集群更新设置 API

1. 概述 集群更新设置 API 允许动态修改集群的各种设置，如索引的默认副本数、分片分配策略等。通过此 API，可以灵活调整集群配置以适应不同的业务需求和运行状况。
2. API 调用 使用 PUT 请求访问 /_cluster/settings 端点，并在请求体中指定要更新的设置。例如，要将集群中所有新创建索引的默认副本数从 1 改为 2：

curl -X PUT "localhost:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
    "persistent": {
        "index": {
            "number_of_replicas": 2
        }
    }
}
'

这里 persistent 表示设置会持久化到配置文件中，重启集群后依然生效。若使用 transient，则设置仅在当前集群运行期间有效。 3. 深入理解

• 设置类型：
• 持久化设置（persistent）：修改后会写入集群的配置文件，重启后仍然保持。常用于一些长期有效的配置更改，如默认索引副本数、分片分配的一些策略等。
• 临时设置（transient）：只在当前集群运行期间生效，集群重启后设置将恢复为原来的值。适用于一些临时调整，如在进行数据迁移时临时调整分片分配延迟时间。
• 影响范围：对索引相关的设置（如 index.number_of_replicas），会影响新创建的索引。对于已经存在的索引，可能需要通过索引更新设置 API 单独调整。在修改一些全局设置时，需要谨慎评估对整个集群的影响，如修改分片分配策略可能会导致大量分片重新分配，影响集群性能。

六、集群分片分配 API

1. 概述 集群分片分配 API 用于控制分片在节点间的分配。这在处理节点故障、负载均衡、数据迁移等场景中非常重要。通过该 API，可以手动干预分片的分配，以优化集群性能和数据可用性。
2. API 调用

• 获取分片分配信息：使用 GET 请求访问 /_cluster/allocation/explain 端点，并在请求体中指定索引和分片编号。例如，获取 my_index 索引中分片 0 的分配解释：

curl -X GET "localhost:9200/_cluster/allocation/explain" -H 'Content-Type: application/json' -d'
{
    "index": "my_index",
    "shard": 0
}
'

• 取消未分配分片：如果有未分配的分片，并且确定不需要恢复该分片，可以使用 DELETE 请求访问 /_cluster/allocation/explain 端点，并在请求体中指定索引和分片编号。例如：

curl -X DELETE "localhost:9200/_cluster/allocation/explain" -H 'Content-Type: application/json' -d'
{
    "index": "my_index",
    "shard": 0
}
'

3. 深入理解

• 分配解释：/_cluster/allocation/explain 返回的信息详细说明了分片为什么被分配到某个节点，或者为什么未分配。这包括节点的各种条件（如磁盘空间、负载、节点角色等）对分配决策的影响。通过分析这些信息，可以找出导致分片分配异常的原因，如某个节点磁盘空间不足导致分片无法分配。
• 取消未分配分片：在某些情况下，如分片数据已损坏且无法恢复，或者该分片对应的数据源已不存在，可以使用取消未分配分片的 API。但要谨慎操作，因为这会永久删除该分片的数据。在执行此操作前，应确保已备份相关数据或确认该分片不再需要。

七、集群节点重启和关闭 API

1. 概述 在对节点进行维护、升级等操作时，需要安全地重启或关闭节点。集群节点重启和关闭 API 提供了一种受控的方式来执行这些操作，确保集群在操作过程中尽量保持稳定。
2. API 调用

• 关闭节点：使用 POST 请求访问 /_cluster/nodes/{node_id}/_shutdown 端点，其中 {node_id} 为要关闭的节点 ID。例如：

curl -X POST "localhost:9200/_cluster/nodes/D9f123456789abcdef/_shutdown"

• 重启节点：Elasticsearch 本身没有直接的 API 来重启节点，但可以结合系统命令（如在 Linux 上使用 systemctl restart elasticsearch）与关闭 API 来实现类似效果。先使用关闭 API 安全关闭节点，然后通过系统命令重启 Elasticsearch 服务。

3. 深入理解

• 关闭过程：当使用关闭 API 时，Elasticsearch 会先将该节点上的分片迁移到其他节点（如果有副本分片且集群健康允许），以确保数据的可用性。这个过程中，集群会进入一个过渡状态，可能会影响部分读写性能。在关闭节点前，应确保集群有足够的资源来承载迁移的分片。
• 重启注意事项：在重启节点时，要注意节点启动顺序以及与集群中其他节点的兼容性。特别是在进行版本升级时，应按照官方文档的建议顺序重启节点，以避免因版本不一致导致的集群问题。同时，在重启前应备份节点的重要配置文件和数据目录，以防万一。

八、集群别名管理 API

1. 概述 集群别名管理 API 用于在集群级别创建、删除和管理索引别名。别名是指向一个或多个索引的可替代名称，它提供了一种灵活的方式来组织和访问索引，特别是在索引滚动、数据迁移等场景中非常有用。
2. API 调用

• 创建别名：使用 PUT 请求访问 /_aliases 端点，并在请求体中指定别名和对应的索引。例如，为 my_index 创建一个别名 my_alias：

curl -X PUT "localhost:9200/_aliases" -H 'Content-Type: application/json' -d'
{
    "actions": [
        {
            "add": {
                "index": "my_index",
                "alias": "my_alias"
            }
        }
    ]
}
'

• 删除别名：同样使用 PUT 请求访问 /_aliases 端点，在请求体中指定删除操作。例如，删除 my_alias 别名：

curl -X PUT "localhost:9200/_aliases" -H 'Content-Type: application/json' -d'
{
    "actions": [
        {
            "remove": {
                "index": "my_index",
                "alias": "my_alias"
            }
        }
    ]
}
'

3. 深入理解

• 别名的用途：
• 索引滚动：在进行索引滚动以实现数据的持续写入时，可以通过别名始终指向最新的索引，应用程序无需关心实际的索引名称变化。例如，当旧索引达到一定大小或时间限制时，创建新索引并将别名切换到新索引，应用程序通过别名读写数据不受影响。
• 数据迁移：在将数据从一个索引迁移到另一个索引时，可使用别名暂时指向两个索引，在迁移完成后再将别名指向新索引，从而实现无缝切换，减少对应用程序的影响。
• 别名与索引关系：一个别名可以指向多个索引，也可以通过过滤条件（如 routing、filter 等）对指向的索引进行更细粒度的控制。例如，可以创建一个别名，根据文档的某个字段值来决定实际访问哪个索引，这在数据分区管理中有很大的应用价值。

九、集群模板管理 API

1. 概述 集群模板管理 API 用于创建、更新和删除索引模板。索引模板定义了新索引的设置、映射和别名等默认配置，当创建新索引时，如果索引名称匹配模板的模式，模板的配置将应用到该索引。这有助于确保集群中索引配置的一致性和规范性。
2. API 调用

• 创建模板：使用 PUT 请求访问 /_template/{template_name} 端点，其中 {template_name} 为模板名称，在请求体中定义模板内容。例如，创建一个名为 my_template 的模板，设置新索引的副本数为 1，映射定义一个 title 字段为 text 类型：

curl -X PUT "localhost:9200/_template/my_template" -H 'Content-Type: application/json' -d'
{
    "index_patterns": ["my_index*"],
    "settings": {
        "number_of_replicas": 1
    },
    "mappings": {
        "properties": {
            "title": {
                "type": "text"
            }
        }
    }
}
'

• 更新模板：与创建模板类似，使用 PUT 请求覆盖已有的模板内容。例如，修改 my_template 模板，将副本数改为 2：

curl -X PUT "localhost:9200/_template/my_template" -H 'Content-Type: application/json' -d'
{
    "index_patterns": ["my_index*"],
    "settings": {
        "number_of_replicas": 2
    },
    "mappings": {
        "properties": {
            "title": {
                "type": "text"
            }
        }
    }
}
'

• 删除模板：使用 DELETE 请求访问 /_template/{template_name} 端点，如删除 my_template 模板：

curl -X DELETE "localhost:9200/_template/my_template"

3. 深入理解

• 模板匹配规则：index_patterns 字段定义了模板匹配的索引名称模式。可以使用通配符（如 *）来匹配多个索引。例如，my_index* 会匹配所有以 my_index 开头的索引名称。在创建新索引时，Elasticsearch 会按照模板的定义来初始化索引的设置、映射等。
• 模板优先级：当有多个模板匹配同一个索引时，具有较高优先级的模板会生效。可以通过在模板中设置 order 字段来指定优先级，order 值越大优先级越高。合理设置模板优先级有助于在复杂环境中精确控制索引的配置。同时，在更新模板时要注意对已有索引的影响，因为模板更新可能会导致新创建的索引配置发生变化。

十、集群监控 API（X-Pack 相关）

1. 概述 如果使用了 Elasticsearch 的 X-Pack 扩展，集群监控 API 提供了更丰富的监控和可视化功能。它可以收集和展示集群的性能指标、节点健康状况、索引使用情况等详细数据，并通过 Kibana 进行直观的展示和分析。
2. API 调用与数据展示

• 启用监控：首先需要确保 X-Pack 已正确安装和配置。在 Elasticsearch 配置文件（elasticsearch.yml）中启用监控功能，例如设置 xpack.monitoring.enabled: true。
• 获取监控数据：X-Pack 提供了一系列 API 来获取监控数据，如 /api/monitoring/v1/clusters/{cluster_uuid}/stats 可获取集群的统计信息。不过，通常更方便的是通过 Kibana 的监控界面来查看数据。在 Kibana 中，进入监控面板，可以看到集群的实时性能图表，如 CPU 使用率、内存使用情况、索引读写速率等。

3. 深入理解

• 监控指标：X-Pack 监控收集的指标非常全面，包括节点级别的 CPU、内存、磁盘 I/O、网络等性能指标，索引级别的文档计数、存储大小、读写操作频率等。通过这些指标，可以实时了解集群的运行状况，及时发现性能瓶颈和潜在问题。例如，通过观察索引的写入速率和磁盘 I/O 指标，可以判断是否存在写入压力过大导致的性能问题。
• 可视化与分析：Kibana 的监控界面提供了直观的可视化工具，支持多种图表类型（如折线图、柱状图、饼图等）来展示监控数据。用户可以通过设置时间范围、过滤条件等对数据进行深入分析。例如，可以对比不同时间段的集群性能，或者查看特定索引在一段时间内的增长趋势。此外，X-Pack 还支持告警功能，可以根据设定的阈值自动发送告警通知，以便及时处理异常情况。

通过对以上 Elasticsearch 常用集群 API 的介绍和深入理解，开发者和运维人员能够更好地管理和优化 Elasticsearch 集群，确保其高效、稳定地运行，满足各种业务场景下的数据存储和检索需求。在实际应用中，应根据具体的业务需求和集群状况，合理使用这些 API，以实现最佳的集群性能和数据可用性。