解释集群中分片的分配决策，帮助用户理解为什么某个分片会被分配到特定的节点，或者为什么某个分片没有被分配。
API #
GET /_cluster/allocation/explain
POST /_cluster/allocation/explain
API 的作用 #
该 API 用于解释集群中分片（shard）的分配决策，帮助用户：
- 理解为什么某个分片被分配到特定节点
- 查看为什么某个分片没有被分配
- 了解影响分片分配的各种因素和决策
- 排查集群中的分片分配问题
当没有指定具体分片时，API 会自动选择第一个未分配的分片进行解释。
API 的参数 #
Query String 参数 #
| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
include_yes_decisions | 布尔值 | 否 | false | 是否在解释中包含 “YES” 决策，默认只返回 “NO” 和 “throttle” 决策 |
include_disk_info | 布尔值 | 否 | false | 是否返回节点的磁盘使用情况和分片大小信息 |
请求体参数（POST 请求时使用） #
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
index | 字符串 | 否 | 要解释的分片所在的索引名称 |
shard | 整数 | 否 | 要解释的分片 ID |
primary | 布尔值 | 否 | 是否解释主分片（true）或副本分片（false） |
current_node | 字符串 | 否 | 当前持有该副本分片的节点 ID |
注意：所有参数都是可选的。如果不指定，API 会自动选择第一个未分配的分片进行解释。
示例 #
简单查询（GET 方法） #
GET /_cluster/allocation/explain
包含 YES 决策和磁盘信息 #
GET /_cluster/allocation/explain?include_yes_decisions=true&include_disk_info=true
查询特定分片（POST 方法） #
POST /_cluster/allocation/explain
{
"index": "my_index",
"shard": 0,
"primary": true
}
查询特定节点的副本分片 #
POST /_cluster/allocation/explain
{
"index": "my_index",
"shard": 1,
"primary": false,
"current_node": "node-1"
}
响应示例：
{
"index": "my_index",
"shard": 0,
"primary": true,
"current_state": "unassigned",
"unassigned_info": {
"reason": "INDEX_CREATED",
"at": "2026-02-04T08:00:00Z"
},
"can_allocate": "yes",
"allocate_explanation": "can allocate the shard",
"node_allocation_decisions": [
{
"node_id": "node1",
"node_name": "node-1",
"transport_address": "192.168.1.1:9300",
"node_attributes": {},
"node_decision": "yes",
"decisions": [
{
"decider": "filter",
"decision": "YES",
"explanation": "node passes include/exclude/require filters"
},
{
"decider": "same_shard",
"decision": "YES",
"explanation": "the shard does not exist on the node"
}
]
}
]
}
分片未分配的响应示例 #
{
"index": "my_index",
"shard": 0,
"primary": true,
"current_state": "unassigned",
"can_allocate": "no",
"allocate_explanation": "cannot allocate because allocation is not permitted",
"unassigned_info": {
"reason": "NODE_LEFT",
"at": "2026-02-04T08:00:00Z",
"details": "node_left [node1]"
},
"node_allocation_decisions": [
{
"node_id": "node2",
"node_name": "node-2",
"node_decision": "no",
"decisions": [
{
"decider": "disk_threshold",
"decision": "NO",
"explanation": "the node is above the high watermark cluster setting [cluster.routing.allocation.disk.watermark=95%], having less than the minimum required [5%] free disk, actual free: [3%]"
}
]
}
]
}
决策类型说明 #
| 决策 | 描述 |
|---|---|
YES | 允许分配 |
NO | 不允许分配 |
THROTTLE | 限制分配（如恢复节点的分片重新分配） |
常见决策器（Decider） #
| 决策器 | 描述 |
|---|---|
filter | 节点过滤（include/exclude/require） |
same_shard | 同一分片检查 |
disk_threshold | 磁盘阈值检查 |
awareness | 分片感知分配 |
shards_limit | 节点分片数量限制 |
