---
title: "查询集群健康（Cat格式）"
date: 2026-01-12
lastmod: 2026-01-12
description: "以表格形式查询集群健康状态"
tags: ["集群", "健康", "Cat API"]
summary: "以紧凑的表格形式返回集群健康状态信息。
API 格式 #  GET /_cat/health API 作用 #  该 API 以表格形式返回集群健康状态：
 显示集群名称和健康状态 显示节点数量（总节点和数据节点） 显示分片统计信息 显示待处理任务信息 显示活跃分片百分比  API 参数 #  查询参数 #     参数 类型 是否必填 默认值 描述     format String 否 文本表格 响应格式（如 json、yaml）   h String 否 所有列 逗号分隔的列名列表   v Boolean 否 false 是否显示列标题   ts Boolean 否 true 是否显示时间戳列   s String 否 - 排序方式（格式：列名:asc 或 列名:desc）    集群健康参数 #     参数 类型 是否必填 默认值 描述     level String 否 cluster 详细程度：cluster、indices、shards   timeout Time 否 30s 操作超时时间   wait_for_status String 否 - 等待指定健康状态：green、yellow、red   wait_for_no_relocating_shards Boolean 否 false 等待直到没有重定位分片   wait_for_no_initializing_shards Boolean 否 false 等待直到没有初始化中的分片   wait_for_active_shards String 否 - 等待指定数量的活跃分片（如 all、1）   wait_for_nodes String 否 - 等待指定数量的节点（如 5、>5、<5）    响应列说明 #     列名 别名 描述     cluster cl 集群名称   status st 健康状态（green/yellow/red）   node."
---


以紧凑的表格形式返回集群健康状态信息。

## API 格式

```
GET /_cat/health
```

## API 作用

该 API 以表格形式返回集群健康状态：
- 显示集群名称和健康状态
- 显示节点数量（总节点和数据节点）
- 显示分片统计信息
- 显示待处理任务信息
- 显示活跃分片百分比

## API 参数

### 查询参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `format` | String | 否 | 文本表格 | 响应格式（如 `json`、`yaml`） |
| `h` | String | 否 | 所有列 | 逗号分隔的列名列表 |
| `v` | Boolean | 否 | `false` | 是否显示列标题 |
| `ts` | Boolean | 否 | `true` | 是否显示时间戳列 |
| `s` | String | 否 | - | 排序方式（格式：`列名:asc` 或 `列名:desc`） |

### 集群健康参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `level` | String | 否 | `cluster` | 详细程度：`cluster`、`indices`、`shards` |
| `timeout` | Time | 否 | `30s` | 操作超时时间 |
| `wait_for_status` | String | 否 | - | 等待指定健康状态：`green`、`yellow`、`red` |
| `wait_for_no_relocating_shards` | Boolean | 否 | `false` | 等待直到没有重定位分片 |
| `wait_for_no_initializing_shards` | Boolean | 否 | `false` | 等待直到没有初始化中的分片 |
| `wait_for_active_shards` | String | 否 | - | 等待指定数量的活跃分片（如 `all`、`1`） |
| `wait_for_nodes` | String | 否 | - | 等待指定数量的节点（如 `5`、`>5`、`<5`） |

## 响应列说明

| 列名 | 别名 | 描述 |
|------|------|------|
| `cluster` | `cl` | 集群名称 |
| `status` | `st` | 健康状态（green/yellow/red） |
| `node.total` | `nt`, `nodeTotal` | 节点总数 |
| `node.data` | `nd`, `nodeData` | 可存储数据的节点数 |
| `shards` | `t`, `sh`, `shardsTotal` | 分片总数 |
| `pri` | `p`, `shardsPrimary` | 主分片数 |
| `relo` | `r`, `shardsRelocating` | 重定位中的分片数 |
| `init` | `i`, `shardsInitializing` | 初始化中的分片数 |
| `unassign` | `u`, `shardsUnassigned` | 未分配的分片数 |
| `pending_tasks` | `pt`, `pendingTasks` | 待处理任务数 |
| `max_task_wait_time` | `mtwt`, `maxTaskWaitTime` | 最长任务等待时间 |
| `active_shards_percent` | `asp`, `activeShardsPercent` | 活跃分片百分比 |
| `timestamp` | - | 响应时间戳 |

## 请求示例

### 查询集群健康

```
GET /_cat/health?v
```

### JSON 格式

```
GET /_cat/health?format=json
```

### 选择显示列

```
GET /_cat/health?h=cluster,status,node.total,shards&v
```

### 等待绿色状态

```
GET /_cat/health?wait_for_status=green&timeout=1m
```

## 响应示例

### 文本表格格式（verbose 模式）

```
timestamp             cluster    status node.total node.data shards pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
2026-02-04 12:00:00   my-cluster green   3          3         15     5    0     0            0                  -                       100.0%
```

### JSON 格式

```json
[
  {
    "cluster": "my-cluster",
    "status": "green",
    "node.total": "3",
    "node.data": "3",
    "shards": "15",
    "pri": "5",
    "relo": "0",
    "init": "0",
    "unassign": "0",
    "pending_tasks": "0",
    "max_task_wait_time": null,
    "active_shards_percent": "100.0%",
    "timestamp": "2026-02-04T12:00:00Z"
  }
]
```

### 黄色状态示例

```
timestamp             cluster    status node.total node.data shards pri relo init unassign pending_tasks max_task_wait_time active_shards_percent
2026-02-04 12:00:00   my-cluster yellow   3          3         15     5    0     1     1               2                  5s                      93.3%
```

## 健康状态说明

| 状态 | 描述 |
|------|------|
| `green` | 所有主分片和副本分片都已分配 |
| `yellow` | 所有主分片已分配，但有部分副本分片未分配 |
| `red` | 有部分主分片未分配 |

## 使用场景

1. **健康监控**：快速查看集群健康状态
2. **故障排查**：检查未分配的分片和待处理任务
3. **容量规划**：查看节点和分片分布
4. **状态等待**：等待集群达到特定健康状态

## 注意事项

1. **v 参数**：使用 `?v` 显示列标题
2. **时间戳**：时间戳自动添加到所有响应
3. **等待参数**：等待参数会阻塞请求直到条件满足
4. **对齐方式**：数值列自动右对齐

## 相关操作

- **GET /_cluster/health**：获取详细健康信息
- **GET /_cat/nodes**：查询节点信息
- **GET /_cat/shards**：查询分片信息
- **GET /_cat/allocation**：查询分片分配解释

## 实现文件

- **REST 处理器**：`RestHealthAction.java`
- **基础类**：`AbstractCatAction.java`