Elasticsearch 集群非 green…

当 Elasticsearch 集群出现 yellow/red、未分配分片或分配失败时，用只读方式快速定位最可能原因并给出修复路径。

适用场景

解决思路

1. 读取整体状态：调用 `GET /_cluster/health`，根据 `status` 字段判断——`green` 表示所有主分片和副本都已分配，报告健康并停止；`yellow` 表示所有主分片已分配但至少一个副本未分配，数据仍可读、冗余降级，不是数据丢失；`red` 表示至少一个主分片未分配，该分片数据不可用，视为紧急。同时读取 `unassigned_shards`、`initializing_shards`、`relocating_shards`。仅当状态为 yellow 或 red 时继续。若 `initializing_shards > 0` 且 `unassigned_shards == 0`，说明集群正在自行恢复——调用 `GET /_cat/recovery` 确认进度，等待后重新检查 `GET /_cluster/health` 再决定是否升级。
2. 将问题定位到单个索引：调用 `GET /_cluster/health?level=indices`，选出驱动集群整体状态的那个索引——任何 red 索引优先于所有 yellow 索引；同为 red 或 yellow 时优先 `unassigned_shards` 最多的索引；red 的系统索引（`.security`、`.kibana*`、`.fleet-*`）优先于应用索引，因为整个技术栈依赖它们。可选调用 `GET /_cat/shards/{index}?h=index,shard,prirep,state,unassigned.reason` 列出该索引所有未分配分片，查看失败的是主分片（`prirep=p`）还是副本（`prirep=r`）。后续步骤只聚焦这一个索引。
3. 区分触发事件与根因：调用 `POST /_cluster/allocation/explain`（不带 body 让 Elasticsearch 自选一个未分配分片），或显式指定最严重的分片：`{ "index": "<index>", "shard": <id>, "primary": <true|false> }`。按顺序读取字段：`primary`——`false` 表示副本未分配（典型 yellow），`true` 表示主分片未分配（典型 red）；`can_allocate`——顶层分配结论（`no`、`yes`、`throttled`、`no_valid_shard_copy` 等）；`unassigned_info.reason`——触发重新分配的事件（如 `NODE_LEFT`、`INDEX_CREATED`），当 `can_allocate` 为 `no` 时它不是根因，只解释分片为何变为未分配；`allocate_explanation`——人类可读摘要，报告中逐字引用；`node_allocation_decisions[].deciders[]`——逐节点决策器结果，找出 `decision: "NO"` 的决策器，其名称（如 `disk_threshold`、`filter`、`awareness`）即根因类别。判断：yellow + `primary: false` 影响仅限副本冗余、无数据丢失，继续第 4 步找出阻塞决策器（不要停在 `NODE_LEFT`）；red + `primary: true` 该分片数据缺失，继续第 4 步，若 `can_allocate` 为 `no_valid_shard_copy` 立即视为可能的数据丢失。
4. 分类决策器：将阻塞信号映射到原因类别，优先采用 `decision: "NO"` 的决策器而非 `unassigned_info.reason` 触发事件。映射表：`decider: disk_threshold` 且 `decision: NO` → 磁盘高/低水位超限，修复方式为释放指定节点磁盘、增加数据节点容量，或在通过 `GET /_cat/allocation` 确认使用率后调整 `cluster.routing.allocation.disk.watermark.*`；`decider: filter` 或 `decider: awareness` 且 `decision: NO` → 分配过滤或区域感知，修复方式为添加满足 `index.routing.allocation.*` / awareness 属性的节点，或调整索引/集群分配设置；`decider: throttling` 或恢复进行中 → 瞬时恢复，等待并监控 `GET /_cat/recovery`、重新检查 `GET /_cluster/health`；`can_allocate: no_valid_shard_copy`（通常 `node_allocation_decisions` 为空）→ 无存活分片副本，见第 5 步的数据丢失场景；`can_allocate: yes` 但分片仍未分配 → 延迟分配或集群状态追赶，检查 `unassigned_info.at` 延迟，等待后重新检查。对于磁盘压力（`NODE_LEFT` 后常见的 yellow 场景）：副本迁移到剩余节点，若某个存活节点超过高水位（`cluster.routing.allocation.disk.watermark.high`，默认 90%），`disk_threshold` 决策器会阻止副本分配，即使主分片仍已分配。修复方式是磁盘容量或水位缓解，而不是删除索引或强制空主分片。
5. 给出修复建议——只读分诊到此结束：报告最可能的单一原因（决策器类别 + 逐字 `allocate_explanation`）和一条主要修复路径，紧急程度与颜色和分片角色匹配。Yellow / 副本未分配（无数据丢失）：明确说明所有主分片已分配、仅副本缺失、无数据丢失；指出真正的决策器（如 `es-node-2` 上的磁盘高水位），而不只是“某节点离开了”；建议释放磁盘空间、扩容存储、增加数据节点，或在查看 `GET /_cat/allocation` 后调整磁盘水位；不要建议删除索引、`allocate_empty_primary`、在健康主分片上强制分配，或在无证据时重启整个集群。Red / 主分片未分配且 `no_valid_shard_copy`（数据丢失风险）：明确说明主分片未分配、该分片的查询/路由失败、视为紧急且局限于指定索引；解释唯一副本在已离开的节点上，Elasticsearch 无法分配主分片，因为剩余节点上没有有效副本（`can_allocate: no_valid_shard_copy`）；恢复路径按顺序：1) 若已离开节点的数据目录完好，将其恢复——分片副本回归；2) 若存在快照，从快照恢复到该索引（或新索引后 reindex）；3) 仅作为最后手段：`POST /_cluster/reroute` 配合 `allocate_empty_primary`——这会创建空主分片并永久丢失该分片上的所有文档，必须明确说明数据丢失，绝不能作为首选或随意修复。不要建议：不讨论数据丢失就删除索引，或不带数据丢失警告就使用 `allocate_empty_primary`。自行恢复进行中：当决策器显示限流或对等恢复活跃时，建议等待并重新检查上述只读 API。不要执行 reroute、快照恢复或设置变更——只呈现原因和修复建议。
6. 遵循准则：只读——分诊只用 GET/POST explain API，修复是建议，由运维人员执行写操作；触发 ≠ 根因——`unassigned_info.reason: NODE_LEFT` 解释事件，`node_allocation_decisions` 决策器解释为何分配仍失败；副本 vs 主分片——yellow + `primary: false` 是冗余缺口而非数据丢失，red + `primary: true` 是该分片数据缺失；一个索引、一个原因——选择影响最大的索引和最强的 NO 决策器，避免罗列每个分片；cat 辅助——当决策器类别不明确或恢复进行中时，用 `GET /_cat/allocation` 查看每节点磁盘百分比，用 `GET /_cat/recovery` 查看进行中的恢复。
7. 参考示例：Yellow——节点离开后的磁盘水位。健康显示 yellow，`logs-2025-07` 上有未分配副本。Allocation explain 返回 `primary: false`、`unassigned_info.reason: NODE_LEFT`，但 `es-node-2` 上 `disk_threshold` 决策器为 NO（“above the high watermark … 90%”）。报告：无数据丢失；根因是接收节点的磁盘压力；修复磁盘/水位——而不只是“节点离开”。Red——主分片无有效副本。健康显示 `orders-2025` 为 red，一个未分配分片。Explain 返回 `primary: true`、`can_allocate: no_valid_shard_copy`、`last_allocation_status: no_valid_shard_copy`。报告：紧急；主分片数据缺失；恢复节点或快照；仅在最后手段提及 `allocate_empty_primary` 并明确数据丢失。
8. 使用 `elastic` CLI 执行操作（HTTP 简写与 CLI 命令映射）：`GET /_cluster/health` → `elastic es cluster health`；`GET /_cluster/health?level=indices` → `elastic es cluster health --level indices`；`POST /_cluster/allocation/explain` → `elastic es cluster allocation-explain`；`POST /_cluster/allocation/explain`（指定分片）→ `elastic es cluster allocation-explain --index '<index>' --shard <id> --primary true`（副本用 `false`）；`GET /_cat/allocation` → `elastic es cat allocation`；`GET /_cat/recovery` → `elastic es cat recovery`；`GET /_cat/shards/{index}?h=index,shard,prirep,state,unassigned.reason` → `elastic es cat shards --index '<index>' --h index,shard,prirep,state,unassigned.reason`；`POST /_cluster/reroute`（最后手段空主分片——仅运维人员）→ `elastic es cluster reroute --commands '<json>'`。若未安装 `elastic` CLI，告知用户其用途；不要猜测凭据、直接调用 HTTP API 或尝试其他变通方法。

适用边界 · 注意事项

• 不适用于 Elastic Cloud Serverless，其集群、分片和分配 API 由内部管理。
• 需要 `elastic` CLI ≥ 0.2 且支持 `stack es`；未安装时不要猜测凭据或直接调用 HTTP API。
• 本技能仅做只读分诊，不执行 reroute、快照恢复或设置变更。