ES 集群 Yellow 复盘：1023 个副本永远分配不出去，问题不在磁盘

一个 7 节点的日志集群，状态 yellow，unassigned_shards 1023，active_shards_percent 只有 76%。磁盘最高 38%，堆内存 60% 出头，熔断器没跳，线程池 rejected 全 0。所有常规的「资源不够」解释全部不成立，但未分配分片每天还在稳定增长。

这类故障的特征是：它不会让你收到 P0 告警，因为集群还能读能写；它只是安静地把你的副本冗余一点点吃光，直到某天一台数据节点掉了，你才发现有几百个分片根本没有第二份。

本文复盘的就是这条路径：从「yellow 但资源全绿」到定位 node_version 决策器，再到根治与预防。

版本说明

本文基于 ES 7.17 / 8.x。node_version 分配决策器的行为、滚动升级的节点顺序、cluster.routing.allocation.enable 的取值均按官方 Rolling upgrades 文档核对（8.x 起 transient 集群设置已废弃，本文一律用 persistent）。文中集群名、节点名、索引名均为通用示例。

一、为什么「yellow 且资源正常」比 red 更值得紧张

red 是主分片缺失，业务立刻报错，没人会拖着不处理。yellow 恰恰相反——查询照常返回，写入照常成功，监控面板一片安静，于是它经常被挂上「回头看」的清单，一挂几个月。

代价是三层叠加的：

• 冗余归零。未分配的都是副本，意味着这些索引只有一份数据。此时任何一次数据节点故障、甚至一次正常的滚动重启，都会把 yellow 直接推成 red。
• 恢复窗口被拉长。副本本来的另一个作用是让分片恢复走本地/对等节点的快速路径；没有副本，恢复只能从头重建。
• 元数据持续膨胀。未分配分片的分配决策会被 master 反复重试并记录，配合本来就积压的索引数，master 处理 cluster state 的负担只增不减。

更关键的是这类故障的增长模式：如果未分配数是一条随时间线性上升的直线，而不是某次事件后的一个台阶，那它几乎一定和「新建索引」绑定——每天新建的索引，副本每天都分配不出去。这个观察本身就是最有价值的一条线索，它把排查范围从「集群资源」直接切换到「分配决策」。

二、取证：三条命令定位到决策器

排障顺序是固定的：先确认规模，再确认分布，最后让 ES 自己说出拒绝理由。不要跳过前两步直接问 explain，否则你拿到的是单个分片的结论，判断不了这是个案还是面。

第一步：确认规模与增长模式

GET _cluster/health

预期输出（关键字段）：

{
  "status": "yellow",
  "number_of_nodes": 7,
  "active_shards_percent_as_number": 76.2,
  "unassigned_shards": 1023,
  "initializing_shards": 0,
  "relocating_shards": 0
}

initializing 与 relocating 都是 0，是一个很强的信号：集群不是「正在恢复中」，而是「已经放弃了」。如果这两个数字非 0，那你要做的只是等待和限速调优，不是排障。

第二步：确认未分配的是主还是副本，落在哪些索引

GET _cat/shards?v&h=index,shard,prirep,state,node&s=state,index | grep UNASSIGNED | head -20

判读要点：

• prirep 列全是 r → 只有副本分配不出去，主分片健康。故障范围被锁定在「副本分配约束」。
• 未分配集中在按天/按月滚动的新索引上，老索引反而齐全 → 印证第一节说的线性增长模式。

如果这里出现 p（主分片未分配），那是另一个故事——通常是数据目录损坏或节点永久离线，处置路径完全不同。

第三步：让 ES 说出拒绝理由

GET _cluster/allocation/explain
{
  "index": "applog-2026.08.20",
  "shard": 0,
  "primary": false
}

allocation/explain 是整套排查里唯一不需要猜的接口。它会对每个节点列出所有决策器的结论。本次故障的关键片段：

{
  "node_allocation_decisions": [
    {
      "node_name": "es-data-01",
      "node_decision": "no",
      "deciders": [
        {
          "decider": "node_version",
          "decision": "NO",
          "explanation": "cannot allocate replica shard to a node with version [7.17.20] since this is older than the primary version [7.17.26]"
        }
      ]
    }
  ]
}

到这里根因已经完全明确：主分片落在 7.17.26 的节点上，而候选节点还是 7.17.20，node_version 决策器直接否决。

第四步：确认版本分裂的范围

GET _cat/nodes?v&h=name,version,node.role,master

预期看到的正是问题本身：

name          version   node.role  master
es-data-01    7.17.20   dim        -
es-data-02    7.17.20   dim        -
es-data-03    7.17.20   dim        *
es-data-04    7.17.20   dim        -
es-data-05    7.17.20   dim        -
es-archive-01 7.17.26   dim        -
es-archive-02 7.17.26   dim        -

一次没做完的升级：两台节点升到了 7.17.26，其余五台停在 7.17.20，然后就这么跑了几个月。

三、机制：为什么 ES 必须这样拒绝

这不是 bug，是数据格式的单向兼容约束。官方文档写得很直白：分配在新版本节点上的主分片，不能把副本分配到旧版本节点上——新版本可能写出旧版本理解不了的数据格式。反过来（主在旧、副本在新）是允许的。

于是在一个版本分裂的集群里，会发生一件很多人没预料到的事：

1. 新索引创建时，主分片可能被分配到任意节点，包括高版本的那两台;
2. 一旦某个主分片落在高版本节点上，它的副本就只能在另一台高版本节点上落地;
3. 高版本节点只有 2 台，扣掉主分片所在的那台，可选目标常常只剩 1 台甚至 0 台（还要过 same_shard「主副本不能同节点」这一关）;
4. 分配失败，副本永久 UNASSIGNED。第二天新建索引，重复一遍。

这就是「每天稳定增长」的机制来源：故障速率不取决于流量，只取决于你每天建多少个索引。

顺带解释一个常见困惑：为什么集群还能维持 yellow 而不是拒绝服务？因为主分片一直是可分配的——node_version 只约束副本。ES 在这里的设计取向是优先保可用性，代价就是把风险静默地记在你账上。

四、根治：把版本补齐，顺序不能反

唯一的根治手段是把落后的节点升级到与最高版本一致。滚动升级的节点顺序是有硬性规定的，反了会引入新问题：

先升级非 master-eligible 节点，再按 frozen → cold → warm → hot 的层级顺序升级数据节点，master-eligible 节点放到最后。这个顺序保证了 master-ineligible 节点运行的版本始终不低于 master-eligible 节点。

单节点的标准动作：

# 1. 停掉副本分配，避免节点重启的几分钟里 ES 徒劳地重建副本
PUT _cluster/settings
{ "persistent": { "cluster.routing.allocation.enable": "primaries" } }

# 2. 尽量刷掉 translog，加快该节点重启后的恢复
POST _flush

# 3. 停节点 → 升级二进制/镜像 → 启动节点（此处按你的部署方式执行）

# 4. 确认新节点已加入且版本正确
GET _cat/nodes?v&h=name,version

# 5. 恢复分配
PUT _cluster/settings
{ "persistent": { "cluster.routing.allocation.enable": null } }

# 6. 等这一台的分片恢复完，再动下一台
GET _cat/health?v

第 1 步用 primaries 而不是 none：none 会把主分片的重新分配也一起停掉，一旦重启期间有节点异常，主分片没法转移，可用性反而更差。

验证根治是否生效，看的不是 green，是增长曲线止住了：

# 版本已统一
GET _cat/nodes?v&h=name,version

# 未分配分片持续下降（而不是「今天比昨天少一点，明天又涨回去」）
GET _cluster/health

# 恢复队列在动
GET _cat/recovery?v&active_only=true

版本补齐后，堆积的 1023 个副本不需要人工干预，会随着分配重试自动落地，只需要控制恢复并发别把集群 IO 打满（相关参数见 ES 集群恢复太慢？三个参数加速节点/分片恢复）。

五、四个坑：每一个都有人踩过

坑 1：用 retry_failed 去「重试」它

症状：看到大量 UNASSIGNED，第一反应是 POST _cluster/reroute?retry_failed=true，执行成功，但未分配数一个没少。

原因：retry_failed 只对因分配失败次数超限（默认 5 次）而被搁置的分片有效。node_version 是决策器的硬否决，不是「失败重试」，重试多少次结论都一样。

解药：分清两类未分配。allocation/explain 里出现 decision: NO 的决策器 → 约束问题，重试无效，必须消除约束；出现 MAX_RETRY / allocation_status: no_attempt → 才轮到 retry_failed。

坑 2：把副本数改成 0，让 yellow「消失」

症状：PUT /applog-*/_settings {"index.number_of_replicas": 0}，集群秒变 green，工单关闭。

原因：这不是修复，是把冗余缺失从监控上抹掉。集群确实 green 了——因为你正式声明了「这些索引不需要副本」。数据依然只有一份，而且现在连告警都没有了。

解药：只在两种情况下临时降副本：一是明确知道这批索引是可重建的临时数据；二是紧急扩容/迁移期间的短窗口，且在工单里写明恢复时间点。默认答案是修根因，不是改期望值。

坑 3：以为「升级过了」就等于「升完了」

症状：运维记录里明明写着某月做过升级，_cat/nodes 却是两个版本。

原因：滚动升级被中断（换人、被更紧急的事打断、某台节点启动失败后临时回滚），而中断后的集群是完全可用的——没有任何报错提示你「升级只做了一半」。这类故障几乎全部来自「升级过程没有收尾检查」。

解药：把版本一致性做成例行检查项，而不是靠记忆。一条命令即可：

# 输出多于一行，就是版本分裂
GET _cat/nodes?h=version | sort -u

放进周巡检脚本，和磁盘水位、堆内存、未分配分片并列。

坑 4：盯着资源指标不放，忽略了元数据侧

症状：排查时顺手统计了一下，集群里躺着一千多个 close 状态的索引，于是怀疑是它们导致了分配失败。

原因：close 索引不占分片资源，不是本次故障的成因——这一点必须靠 allocation/explain 的结论来排除，而不是靠直觉。但它确实是另一个真实问题：close 索引的元数据仍然全量存在于 cluster state 中，数量上千时会实打实增加 master 的处理负担和节点加入时的状态同步开销。

解药：两件事分开处理。故障归故障，以决策器结论为准；元数据膨胀单独排期，用快照归档 + 删除代替长期 close（治理思路可参考 Elasticsearch 分片和副本：容量怎么规划）。排障时最忌讳的就是把「顺手发现的问题」当成「当前故障的原因」。

六、可复用要点

1. yellow + 资源全绿 + 数量线性增长 = 去查分配约束，不要查资源。 增长模式本身是分类依据：台阶状通常是一次性事件（节点掉线、磁盘打满），线性上升几乎一定绑定「每天新建的对象」。
2. _cluster/allocation/explain 是结论，其他都是线索。 排障顺序固定为 health（规模）→ _cat/shards（分布）→ explain（原因）→ _cat/nodes（范围）。跳步的代价是拿一个个案的结论去解释整体。
3. 副本分配的版本约束是单向的：主在新版本 → 副本不能去旧版本；反之允许。所以版本分裂集群的伤害会随「新建索引」积累，不随流量积累。
4. 升级必须有收尾验证。_cat/nodes?h=version | sort -u 只输出一行才算升完，这条应该进巡检脚本，而不是留在人的记忆里。
5. 不要用降低期望值的方式让告警变绿。改副本数为 0、上调磁盘水位线、关闭告警规则，都属于同一类错误：故障没解决，只是不再可见。

---

🤖 Agent 可直接解析的元数据块（点击展开）

{
  "_meta": {
    "doc_version": "2026-08-25",
    "article_id": "es-unassigned-replica-node-version",
    "profile_context": "prod",
    "estimated_setup_time": "15min"
  },
  "quick_start": {
    "step_1": "GET _cluster/health",
    "step_2": "GET _cat/shards?v&h=index,shard,prirep,state,node&s=state,index | grep UNASSIGNED | head -20",
    "step_3": "GET _cluster/allocation/explain {\"index\":\"<index>\",\"shard\":0,\"primary\":false}",
    "step_4": "GET _cat/nodes?v&h=name,version,node.role,master"
  },
  "diagnosis_rules": [
    "unassigned 全为 prirep=r 且 explain 命中 node_version decider → 集群版本分裂，需补齐滚动升级",
    "initializing/relocating 均为 0 → 集群已放弃分配，不是恢复中，无需等待",
    "explain 给出 decision=NO → 约束问题，retry_failed 无效"
  ],
  "safety_rules": [
    "升级顺序：非 master-eligible 节点先升，master-eligible 节点最后升",
    "重启数据节点前设置 cluster.routing.allocation.enable=primaries，不要用 none",
    "禁止用 number_of_replicas=0 让 yellow 变 green 来关闭工单",
    "集群设置一律用 persistent，transient 在 8.x 已废弃"
  ],
  "verification": {
    "check_1": "GET _cat/nodes?h=version | sort -u  # 只应输出一行",
    "check_2": "GET _cluster/health  # unassigned_shards 持续下降",
    "check_3": "GET _cat/recovery?v&active_only=true  # 恢复队列在动且逐步清空"
  }
}

AI Agent 使用指南：

• 当用户说「集群 yellow / 有大量 unassigned 分片」→ 依次执行 quick_start.step_1 到 step_4，再用 diagnosis_rules 判定类别。
• 当用户说「要不要把副本调成 0」→ 引用 safety_rules 第 3 条拒绝，并给出根治路径。
• 当用户说「升级完了吗」→ 执行 verification.check_1，多于一行即为未完成。

延伸阅读：磁盘维度的分配问题见 Elasticsearch 集群节点磁盘使用分配不均解决办法；分片数与容量规划见 Elasticsearch 分片和副本。