当 Elasticsearch 集群出现写入延迟升高、节点离线或分片未分配时，第一时间需要获取的信息通常很简单：集群现在是绿色还是红色、哪些节点压力大、哪些索引分片异常。REST 接口返回的完整 JSON 虽然信息全面，但在终端里逐层解析会很吃力。Elasticsearch 提供的 cat API 正是为这种场景设计，它把集群元数据压缩成单行文本或表格，配合少量查询参数就能快速定位问题。本文将围绕 cat API 中与集群信息密切相关的端点展开，介绍常用命令、参数控制以及生产环境巡检技巧。
一、cat API 的设计目标与基本用法
cat API 的设计目标是让人和脚本都能轻松读懂输出。与标准 REST 接口返回的 JSON 结构不同，cat API 默认输出对齐文本，每一行代表一个对象，列之间用空格分隔。例如查看集群健康状态时，一条命令就能得到节点总数、数据节点数、分片数量、未分配分片等核心字段。这种输出格式非常适合在终端中快速浏览，也便于通过 awk、cut 等命令行工具做二次处理。
所有 cat API 都挂在 _cat 路径下，使用 GET 请求访问特定的端点。最常见的入门操作是给命令加上 ?v 参数来显示表头。例如执行下面的命令可以查看集群健康状态，其中 v 表示 verbose，也就是输出列名。不加 ?v 时只有数据行，加了之后第一行会变成字段名，方便理解每一列的含义。
curl -XGET 'http://127.0.0.1:9200/_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 1615471234 10:00:34 my_cluster green 3 2 18 9 0 0 0 0 - 100.0%
可以看到第一行是字段名，第二行是对应的值。status 字段为 green 表示所有主分片和副本分片都已分配，yellow 表示主分片已分配但部分副本未分配，red 则表示有主分片未分配，需要立即处理。通过这一条命令，你就能快速判断集群是否处于健康状态，而不需要解析多层 JSON。
二、核心集群信息端点详解
除了 _cat/health 之外，cat API 还提供了多个专门用于查看集群不同维度信息的端点。其中 _cat/nodes 用于查看每个节点的资源使用情况，_cat/indices 用于查看索引级别的状态和存储占用，_cat/shards 则展示分片分配细节。合理搭配这些端点，可以快速定位是节点资源瓶颈还是索引分片不平衡导致的问题。
查看节点信息时，最常用的是 _cat/nodes 端点。默认输出包含节点名、IP、角色、负载、堆内存使用率等列。如果只想关注某几个关键指标，可以通过 h 参数指定列。下面的命令只输出节点名、IP、堆内存百分比、内存百分比、CPU、1分钟负载、节点角色和主节点标识。
curl -XGET 'http://127.0.0.1:9200/_cat/nodes?v&h=name,ip,heap.percent,ram.percent,cpu,load_1m,node.role,master'
输出会按指定列顺序排列，每一行对应一个节点。通过观察 heap.percent 和 ram.percent 可以判断节点是否存在内存压力，cpu 和 load_1m 则反映计算资源使用情况。如果发现某个节点的 heap.percent 长期接近 100%，很可能需要进行 JVM 参数调整或减少该节点上的分片数量。
索引层级的信息主要通过 _cat/indices 获取。它能列出所有索引的健康状态、文档数、主分片和副本分片数量、存储大小等。在排查磁盘水位问题时，通常先按照存储大小排序，找出占用空间最多的索引。下面这条命令使用 s 参数按 store.size 字段降序排序。
curl -XGET 'http://127.0.0.1:9200/_cat/indices?v&s=store.size:desc'
输出结果中会先显示存储量最大的索引。对于存储占用异常偏高的索引，可以进一步检查其映射设置、段合并情况或者是否有大量删除文档未被回收。如果只关注单个索引，可以在路径后面跟上索引名称，比如 _cat/indices/my_index 只显示该索引的信息。
分片维度的排查则需要使用 _cat/shards。它能展示每个分片的主副状态、所在节点、文档数以及未分配原因。当集群状态为 yellow 或 red 时，执行 _cat/shards?v 并重点关注 state 为 UNASSIGNED 的行，就能看到哪些分片未能分配以及原因。常见原因包括节点磁盘水位过高、分片分配过滤规则限制、索引重建过程中人为关闭分配等。
三、输出格式控制与实战技巧
cat API 最大优势在于输出格式可以灵活切换。除了默认的对齐文本，还可以通过 format 参数指定为 JSON 或 YAML。JSON 格式对于脚本处理非常友好，很多自动化巡检工具会先以 JSON 格式获取数据，再通过 jq 等命令做过滤。例如把健康状态输出为 JSON：
curl -XGET 'http://127.0.0.1:9200/_cat/health?format=json&pretty'
返回的 JSON 是一个数组，每个元素包含一个对象，键名与文本输出的列名一致。这样在 shell 脚本中就可以利用 jq 提取特定字段。下面这段脚本演示了如何获取集群状态并判断是否需要告警：
status=$(curl -s 'http://127.0.0.1:9200/_cat/health?format=json&h=status' | jq -r '.[0].status') if [ "$status" != "green" ]; then echo "Cluster status is $status" fi
使用 h 参数配合 JSON 格式时，返回的 JSON 对象只包含指定字段，能够减少传输数据量。需要注意的是，如果同时指定多个字段，字段名之间用逗号分隔，不能有多余空格。例如 h=status,node.total,active_shards_percent 是合法的，而 h=status, node.total 可能会被解析成包含空格的列名。
在生产环境中频繁执行 _cat/indices 或 _cat/shards 可能会给集群带来一定开销，尤其是在索引数量很多、分片数量上千的场景下。建议将这些命令放在监控脚本中定时执行，而不是在循环中无节制调用。同时可以利用 s 参数排序和 h 参数裁剪字段，减少返回的数据量。对于需要实时展示的场景，可以结合 watch 命令周期性刷新，但间隔不宜过短，一般 10 秒到 30 秒即可满足大多数巡检需求。
cat API 的另一个实用技巧是通过 help 参数查看某个端点支持的所有列名。例如执行 _cat/nodes?help 会列出全部可选字段及其含义。当你需要按某个特殊指标排查问题，但不确定列名时，这个帮助信息非常有用。它还能帮你发现一些不太常用但很有价值的字段，比如 disk.avail、segments.count、suggest.total 等。
Elasticsearchcat API集群信息修改时间：2026-08-20 01:13:29