---
title: "查询节点"
date: 2026-03-13
lastmod: 2026-03-13
description: "介绍如何使用 Cat API 查询 Easysearch 集群中所有节点的详细信息和统计指标。"
tags: ["Cat API", "节点", "监控", "集群管理"]
summary: "此 API 用于显示集群中所有节点的详细信息和统计指标。
API #  GET /_cat/nodes API 的作用 #  返回集群中所有节点的全面信息，包括：
 基本信息：节点 ID、名称、IP 地址、端口等 版本信息：Easysearch 版本、构建信息、JDK 版本 资源使用：磁盘、内存、CPU 使用情况 统计信息：索引、搜索、合并等操作的统计数据 角色信息：主节点标记、节点角色（数据/摄取/协调）  API 的参数 #  此 API 没有路由参数。
查询字符串参数 #     参数 类型 是否必需 默认值 描述     bytes string 可选 b 字节大小单位
可选值：b, k, kb, m, mb, g, gb, t, tb, p, pb   format string 可选 text 响应格式"
---


此 API 用于显示集群中所有节点的详细信息和统计指标。

## API

```
GET /_cat/nodes
```

## API 的作用

返回集群中所有节点的全面信息，包括：

- **基本信息**：节点 ID、名称、IP 地址、端口等
- **版本信息**：Easysearch 版本、构建信息、JDK 版本
- **资源使用**：磁盘、内存、CPU 使用情况
- **统计信息**：索引、搜索、合并等操作的统计数据
- **角色信息**：主节点标记、节点角色（数据/摄取/协调）

## API 的参数

此 API **没有**路由参数。

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `bytes` | string | 可选 | b | 字节大小单位<br>可选值：`b`, `k`, `kb`, `m`, `mb`, `g`, `gb`, `t`, `tb`, `p`, `pb` |
| `format` | string | 可选 | text | 响应格式<br>可选值：`json`, `yaml`, `text` |
| `full_id` | boolean | 可选 | false | 是否显示完整的节点 ID |
| `h` | string | 可选 | 默认列 | 指定显示的列，逗号分隔 |
| `help` | boolean | 可选 | false | 显示帮助信息 |
| `local` | boolean | 可选 | false | 是否从本地节点获取信息 |
| `master_timeout` | time | 可选 | 30s | 等待主节点响应的超时时间 |
| `s` | string | 可选 | - | 排序列，支持 `:asc` 和 `:desc` |
| `size` | string | 可选 | - | 数量大小单位<br>可选值：`k`, `m`, `g`, `t`, `p` |
| `time` | string | 可选 | ms | 时间单位<br>可选值：`nanos`, `micros`, `ms`, `s`, `m`, `h`, `d` |
| `ts` | boolean | 可选 | true | 是否显示时间戳 |
| `v` | boolean | 可选 | false | 详细模式，显示列头 |

## 返回的字段信息

### 基本信息字段

| 列名 | 描述 |
|------|------|
| `id` | 节点唯一标识符（默认显示前 4 个字符） |
| `pid` | 进程 ID |
| `ip` | IP 地址 |
| `port` | 传输端口 |
| `http_address` | HTTP 地址 |
| `name` | 节点名称 |

### 版本信息字段

| 列名 | 描述 |
|------|------|
| `version` | Easysearch 版本 |
| `flavor` | 发行版本类型 |
| `type` | 发行类型 |
| `build` | 构建哈希值 |
| `jdk` | JDK 版本 |

### 磁盘信息字段

| 列名 | 描述 |
|------|------|
| `disk.total` | 总磁盘空间 |
| `disk.used` | 已用磁盘空间 |
| `disk.avail` | 可用磁盘空间 |
| `disk.used_percent` | 磁盘使用百分比 |

### 内存信息字段

| 列名 | 描述 |
|------|------|
| `heap.current` | 当前堆内存使用量 |
| `heap.percent` | 堆内存使用百分比 |
| `heap.max` | 最大堆内存配置 |
| `ram.current` | 当前物理内存使用量 |
| `ram.percent` | 物理内存使用百分比 |
| `ram.max` | 总物理内存 |

### 文件描述符字段

| 列名 | 描述 |
|------|------|
| `file_desc.current` | 当前使用的文件描述符数量 |
| `file_desc.percent` | 文件描述符使用百分比 |
| `file_desc.max` | 最大文件描述符数量 |

### 系统负载字段

| 列名 | 描述 |
|------|------|
| `cpu` | 最近 CPU 使用率 |
| `load_1m` | 1 分钟负载平均值 |
| `load_5m` | 5 分钟负载平均值 |
| `load_15m` | 15 分钟负载平均值 |
| `uptime` | 节点运行时间 |

### 节点角色字段

| 列名 | 描述 |
|------|------|
| `node.role` | 节点角色<br>`m`: 主节点候选<br>`d`: 数据节点<br>`i`: 摄取节点<br>`-`: 仅协调节点 |
| `master` | 主节点标记（`*` 表示当前主节点） |

### 缓存统计字段

| 列名 | 描述 |
|------|------|
| `completion.size` | 完成功能缓存大小 |
| `fielddata.memory_size` | 字段数据缓存大小 |
| `fielddata.evictions` | 字段数据缓存驱逐次数 |
| `query_cache.memory_size` | 查询缓存大小 |
| `query_cache.evictions` | 查询缓存驱逐次数 |
| `query_cache.hit_count` | 查询缓存命中次数 |
| `query_cache.miss_count` | 查询缓存未命中次数 |
| `request_cache.memory_size` | 请求缓存大小 |
| `request_cache.evictions` | 请求缓存驱逐次数 |
| `request_cache.hit_count` | 请求缓存命中次数 |
| `request_cache.miss_count` | 请求缓存未命中次数 |

### 索引操作统计字段

| 列名 | 描述 |
|------|------|
| `indexing.index_current` | 当前索引操作数 |
| `indexing.index_time` | 索引操作耗时 |
| `indexing.index_total` | 索引操作总数 |
| `indexing.index_failed` | 失败的索引操作数 |
| `indexing.delete_current` | 当前删除操作数 |
| `indexing.delete_time` | 删除操作耗时 |
| `indexing.delete_total` | 删除操作总数 |

### 搜索操作统计字段

| 列名 | 描述 |
|------|------|
| `search.query_current` | 当前查询阶段操作数 |
| `search.query_time` | 查询阶段耗时 |
| `search.query_total` | 查询操作总数 |
| `search.fetch_current` | 当前获取阶段操作数 |
| `search.fetch_time` | 获取阶段耗时 |
| `search.fetch_total` | 获取操作总数 |
| `search.scroll_current` | 开放的滚动上下文数 |
| `search.open_contexts` | 开放的搜索上下文数 |

### 合并操作统计字段

| 列名 | 描述 |
|------|------|
| `merges.current` | 当前合并操作数 |
| `merges.total` | 合并操作总数 |
| `merges.total_time` | 合并操作总耗时 |

### 分段统计字段

| 列名 | 描述 |
|------|------|
| `segments.count` | 分段数量 |
| `segments.memory` | 分段内存使用量 |
| `segments.index_writer_memory` | 索引写入器内存使用量 |

## 请求示例

```bash
# 查询所有节点的默认信息
GET /_cat/nodes

# 显示列头
GET /_cat/nodes?v

# 使用 JSON 格式
GET /_cat/nodes?format=json

# 只显示特定列
GET /_cat/nodes?h=name,ip,heap.percent,cpu,load_1m

# 按 CPU 使用率降序排序
GET /_cat/nodes?s=cpu:desc

# 显示完整节点 ID
GET /_cat/nodes?full_id=true

# 设置字节单位为 GB
GET /_cat/nodes?bytes=gb

# 显示帮助信息
GET /_cat/nodes?help
```

## 响应示例

### 文本格式（默认）

```
ip           heap.percent ram.percent cpu load_1m load_5m load_15m node.role master name
10.0.1.10           45          78  15    2.10    2.05     1.98  mdi       *      master-node
10.0.1.11           52          68  22    3.20    2.80     2.50  di        -      data-node-1
10.0.1.12           48          72  18    2.80    2.60     2.40  di        -      data-node-2
10.0.1.13           35          55  10    1.50    1.40     1.30  -         -      coordinating-node
```

### JSON 格式

```json
[
  {
    "ip": "10.0.1.10",
    "heap.percent": "45",
    "ram.percent": "78",
    "cpu": "15",
    "load_1m": "2.10",
    "load_5m": "2.05",
    "load_15m": "1.98",
    "node.role": "mdi",
    "master": "*",
    "name": "master-node"
  }
]
```

## 使用场景

1. **集群监控**：实时监控各节点的资源使用情况
2. **负载均衡检查**：确认负载在节点间分布是否均匀
3. **性能分析**：分析索引、搜索等操作的性能指标
4. **容量规划**：评估资源使用，规划节点扩容
5. **问题排查**：诊断节点相关的性能和稳定性问题

## 节点角色说明

| 角色 | 标识 | 描述 |
|------|------|------|
| 主节点候选 | `m` | 可以被选举为主节点 |
| 数据节点 | `d` | 存储数据和执行数据相关操作 |
| 摄取节点 | `i` | 执行摄取管道预处理数据 |
| 协调节点 | `-` | 处理客户端请求，分发搜索和聚合 |

一个节点可以同时具有多个角色，如 `mdi` 表示同时具备主节点候选、数据节点和摄取节点功能。

## 注意事项

1. 此 API 只支持 GET 方法
2. 默认只显示节点 ID 的前 4 个字符，使用 `full_id=true` 显示完整 ID
3. `local=true` 时可能返回过时信息，但响应更快
4. 大量节点时响应时间可能较长
5. 某些统计字段可能为空或显示 `-`

## 最佳实践

1. **定期监控**：定期检查各节点的资源使用情况
2. **告警设置**：对 CPU、内存、磁盘使用率设置告警阈值
3. **均衡分布**：确保数据和负载均匀分布在各节点
4. **专用角色**：大规模集群建议使用专用角色节点
5. **文件描述符**：监控文件描述符使用，避免耗尽

## 相关文档

- [查询主节点](./get-master-node.md)
- [查询集群健康](./get-cluster-health-cat-format.md)
- [获取节点信息](./get-node-info.md)
- [获取节点统计信息](./get-node-stats.md)