手动更改集群中单个分片（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 数组，数组中可以包含多种类型的命令：
{
"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，表示接受数据丢失 |
示例 #
移动分片到另一个节点 #
POST /_cluster/reroute
{
"commands": [
{
"move": {
"index": "my_index",
"shard": 0,
"from_node": "node1",
"to_node": "node2"
}
}
]
}
取消分片分配 #
POST /_cluster/reroute
{
"commands": [
{
"cancel": {
"index": "my_index",
"shard": 0,
"node": "node1"
}
}
]
}
分配未分配的副本 #
POST /_cluster/reroute
{
"commands": [
{
"allocate_replica": {
"index": "my_index",
"shard": 0,
"node": "node1"
}
}
]
}
分配空主分片（会丢失数据） #
POST /_cluster/reroute
{
"commands": [
{
"allocate_empty_primary": {
"index": "my_index",
"shard": 0,
"node": "node1",
"accept_data_loss": true
}
}
]
}
模拟运行（不实际执行） #
POST /_cluster/reroute?dry_run=true
{
"commands": [
{
"move": {
"index": "my_index",
"shard": 0,
"from_node": "node1",
"to_node": "node2"
}
}
]
}
获取详细解释 #
POST /_cluster/reroute?explain=true
{
"commands": [
{
"move": {
"index": "my_index",
"shard": 0,
"from_node": "node1",
"to_node": "node2"
}
}
]
}
重试失败的分片分配 #
POST /_cluster/reroute?retry_failed=true
{
"commands": []
}
响应示例：
{
"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命令会导致数据丢失，请谨慎使用！
