集群重路由

/_cluster/reroute API 允许您手动控制集群内单个分片的分配。这包括移动、分配或取消分片分配。它通常用于高级场景，例如手动恢复或自定义负载均衡。

分片移动受集群分配决策器约束。在生产环境中应用重路由命令之前，请务必使用 dry_run=true 进行测试。使用 explain=true 参数可获取分配决策的详细信息，这有助于理解为什么某个重路由请求可能被允许或不被允许。如果分片分配因先前问题或集群不稳定而失败，您可以使用 retry_failed=true 参数重新尝试分配。

有关分片分布和集群健康的更多信息，请参阅集群健康和集群分配说明。

端点

POST /_cluster/reroute

查询参数

度量选项

metric 参数过滤由重路由 API 返回的集群状态值。这对于减小响应大小或检查集群状态的特定部分很有用。此参数支持以下值：

• _all （默认）：返回所有可用的集群状态部分。
• blocks：包含集群中读写级别阻塞的信息。
• cluster_manager_node：显示哪个节点当前充当集群管理器。
• metadata：返回索引设置、映射和别名。如果指定了特定索引，则仅返回其元数据。
• nodes：包含集群中的所有节点及其元数据。
• routing_table：返回所有分片和副本的路由信息。
• version：显示集群状态版本号。

您可以以逗号分隔列表的形式组合值，例如 metric=metadata,nodes,routing_table。

请求正文字段

请求体中的 commands 数组定义了要应用于分片分配的操作。它支持以下操作。

移动

move 命令将已启动的分片（主分片或副本分片）从一个节点移动到另一个节点。这可用于在维护前平衡负载或耗尽节点。分片必须处于 STARTED 状态。主分片和副本分片都可以使用此命令移动。

move 命令需要以下参数：

• index：索引的名称。
• shard：分片编号。
• from_node：要从中移动分片的节点的名称。
• to_node：要将分片移动到的节点的名称。

取消

cancel 命令取消分片的分配（包括恢复）。此命令通过取消现有分配并让系统重新初始化来强制重新同步。副本分片分配默认可以取消，但取消主分片需要将 allow_primary=true 设置为 true，以防止意外数据中断。

cancel 命令需要以下参数：

• index：索引的名称。
• shard：分片编号。
• node：要执行操作的节点的名称或节点 ID。
• allow_primary （可选）：如果为 true，则允许取消主分片分配。默认值为 false。

分配副本

allocate_replica 命令将未分配的副本分配给指定的节点。此操作遵循分配决策器。当自动分配失败时，使用此命令手动触发副本的分配。

allocate_replica 命令需要以下参数：

• index：索引的名称。
• shard：分片编号。
• node：要执行操作的节点的名称或节点 ID。

分配过时主分片

allocate_stale_primary 命令强制将主分片分配给持有过时副本的节点。

此命令应极其谨慎使用。它绕过安全检查，可能导致数据丢失，尤其是在另一个暂时离线的节点上存在更新的分片副本时。如果该节点稍后重新加入集群，其数据将被删除或被强制提升的过时副本替换。

仅当没有最新副本可用且无法恢复原始数据时才使用此命令。

allocate_stale_primary 命令需要以下参数：

• index：索引的名称。
• shard：分片编号。
• node：要执行操作的节点的名称或节点 ID。
• accept_data_loss：必须设置为 true。

分配空主分片

allocate_empty_primary 命令强制将一个新的空主分片分配给一个节点。此操作初始化一个新的主分片，不包含任何现有数据。

分片的任何先前数据将永久丢失。如果带有该分片有效数据的节点稍后重新加入集群，其副本将被擦除。此命令旨在用于灾难恢复，当不存在有效的分片副本且无法从备份或快照恢复时。

allocate_empty_primary 命令需要以下参数：

• index：索引的名称。
• shard：分片编号。
• node ：要执行操作的节点的名称或节点 ID。
• accept_data_loss：必须设置为 true。

示例

以下是使用集群重路由 API 的示例。

移动分片

创建示例索引

PUT /test-cluster-index
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1
  }
}

运行以下 reroute 命令，将索引 test-cluster-index 的分片 0 从节点 node1 移动到节点 node2

POST /_cluster/reroute
{
  "commands": [
    {
      "move": {
        "index": "test-cluster-index",
        "shard": 0,
        "from_node": "node1",
        "to_node": "node2"
      }
    }
  ]
}

模拟 reroute

要在不执行 reroute 的情况下模拟它，请设置 dry_run=true

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

重试失败的分配

如果某些分片因先前的问题未能分配，您可以重新尝试分配

POST /_cluster/reroute?retry_failed=true

解释 reroute 决策

要了解 reroute 命令被接受或拒绝的原因，请添加 explain=true

POST /_cluster/reroute?explain=true
{
  "commands": [
    {
      "move": {
        "index": "test-cluster-index",
        "shard": 0,
        "from_node": "node1",
        "to_node": "node3"
      }
    }
  ]
}

这会返回一个解释结果的 decisions 数组

"decisions": [
        {
          "decider": "max_retry",
          "decision": "YES",
          "explanation": "shard has no previous failures"
        },
        {
          "decider": "replica_after_primary_active",
          "decision": "YES",
          "explanation": "shard is primary and can be allocated"
        },
        ...
        {
          "decider": "remote_store_migration",
          "decision": "YES",
          "explanation": "[none migration_direction]: primary shard copy can be relocated to a non-remote node for strict compatibility mode"
        }
      ]

响应正文字段

响应包括集群状态元数据，如果使用了 explain=true，则还可选地包括一个 decisions 数组。