---
title: "查询分片分配"
date: 2026-02-05
lastmod: 2026-02-05
description: "介绍如何使用 Cat API 查询集群中节点的分片分配和磁盘使用情况。"
tags: ["Cat API", "分片", "监控", "集群管理"]
summary: "此 API 提供集群中每个数据节点的分片分配情况和磁盘使用状态的快照视图。
API #  GET /_cat/allocation GET /_cat/allocation/{nodes} API 的作用 #  返回集群中各个节点的分片分配信息，包括：
 分片数量：每个节点上分配的分片总数 磁盘使用：索引数据占用的磁盘空间 磁盘状态：已用、可用、总容量和使用百分比 节点信息：节点名称、IP 地址和主机名  此 API 是监控集群健康状况和磁盘使用情况的重要工具，特别适合用于集群运维和容量规划。
API 的参数 #  路由参数 #     参数 类型 是否必需 描述     nodes string 可选 节点 ID 或名称列表
可以用逗号分隔多个节点
例如：node1,node2    查询字符串参数 #     参数 类型 是否必需 默认值 描述     bytes string 可选 自动 字节值的显示单位"
---


此 API 提供集群中每个数据节点的分片分配情况和磁盘使用状态的快照视图。

## API

```
GET /_cat/allocation
GET /_cat/allocation/{nodes}
```

## API 的作用

返回集群中各个节点的分片分配信息，包括：

- **分片数量**：每个节点上分配的分片总数
- **磁盘使用**：索引数据占用的磁盘空间
- **磁盘状态**：已用、可用、总容量和使用百分比
- **节点信息**：节点名称、IP 地址和主机名

此 API 是监控集群健康状况和磁盘使用情况的重要工具，特别适合用于集群运维和容量规划。

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必需 | 描述 |
|------|------|----------|------|
| `nodes` | string | 可选 | 节点 ID 或名称列表<br>可以用逗号分隔多个节点<br>例如：`node1,node2` |

### 查询字符串参数

| 参数 | 类型 | 是否必需 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `bytes` | string | 可选 | 自动 | 字节值的显示单位<br>可选值：`b`, `k`, `kb`, `m`, `mb`, `g`, `gb`, `t`, `tb`, `p`, `pb` |
| `format` | string | 可选 | text | 响应格式<br>可选值：`json`, `yaml`, `text` |
| `h` | string | 可选 | 所有列 | 指定要显示的列，逗号分隔<br>例如：`shards,disk.indices,node` |
| `help` | boolean | 可选 | false | 显示帮助信息，包括所有可用列 |
| `local` | boolean | 可选 | false | 是否从本地节点获取信息 |
| `master_timeout` | time | 可选 | 30s | 等待主节点响应的超时时间 |
| `s` | string | 可选 | - | 排序列，支持 `:asc` 和 `:desc`<br>例如：`disk.percent:desc` |
| `v` | boolean | 可选 | false | 详细模式，显示列头 |

## 返回的字段信息

| 列名 | 别名 | 描述 | 对齐方式 |
|------|------|------|----------|
| `shards` | `s` | 节点上的分片数量 | 右对齐 |
| `disk.indices` | `di`, `diskIndices` | ES 索引使用的磁盘空间 | 右对齐 |
| `disk.used` | `du`, `diskUsed` | 已用磁盘空间（包括非 ES 数据） | 右对齐 |
| `disk.avail` | `da`, `diskAvail` | 可用磁盘空间 | 右对齐 |
| `disk.total` | `dt`, `diskTotal` | 所有卷的总容量 | 右对齐 |
| `disk.percent` | `dp`, `diskPercent` | 磁盘使用百分比 | 右对齐 |
| `host` | `h` | 节点的主机名 | 左对齐 |
| `ip` | - | 节点的 IP 地址 | 左对齐 |
| `node` | `n` | 节点名称 | 左对齐 |

## 请求示例

```bash
# 基本查询，显示所有数据节点的分配情况
GET /_cat/allocation

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

# 查询指定节点
GET /_cat/allocation/node1,node2

# 使用 JSON 格式返回
GET /_cat/allocation?format=json

# 只显示特定列
GET /_cat/allocation?h=shards,disk.indices,node

# 按磁盘使用百分比降序排列
GET /_cat/allocation?s=disk.percent:desc

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

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

## 响应示例

### 文本格式（默认）

```
shards disk.indices disk.used disk.avail disk.total disk.percent host ip       node
    15        45gb       60gb       140gb       200gb           30 node1 10.0.1.1 data-node-1
    12        38gb       50gb       150gb       200gb           25 node2 10.0.1.2 data-node-2
    18        52gb       68gb       132gb       200gb           34 node3 10.0.1.3 data-node-3
```

### JSON 格式

```json
[
  {
    "shards": "15",
    "disk.indices": "45gb",
    "disk.used": "60gb",
    "disk.avail": "140gb",
    "disk.total": "200gb",
    "disk.percent": "30",
    "host": "node1",
    "ip": "10.0.1.1",
    "node": "data-node-1"
  },
  {
    "shards": "12",
    "disk.indices": "38gb",
    "disk.used": "50gb",
    "disk.avail": "150gb",
    "disk.total": "200gb",
    "disk.percent": "25",
    "host": "node2",
    "ip": "10.0.1.2",
    "node": "data-node-2"
  }
]
```

### 帮助信息

```
shards    | s                     | number of shards on the node
disk.indices| di, diskIndices     | disk used by ES indices
disk.used  | du, diskUsed         | disk used (total, including non-ES)
disk.avail | da, diskAvail        | disk available
disk.total | dt, diskTotal        | total disk space
disk.percent| dp, diskPercent     | percent disk used
host       | h                    | host name
ip         |                      | ip address
node       | n                    | node name
```

## 使用场景

1. **容量规划**：监控磁盘使用情况，预测存储需求
2. **负载均衡**：检查分片在节点间的分布是否均匀
3. **磁盘告警**：及时发现磁盘使用率过高的节点
4. **节点扩容**：确定需要添加新节点的时机
5. **问题排查**：诊断分片分配不均或磁盘空间问题

## 特殊情况说明

### 未分配分片
如果存在未分配的分片，会显示一行特殊信息：
- `node` 列显示 `UNASSIGNED`
- `shards` 列显示未分配分片数量
- 磁盘相关列显示 `-` 或 `null`

### 非数据节点
对于非数据节点（如 master-only 节点）：
- `disk.indices` 显示 `0`
- 磁盘相关列可能显示 `-` 或 `null`
- 除非明确指定，否则默认不显示

## 磁盘水位线

Easysearch 使用磁盘水位线来决定分片分配：

| 水位线 | 默认值 | 说明 |
|--------|--------|------|
| `cluster.routing.allocation.disk.watermark.low` | 85% | 磁盘使用超过此值，不再分配新分片 |
| `cluster.routing.allocation.disk.watermark.high` | 90% | 磁盘使用超过此值，尝试将分片移到其他节点 |
| `cluster.routing.allocation.disk.watermark.flood_stage` | 95% | 磁盘使用超过此值，阻止所有写入操作 |

## 最佳实践

1. **定期监控**：定期检查磁盘使用情况，避免磁盘满载
2. **设置告警**：对 `disk.percent` 设置告警阈值（如 80%）
3. **均衡分布**：确保分片均匀分布在各节点
4. **预留空间**：建议保持至少 15-20% 的可用磁盘空间
5. **及时扩容**：当多个节点接近水位线时，考虑添加新节点

## 注意事项

1. 默认只显示数据节点（`data:true`）
2. 磁盘使用包括所有数据，不仅仅是 ES 索引数据
3. `local=true` 时可能返回过时信息，但响应更快
4. 磁盘使用百分比基于总磁盘容量，包括非 ES 数据

## 相关文档

- [查询分片](./get-shard.md)
- [查询集群健康](./get-cluster-health-cat-format.md)
- [查询文档数量](./get-doc-count-cat-format.md)
- [查询节点信息](./get-node.md)