【Elasticsearch从入门到精通】第37篇：Elasticsearch集群路由与分片管理——Reroute API详解

上一篇【第36篇】Elasticsearch索引生命周期管理实战
下一篇【第38】Elasticsearch索引映射深度解析——数据类型与映射属性

摘要

在Elasticsearch集群的日常运维中，分片分配问题是最常见的挑战之一。当节点宕机、磁盘满载或索引操作异常时，分片可能进入UNASSIGNED状态，导致集群健康度下降。本文将系统讲解Elasticsearch集群路由与分片管理机制，重点介绍Reroute API的使用方法，包括手动分配副本（allocate_replica）、取消分片分配（cancel）和移动分片（move）三种命令。同时，我们还将探讨分片分配策略配置、节点排除方法，以及如何通过dry_run模式安全地模拟分片分配操作。通过本文的学习，你将具备独立处理集群分片异常问题的能力。

一、理解分片与路由机制

1.1 分片分配基础

Elasticsearch将每个索引划分为多个分片（Shard），分片是数据的物理存储单元。分片分为两种类型：

• 主分片（Primary Shard）：数据的原始副本，支持读写操作
• 副本分片（Replica Shard）：主分片的复制品，提供高可用性和读负载均衡

当一个文档被索引时，Elasticsearch通过路由算法（默认基于文档_id的hash值）决定该文档存储在哪个分片上：

shard_num = hash(_routing) % num_primary_shards

1.2 分片状态与生命周期

分片在集群中可能处于以下状态：

其中，UNASSIGNED状态是需要运维人员重点关注的问题状态。

二、分片未分配问题分析

2.1 UNASSIGNED状态的常见原因

当分片处于UNASSIGNED状态时，通常由以下原因导致：

2.2 查看未分配分片的详细信息

使用_cat/shardsAPI查看分片状态：

GET _cat/shards/my_index?v&h=index,shard,prirep,state,unassigned.reason

响应示例：

index shard prirep state unassigned.reason my_index 0 p STARTED my_index 0 r UNASSIGNED NODE_LEFT my_index 1 p STARTED my_index 1 r UNASSIGNED NODE_LEFT

更详细的信息可以通过集群分配解释API获取：

GET_cluster/allocation/explain{"index":"my_index","shard":0,"primary":false,"current_node":"node-2"}

响应示例：

{"explanation":"the shard cannot be assigned because the node is not a data node","decisions":{"node_decisions":[{"node_id":"node-1","node_name":"node-1","decisions":[{"decider":"disk_threshold","decision":"NO","explanation":"the node is above the high watermark cluster setting"}]}]}}

三、Reroute API详解

3.1 API概述

_cluster/rerouteAPI允许手动控制分片在集群节点间的分配。它在以下场景中特别有用：

• 节点宕机后，手动将未分配的副本分片分配到可用节点
• 将特定分片从一个节点迁移到另一个节点
• 取消正在进行的分片分配操作

基本语法：

POST _cluster/reroute

3.2 allocate_replica：手动分配副本分片

当副本分片因节点离开而变为UNASSIGNED状态时，可以使用allocate_replica命令将其手动分配到其他节点。

POST_cluster/reroute{"commands":[{"allocate_replica":{"index":"my_index","shard":0,"node":"node-1"}}]}

响应示例：

{"acknowledged":true,"state":{"cluster_name":"my-cluster","version":42,"state_uuid":"abc123","master_node":"node-0","blocks":{},"nodes":{"node-0":{"name":"node-0"},"node-1":{"name":"node-1"}}}}

注意：allocate_replica只能用于副本分片。如果主分片未分配，需要使用allocate_stale_primary（有数据丢失风险）或通过_cluster/reroute的allocate_empty_primary命令。

3.3 move：移动分片到指定节点

move命令将分片从一个节点移动到另一个节点，常用于负载均衡或节点下线前的数据迁移。

POST_cluster/reroute{"commands":[{"move":{"index":"my_index","shard":0,"from_node":"node-1","to_node":"node-2"}}]}

响应示例：

{"acknowledged":true,"explanations":[{"command":"move","explanation":"move shard [my_index][0] from [node-1] to [node-2]"}]}

移动分片时需要注意：

• 移动过程会消耗网络带宽和I/O资源，建议在业务低峰期执行
• 可以在单次请求中移动多个分片

POST_cluster/reroute{"commands":[{"move":{"index":"logs-2026","shard":0,"from_node":"node-1","to_node":"node-2"}},{"move":{"index":"logs-2026","shard":1,"from_node":"node-1","to_node":"node-3"}}]}

3.4 cancel：取消分片分配

cancel命令用于取消正在进行的分片分配操作，适用于需要中断分片迁移的场景。

取消副本分片的分配：

POST_cluster/reroute{"commands":[{"cancel":{"index":"my_index","shard":0,"node":"node-2","allow_primary":false}}]}

取消主分片的分配（需要设置allow_primary: true）：

POST_cluster/reroute{"commands":[{"cancel":{"index":"my_index","shard":0,"node":"node-1","allow_primary":true}}]}

警告：取消主分片分配可能导致数据丢失，仅在确认安全的情况下使用。

3.5 dry_run：模拟试运行

在实际执行分片分配操作前，强烈建议使用dry_run模式进行模拟，确认操作不会产生预期外的影响。

POST_cluster/reroute?dry_run{"commands":[{"move":{"index":"my_index","shard":0,"from_node":"node-1","to_node":"node-2"}}]}

响应示例：

{"acknowledged":true,"explanations":[{"command":"move","explanation":"move shard [my_index][0] from [node-1] to [node-2]"}],"state":{}}

dry_run模式返回的结果与正式执行相同，但不会实际修改集群状态，是一种安全的预检手段。

3.6 三种Reroute命令对比

四、分片分配策略配置

4.1 分片分配过滤器

Elasticsearch提供了基于节点属性的分配过滤器，允许管理员精确控制分片的分配位置。

集群级别分配设置：

PUT_cluster/settings{"persistent":{"cluster.routing.allocation.include._ip":"192.168.1.10,192.168.1.11","cluster.routing.allocation.exclude._name":"node-old-1,node-old-2","cluster.routing.allocation.include._host":"data-node-*"}}

索引级别分配设置：

PUTmy_index/_settings{"index.routing.allocation.include._tier_preference":"data_hot","index.routing.allocation.exclude._name":"node-3"}

4.2 排除节点下线

当需要下线某个节点进行维护时，可以通过排除设置将其上的分片迁移出去：

PUT_cluster/settings{"transient":{"cluster.routing.allocation.exclude._ip":"192.168.1.100"}}

也可以按节点名排除：

PUT_cluster/settings{"transient":{"cluster.routing.allocation.exclude._name":"node-maintenance-1"}}

执行排除命令后，Elasticsearch会自动将目标节点上的分片迁移到其他可用节点。可以通过以下命令监控迁移进度：

GET _cat/recovery?v&active_only=true

维护完成后，记得移除排除设置：

PUT_cluster/settings{"transient":{"cluster.routing.allocation.exclude._ip":null,"cluster.routing.allocation.exclude._name":null}}

4.3 分片分配感知属性

通过节点属性实现分片分配感知，确保数据分布在不同的机架或可用区：

# 在各节点的elasticsearch.yml中配置node.attr.rack_id: rack1

然后在集群设置中启用分配感知：

PUT_cluster/settings{"persistent":{"cluster.routing.allocation.awareness.attributes":"rack_id"}}

这样Elasticsearch会尽量将主分片和副本分片分配在不同机架的节点上，提升容灾能力。

4.4 分片平衡配置

PUT_cluster/settings{"persistent":{"cluster.routing.allocation.balance.shard":0.45,"cluster.routing.allocation.balance.index":0.55,"cluster.routing.allocation.balance.threshold":1.0}}

4.5 分片分配启用控制

在紧急情况下，可以暂时禁止分片分配：

PUT_cluster/settings{"persistent":{"cluster.routing.allocation.enable":"primaries"}}

cluster.routing.allocation.enable的可选值：

注意：在生产环境中禁用分片分配可能影响数据写入和集群恢复，仅在紧急维护时短暂使用，操作完成后立即恢复为all。

五、实战：处理yellow状态分片未分配

5.1 诊断步骤

当一个或多个索引的副本分片未分配时，集群状态会变为yellow。以下是完整的排查流程：

步骤1：检查集群健康状态

GET _cluster/health?pretty

{"cluster_name":"production","status":"yellow","timed_out":false,"number_of_nodes":2,"number_of_data_nodes":2,"active_primary_shards":50,"active_shards":98,"relocating_shards":0,"initializing_shards":0,"unassigned_shards":2,"delayed_unassigned_shards":0,"number_of_pending_tasks":0}

步骤2：定位未分配的分片

GET _cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason|grepUNASSIGNED

my_index 0 r UNASSIGNED NODE_LEFT my_index 1 r UNASSIGNED NODE_LEFT

步骤3：获取详细原因

GET_cluster/allocation/explain{"index":"my_index","shard":0,"primary":false}

5.2 修复方案

根据不同的原因采取不同的修复方案：

场景1：节点磁盘空间不足

# 检查各节点磁盘使用率GET _cat/allocation?v

# 调整磁盘水位线PUT_cluster/settings{"transient":{"cluster.routing.allocation.disk.watermark.low":"85%","cluster.routing.allocation.disk.watermark.high":"90%","cluster.routing.allocation.disk.watermark.flood_stage":"95%"}}

场景2：节点已恢复，自动恢复未触发

POST_cluster/reroute{"commands":[{"allocate_replica":{"index":"my_index","shard":0,"node":"node-recovered"}}]}

场景3：主分片数据丢失（高风险操作）

当主分片数据确实丢失且无法恢复时，可以分配一个空的主分片（数据不可恢复）：

POST_cluster/reroute{"commands":[{"allocate_stale_primary":{"index":"my_index","shard":0,"node":"node-1","accept_data_loss":true}}]}

严重警告：allocate_stale_primary和allocate_empty_primary都会导致数据丢失，仅在确认数据无法通过其他方式恢复时才使用。

5.3 批量修复未分配分片

当有大量分片未分配时，可以编写脚本批量执行reroute操作：

POST_cluster/reroute{"commands":[{"allocate_replica":{"index":"logs-2026-01","shard":0,"node":"node-1"}},{"allocate_replica":{"index":"logs-2026-01","shard":1,"node":"node-2"}},{"allocate_replica":{"index":"logs-2026-02","shard":0,"node":"node-1"}}]}

六、分片分配过滤属性详解

Elasticsearch支持多种节点属性用于过滤分片分配：

七、总结与最佳实践

核心要点回顾

1. Reroute API是分片管理的利器：通过allocate_replica、move、cancel三种命令，可以精确控制分片分配
2. 始终使用dry_run预检：在生产环境执行reroute操作前，先用dry_run模式验证
3. 理解分片未分配原因：通过_cluster/allocation/explainAPI定位根因，而非盲目操作
4. 合理配置分配策略：利用分配感知和过滤器实现数据安全分布

最佳实践清单

• 定期监控集群健康状态和未分配分片数量
• 在节点维护前，使用exclude属性逐步迁移分片，而非直接关停
• 为节点配置机架/可用区属性，启用分配感知提升容灾能力
• 设置合理的磁盘水位线，避免因磁盘满导致分片分配失败
• 执行高风险操作前，先备份重要数据
• 禁止分片分配后，务必记得恢复设置

上一篇【第36篇】Elasticsearch索引生命周期管理实战
下一篇【第38】Elasticsearch索引映射深度解析——数据类型与映射属性