---
title: "分片分配解释"
date: 2026-01-24
lastmod: 2026-01-24
description: "解释集群中分片的分配决策，帮助理解为什么分片被分配到特定节点或未分配"
tags: ["集群管理", "分片分配", "故障排查"]
summary: "解释集群中分片的分配决策，帮助用户理解为什么某个分片会被分配到特定的节点，或者为什么某个分片没有被分配。
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 会自动选择第一个未分配的分片进行解释。"
---


解释集群中分片的分配决策，帮助用户理解为什么某个分片会被分配到特定的节点，或者为什么某个分片没有被分配。

## 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 方法）

```bash
GET /_cluster/allocation/explain
```

### 包含 YES 决策和磁盘信息

```bash
GET /_cluster/allocation/explain?include_yes_decisions=true&include_disk_info=true
```

### 查询特定分片（POST 方法）

```bash
POST /_cluster/allocation/explain
{
  "index": "my_index",
  "shard": 0,
  "primary": true
}
```

### 查询特定节点的副本分片

```bash
POST /_cluster/allocation/explain
{
  "index": "my_index",
  "shard": 1,
  "primary": false,
  "current_node": "node-1"
}
```

**响应示例：**

```json
{
  "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"
        }
      ]
    }
  ]
}
```

### 分片未分配的响应示例

```json
{
  "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` | 节点分片数量限制 |