【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_shards1.2 分片状态与生命周期分片在集群中可能处于以下状态状态说明STARTED分片已正常启动可以读写INITIALIZING分片正在初始化中RELOCATING分片正在迁移到其他节点UNASSIGNED分片未分配无法提供服务其中UNASSIGNED状态是需要运维人员重点关注的问题状态。二、分片未分配问题分析2.1 UNASSIGNED状态的常见原因当分片处于UNASSIGNED状态时通常由以下原因导致原因描述解决思路ALLOCATION_FAILED分片分配失败检查节点磁盘空间和内存NODE_LEFT持有分片的节点离开集群等待自动恢复或手动rerouteTOO_MANY_SHARDS节点分片数超过限制调整cluster.max_shards_per_nodeINDEX_CREATED索引刚创建副本尚未分配等待节点恢复或增加节点DANGLING_INDEX_IMPORTED导入悬空索引检查索引数据完整性REINITIALIZED主分片被重新初始化检查集群状态一致性2.2 查看未分配分片的详细信息使用_cat/shardsAPI查看分片状态GET _cat/shards/my_index?vhindex,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/reroute3.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: truePOST_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命令对比命令功能适用场景风险等级allocate_replica手动分配副本分片节点恢复后、副本重建低move移动分片到目标节点负载均衡、节点下线中cancel取消分片分配中断异常的分配操作高主分片四、分片分配策略配置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?vactive_onlytrue维护完成后记得移除排除设置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}}参数默认值说明balance.shard0.45节点间分片数量的权重因子balance.index0.55节点间索引分布的权重因子balance.threshold1.0触发重平衡的阈值0-1.04.5 分片分配启用控制在紧急情况下可以暂时禁止分片分配PUT_cluster/settings{persistent:{cluster.routing.allocation.enable:primaries}}cluster.routing.allocation.enable的可选值值说明all默认允许所有类型分片的分配primaries仅允许主分片的分配new_primaries仅允许新建索引的主分片分配none禁止所有分片分配注意在生产环境中禁用分片分配可能影响数据写入和集群恢复仅在紧急维护时短暂使用操作完成后立即恢复为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?vhindex,shard,prirep,state,node,unassigned.reason|grepUNASSIGNEDmy_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支持多种节点属性用于过滤分片分配属性说明示例_name节点名称node-1_host主机名host-data-01_ipIP地址192.168.1.10_tier_preference数据层data_hot_id节点IDNdXzC7q自定义属性用户定义的属性node.attr.zone: zone-a七、总结与最佳实践核心要点回顾Reroute API是分片管理的利器通过allocate_replica、move、cancel三种命令可以精确控制分片分配始终使用dry_run预检在生产环境执行reroute操作前先用dry_run模式验证理解分片未分配原因通过_cluster/allocation/explainAPI定位根因而非盲目操作合理配置分配策略利用分配感知和过滤器实现数据安全分布最佳实践清单定期监控集群健康状态和未分配分片数量在节点维护前使用exclude属性逐步迁移分片而非直接关停为节点配置机架/可用区属性启用分配感知提升容灾能力设置合理的磁盘水位线避免因磁盘满导致分片分配失败执行高风险操作前先备份重要数据禁止分片分配后务必记得恢复设置上一篇【第36篇】Elasticsearch索引生命周期管理实战下一篇【第38】Elasticsearch索引映射深度解析——数据类型与映射属性