这些 API 属于只读型、诊断型接口，不涉及业务数据的增删改查（CRUD），专门用于快速定位集群健康、资源瓶颈、分片分配等问题。它们是你作为运维或开发人员的“听诊器”和“X光机”。
🛠️ 一、_cat 系列：运维人员的“瑞士军刀”
特点：返回格式为纯文本表格，轻量、直观、可定制列，适合命令行快速查看。 通用参数：
?v: 显示表头（Verbose）。?h=col1,col2: 只显示指定列（Headers）。?s=col:desc: 按某列排序（Sort）。?help: 查看该 API 支持的所有列。
| API 端点 | 功能描述 | 典型排查场景 | 推荐命令示例 |
|---|---|---|---|
/_cat/health | 集群健康摘要 | 快速确认集群是绿/黄/红，是否有未分配分片。 | GET /_cat/health?v |
/_cat/nodes | 节点资源概览 | 哪个节点 CPU 爆满？哪个节点磁盘快满了？主节点是谁？ | GET /_cat/nodes?v&h=name,ip,node.role,master,ram.percent,cpu,disk.used_percent |
/_cat/indices | 索引列表与大小 | 哪个索引占用空间最大？文档数多少？状态是否正常？ | GET /_cat/indices?v&s=size:desc (按大小排序) |
/_cat/shards | 分片分布详情 | 分片是否均匀？是否有分片处于 UNASSIGNED 或 INITIALIZING？ | GET /_cat/shards?v&h=index,shard,prirep,state,node,docs,store |
/_cat/allocation | 磁盘空间分配 | 每个节点用了多少磁盘？剩余多少？是否触达水位线？ | GET /_cat/allocation?v |
/_cat/recovery | 分片恢复进度 | 重启后分片正在恢复？速度如何？还剩多久？ | GET /_cat/recovery?v&active_only=true (只看正在恢复的) |
/_cat/thread_pool | 线程池状态 | 是否有请求被拒绝（rejected）？队列是否满了？ | GET /_cat/thread_pool?v&h=node_name,name,active,queue,rejected |
/_cat/pending_tasks | 待执行集群任务 | 集群卡住了？是否有大量创建索引/分片分配任务在排队？ | GET /_cat/pending_tasks?v |
/_cat/fielddata | 字段数据缓存 | 哪个字段占用了大量堆内存？（可能导致 OOM） | GET /_cat/fielddata?v&s=total:desc |
/_cat/segments | 索引段信息 | 某个索引的 Segment 数量是否过多？（影响查询性能） | GET /_cat/segments/<index-name>?v |
/_cat/templates | 索引模板列表 | 当前有哪些生效的索引模板？优先级如何？ | GET /_cat/templates?v |
/_cat/plugins | 已安装插件 | 集群安装了哪些插件？版本是否一致？ | GET /_cat/plugins?v |
/_cat/master | 主节点信息 | 简单快速查看当前主节点是谁。 | GET /_cat/master?v |
/_cat/nodeattrs | 节点自定义属性 | 查看节点的自定义属性（如冷热节点标识）。 | GET /_cat/nodeattrs?v |
🔍 二、_cluster 系列：集群状态与决策分析
特点：返回 JSON 格式，信息量巨大，适合深入分析集群元数据和分配逻辑。
| API 端点 | 功能描述 | 典型排查场景 | 关键返回字段/说明 |
|---|---|---|---|
/_cluster/health | 详细健康状态 | 比 _cat/health 更详细的 JSON 版，含未分配分片数。 | status, unassigned_shards, delayed_unassigned_shards |
/_cluster/state | 集群完整元数据 | 查看路由表、节点列表、索引映射等底层元数据。 | 注意：数据量极大，建议配合 metric 参数过滤，如 ?metric=blocks,routing_table。 |
/_cluster/stats | 集群统计信息 | 集群整体文档数、存储大小、JVM 使用率概览。 | indices.count, nodes.jvm.mem.heap_used_percent |
/_cluster/allocation/explain | 分片分配解释 ⭐ | 神器！ 解释为什么某个分片无法分配（UNASSIGNED）。 | 返回具体的拒绝原因，如 "disk usage exceeded watermark"。需提供 index, shard, primary 参数。 |
/_cluster/pending_tasks | 待处理任务列表 | 查看阻塞集群操作的任务队列。 | 如果列表很长，说明集群元数据更新阻塞，可能导致写入变慢。 |
/_cluster/reroute | 手动重路由 | (慎用) 手动干预分片分配，如强制分配空分片、取消分配等。 | 通常配合 commands 参数使用，用于灾难恢复。 |
📊 三、_nodes 系列：节点级深度监控
特点：获取单个或所有节点的底层性能指标，是性能调优的核心依据。
| API 端点 | 功能描述 | 典型排查场景 | 关键返回字段/说明 |
|---|---|---|---|
/_nodes/stats | 节点综合统计 | 全方位监控：JVM、线程池、IO、网络、索引/搜索速率。 | 建议过滤：/_nodes/stats/jvm,thread_pool,fs,os 避免返回过大。 |
/_nodes/hot_threads | 热点线程分析 ⭐ | 节点 CPU 100%？查看具体是哪个线程在疯狂计算。 | 返回线程栈信息，可识别是 search、gc 还是 merge 导致的 CPU 飙升。 |
/_nodes/usage | API 使用情况 | 统计各个 API 的调用次数和耗时，找出滥用接口。 | 可查看 rest_actions 统计。 |
/_nodes/info | 节点基本信息 | 查看节点配置、JVM 版本、插件列表、角色定义。 | 确认节点角色是否符合预期 (node.roles)。 |
📂 四、_indices / _stats 系列：索引级性能诊断
特点：针对特定索引或全量索引的性能指标分析。
| API 端点 | 功能描述 | 典型排查场景 | 关键返回字段/说明 |
|---|---|---|---|
/<index>/_stats | 索引详细统计 | 查询/写入速率、缓存命中率、分段数、删除文档数。 | primaries.search.query_time_in_millis, segments.count, docs.deleted |
/<index>/_segments | 分段详细信息 | 查看索引底层的 Lucene 段文件大小、版本、内存占用。 | 段过多会导致查询慢，需 force_merge。 |
/<index>/_recovery | 索引恢复详情 | 查看特定索引的分片恢复进度和速度。 | 适合在大索引迁移或重启后监控。 |
/<index>/_cache/clear | 清除缓存 | (写操作但常用于调试) 清除查询缓存，测试真实性能。 | 用于排除缓存干扰的性能测试。 |
💡 五、实战组合拳：常见故障排查流程
场景 1：集群变黄（Yellow），有分片未分配
- 看概况：
GET /_cat/health?v确认unassigned_shards数量。 - 找位置：
GET /_cat/shards?v&h=index,shard,state找到状态为UNASSIGNED的分片。 - 问原因：
GET /_cluster/allocation/explain(带上上一步找到的 index 和 shard 信息)。这一步直接告诉你为什么分片不分配（通常是磁盘满、节点缺少角色、副本数设置错误等）。
场景 2：写入变慢，甚至报错 429 (Too Many Requests)
- 看拒绝：
GET /_cat/thread_pool?v&h=node_name,name,queue,rejected查看write线程池是否有rejected计数增长。 - 看负载：
GET /_cat/nodes?v&h=name,cpu,ram,load_1m检查节点负载是否过高。 - 看限流：
GET /_cluster/state?metric=blocks查看是否触发了磁盘水位线导致索引被设为read_only。
场景 3：查询极慢，CPU 飙高
- 抓热点：
GET /_nodes/hot_threads?type=cpu&threads=10查看是哪个线程在忙（是search还是gc？）。 - 看缓存：
GET /<index>/_stats?human查看query_cache和fielddata的使用情况。 - 看分段：
GET /_cat/segments/<index>?v&s=segment:desc检查是否 Segment 数量过多。
场景 4：内存溢出（OOM）风险
- 看堆内存：
GET /_cat/nodes?v&h=name,ram.percent,heap.current,heap.max。 - 看字段数据：
GET /_cat/fielddata?v&s=total:desc找出占用内存最大的字段（通常是 text 字段被聚合了）。 - 看 GC：
GET /_nodes/stats/jvm查看 Old GC 的频率和时间。
📝 小贴士
- 加上
?pretty：所有返回 JSON 的 API，加上?pretty参数可以格式化输出，便于阅读。 - 加上
?human：涉及字节数、时间毫秒数的 API，加上?human会自动转换为5mb,2s等可读格式。 - 不要在生产环境随意运行全量
_cluster/state：如果集群元数据很大（几万个索引），这个 API 会消耗大量内存和网络带宽，甚至导致集群卡顿。务必使用metric参数过滤。 - 权限控制：这些 API 大多只需要
monitor或view_index_metadata权限，建议为运维账号配置最小权限原则。
掌握这些 API，你就能在 Elasticsearch 出现问题时，不再盲目猜测，而是像医生看化验单一样，精准定位病灶！
