接口干什么用
_cat/shards 按行列出每个索引的每个分片：状态、所在节点、文档数、磁盘占用，以及未分配时的原因。它是排查「分片卡在 UNASSIGNED」「分布倾斜」「某个分片特别大」的第一站接口，输出是纯文本表格，适合直接看或脚本解析。
基本信息
| 适用版本 | Elasticsearch 7.x / 8.x |
|---|---|
| 接口 | GET /_cat/shards?v 或 /_cat/shards/<index>?v |
| 常用参数 | h= 选列、s= 排序、state= 过滤 |
| 关键列 | shard、prirep、state、docs、store、node、unassigned.reason |
| 配套接口 | GET /_cluster/allocation/explain、GET /_cat/allocation?v |
典型使用场景
- 排查未分配分片：过滤 state=unassigned，再顺着 unassigned.reason 找根因
- 检查分布倾斜：看各分片 docs 与 store 是否均匀落在各节点
- 定位大分片：store 明显偏大的分片是合并与恢复耗时的源头
- 滚动重启前后核对：确认分片是否都回到 STARTED
- 验证副本数变更：改完 number_of_replicas 后看是否多出对应的 r 行
示例
示例
GET /_cat/shards?v&s=state # 按状态排序，异常排前面
GET /_cat/shards/logs-2026.10.01?v&h=index,shard,prirep,state,docs,store,node,unassigned.reason
GET /_cat/shards?v&state=unassigned # 只看未分配分片
GET /_cluster/allocation/explain # 未分配时查根因（也可指定 index/shard）
GET /_cat/allocation?v # 各节点的分片数与磁盘占用对照列读法
| 列 | 含义 | 正常/异常 |
|---|---|---|
| shard | 分片编号，从 0 开始 | 编号范围应与主分片数一致 |
| prirep | p 表示主分片，r 表示副本 | 统计主分片数时只数 p 行 |
| state | STARTED / INITIALIZING / RELOCATING / UNASSIGNED | 长期 UNASSIGNED 或反复 INITIALIZING 即异常 |
| docs | 该分片内的文档数 | 分片间差距悬殊说明分布不均 |
| store | 该分片的磁盘占用 | 单分片过大（常见经验值几十 GB 量级）会拖慢恢复 |
| node | 所在节点名 | 为空表示尚未分配 |
| unassigned.reason | 未分配原因，如 NODE_LEFT、ALLOCATION_FAILED | 定位是节点缺失、分配失败还是磁盘水位触发 |
state 的四种状态含义不同：STARTED 正常服务、INITIALIZING 正在恢复、RELOCATING 正在迁移、UNASSIGNED 尚未分配。看到 INITIALIZING 长时间不动，通常是大分片恢复或磁盘受限。
单节点集群里副本永远是 UNASSIGNED，因为找不到第二个节点放副本，这是预期行为；结合 unassigned.reason 就能和真正的故障区分开。
输出很长时用 h 参数只取需要的列，用 s 参数排序，既能减少人工阅读负担，也能让脚本解析更稳（列顺序固定后无需按位置硬编码）。