---
title: "集群重新路由"
date: 2026-01-05
lastmod: 2026-01-05
description: "手动更改集群中分片的分配，包括移动分片、取消分配、分配副本等操作"
tags: ["集群管理", "分片分配", "运维操作"]
summary: "手动更改集群中单个分片（shard）的分配，允许管理员在特殊情况下手动干预分片分配策略。
API #  POST /_cluster/reroute API 的作用 #  该 API 允许手动更改集群中分片的分配，可以用于：
 移动分片（move）：将分片从一个节点移动到另一个节点 取消分配（cancel）：取消分片的重新定位或恢复 分配副本（allocate_replica）：将未分配的副本分片分配到特定节点 分配过期主分片（allocate_stale_primary）：将可能过期的主分片分配到特定节点（可能丢失数据） 分配空主分片（allocate_empty_primary）：创建一个空的主分片（会丢失数据）  使用场景 #   集群健康状态不佳时手动调整分片分布 节点故障后手动迁移分片 维护操作时调整分片位置 测试和调试分片分配策略  API 的参数 #  Query String 参数 #     参数 类型 是否必填 默认值 描述     dry_run 布尔值 否 false 模拟运行，不实际执行操作，只返回操作后的集群状态   explain 布尔值 否 false 返回命令可以或不能执行的详细解释   retry_failed 布尔值 否 false 重试因连续分配失败而被阻塞的分片分配   timeout 时间值 否 默认超时 操作超时时间   master_timeout 时间值 否 默认超时 连接到主节点的超时时间   metric 列表 否 所有（除 metadata） 限制返回的指定指标信息    请求体参数 #  请求体是一个 JSON 对象，包含 commands 数组，数组中可以包含多种类型的命令："
---


手动更改集群中单个分片（shard）的分配，允许管理员在特殊情况下手动干预分片分配策略。

## API

```
POST /_cluster/reroute
```

## API 的作用

该 API 允许手动更改集群中分片的分配，可以用于：

- **移动分片**（move）：将分片从一个节点移动到另一个节点
- **取消分配**（cancel）：取消分片的重新定位或恢复
- **分配副本**（allocate_replica）：将未分配的副本分片分配到特定节点
- **分配过期主分片**（allocate_stale_primary）：将可能过期的主分片分配到特定节点（可能丢失数据）
- **分配空主分片**（allocate_empty_primary）：创建一个空的主分片（会丢失数据）

### 使用场景

- 集群健康状态不佳时手动调整分片分布
- 节点故障后手动迁移分片
- 维护操作时调整分片位置
- 测试和调试分片分配策略

## API 的参数

### Query String 参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `dry_run` | 布尔值 | 否 | false | 模拟运行，不实际执行操作，只返回操作后的集群状态 |
| `explain` | 布尔值 | 否 | false | 返回命令可以或不能执行的详细解释 |
| `retry_failed` | 布尔值 | 否 | false | 重试因连续分配失败而被阻塞的分片分配 |
| `timeout` | 时间值 | 否 | 默认超时 | 操作超时时间 |
| `master_timeout` | 时间值 | 否 | 默认超时 | 连接到主节点的超时时间 |
| `metric` | 列表 | 否 | 所有（除 metadata） | 限制返回的指定指标信息 |

### 请求体参数

请求体是一个 JSON 对象，包含 `commands` 数组，数组中可以包含多种类型的命令：

```json
{
  "commands": [
    { "move": { ... } },
    { "cancel": { ... } },
    { "allocate_replica": { ... } },
    { "allocate_stale_primary": { ... } },
    { "allocate_empty_primary": { ... } }
  ]
}
```

#### 1. move 命令 - 移动分片

| 参数 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `index` | 字符串 | 必需 | 索引名称 |
| `shard` | 整数 | 必需 | 分片 ID |
| `from_node` | 字符串 | 必需 | 源节点 ID |
| `to_node` | 字符串 | 必需 | 目标节点 ID |

**注意**：分片必须处于 STARTED 状态才能被移动

#### 2. cancel 命令 - 取消分配

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `index` | 字符串 | 必需 | - | 索引名称 |
| `shard` | 整数 | 必需 | - | 分片 ID |
| `node` | 字符串 | 必需 | - | 节点 ID |
| `allow_primary` | 布尔值 | 否 | false | 是否允许取消主分片 |

#### 3. allocate_replica 命令 - 分配副本

| 参数 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `index` | 字符串 | 必需 | 索引名称 |
| `shard` | 整数 | 必需 | 分片 ID |
| `node` | 字符串 | 必需 | 目标节点 ID |

#### 4. allocate_stale_primary 命令 - 分配过期主分片

| 参数 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `index` | 字符串 | 必需 | 索引名称 |
| `shard` | 整数 | 必需 | 分片 ID |
| `node` | 字符串 | 必需 | 目标节点 ID |
| `accept_data_loss` | 布尔值 | 必需 | 必须为 true，表示接受数据丢失 |

#### 5. allocate_empty_primary 命令 - 分配空主分片

| 参数 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `index` | 字符串 | 必需 | 索引名称 |
| `shard` | 整数 | 必需 | 分片 ID |
| `node` | 字符串 | 必需 | 目标节点 ID |
| `accept_data_loss` | 布尔值 | 必需 | 必须为 true，表示接受数据丢失 |

## 示例

### 移动分片到另一个节点

```bash
POST /_cluster/reroute
{
  "commands": [
    {
      "move": {
        "index": "my_index",
        "shard": 0,
        "from_node": "node1",
        "to_node": "node2"
      }
    }
  ]
}
```

### 取消分片分配

```bash
POST /_cluster/reroute
{
  "commands": [
    {
      "cancel": {
        "index": "my_index",
        "shard": 0,
        "node": "node1"
      }
    }
  ]
}
```

### 分配未分配的副本

```bash
POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_replica": {
        "index": "my_index",
        "shard": 0,
        "node": "node1"
      }
    }
  ]
}
```

### 分配空主分片（会丢失数据）

```bash
POST /_cluster/reroute
{
  "commands": [
    {
      "allocate_empty_primary": {
        "index": "my_index",
        "shard": 0,
        "node": "node1",
        "accept_data_loss": true
      }
    }
  ]
}
```

### 模拟运行（不实际执行）

```bash
POST /_cluster/reroute?dry_run=true
{
  "commands": [
    {
      "move": {
        "index": "my_index",
        "shard": 0,
        "from_node": "node1",
        "to_node": "node2"
      }
    }
  ]
}
```

### 获取详细解释

```bash
POST /_cluster/reroute?explain=true
{
  "commands": [
    {
      "move": {
        "index": "my_index",
        "shard": 0,
        "from_node": "node1",
        "to_node": "node2"
      }
    }
  ]
}
```

### 重试失败的分片分配

```bash
POST /_cluster/reroute?retry_failed=true
{
  "commands": []
}
```

**响应示例：**

```json
{
  "explanations": [
    {
      "command": {
        "move": {
          "index": "my_index",
          "shard": 0,
          "from_node": "node1",
          "to_node": "node2"
        }
      },
      "parameters": {
        "index": "my_index",
        "shard": 0,
        "from_node": "node1",
        "to_node": "node2",
        "allow_primary": false
      },
      "decisions": [
        {
          "decider": "move_allocation_command",
          "decision": "YES",
          "explanation": "move allocation command"
        }
      ]
    }
  ],
  "state": {
    "cluster_name": "easysearch-cluster",
    "cluster_uuid": "xxx"
  }
}
```

> **警告**：使用 `allocate_stale_primary` 和 `allocate_empty_primary` 命令会导致数据丢失，请谨慎使用！