Elasticsearch 日常运维与故障场景 (8.x / 9.x)

不是安装指南：面向已安装的 Elasticsearch 8.x / 9.x 集群的场景化 runbook，用于日常管理以及出现故障时的恢复。内容包括：健康检查与 allocation explain，处理未分配分片（磁盘、filtering、retry_failed、副本，最后手段 stale/empty primary），磁盘 watermark，read_only_allow_delete 块，添加节点与安全下线节点，借助别名的零停机 reindex，ILM 与 rollover，_shrink / _split，从快照以新名称恢复单个索引。不确定该做什么时，先做健康检查。快照存储库配置与 SLM、安全加固和版本升级见其他 Elasticsearch 指南。

架构: Elasticsearch 8.x / 9.x 集群（1–N 个节点），已启用 TLS 和身份验证

场景

• 集群健康：状态、节点、未分配分片、磁盘 — 只读：green/yellow/red、节点列表、未分配（UNASSIGNED）分片及其原因（allocation explain）、磁盘使用率和 watermark、挂起任务。不确定该做什么时从这里开始。
• 处理未分配（UNASSIGNED）分片（依据 explain） — 集群为 yellow 或 red，分片无法分配：根据 allocation explain 给出的原因，处理磁盘、allocation filtering、重试上限（retry_failed）、副本数，或作为最后手段从旧副本分配主分片。
• 查看 / 修改磁盘 watermark 设置 — 磁盘占用导致分片被迁移或无法分配；需要临时或永久修改 watermark 阈值（low / high / flood_stage），或恢复为默认值。
• 索引变为只读：移除 read_only_allow_delete 块 — 写入被拒绝，报错 'FORBIDDEN/12/index read-only / allow delete (api)' 或 'TOO_MANY_REQUESTS/12/disk usage exceeded flood-stage watermark'：先释放磁盘空间，再移除块。
• 向集群添加节点（enrollment token） — 需要扩容：新服务器上已安装 Elasticsearch，使用 enrollment token 加入集群；分片自动重新平衡。无停机。
• 安全下线节点（exclude、腾空、关闭） — 节点要退役或更换硬件：通过 allocation exclude 将其分片迁移到其他节点，确认节点已腾空；若为 master-eligible 节点则加入 voting exclusion，然后关闭。
• Reindex：为修改 mapping/设置，借助新索引和别名零停机切换 — 需要修改 mapping 字段类型、analyzer 或分片数：创建新索引，用 _reindex 复制数据，再将别名原子地切换到新索引。
• 配置 / 排查索引生命周期（ILM）与 rollover — 日志/时间序列索引持续增长或未被删除：配置 ILM 策略（rollover + delete）、索引模板和初始索引（写别名）；用 explain 查看现有策略为何不推进。
• 修正分片数：_shrink（减少）/ _split（增加） — 索引的分片数选得不合适：过小的分片（分片过多）用 _shrink 合并，过大的分片用 _split 拆分；通过别名切换。
• 从快照以新名称恢复单个索引 — 某个索引被删除或损坏：从快照存储库只恢复该索引，以新名称（rename）恢复，不影响在线索引；验证后通过别名投入使用。

开始之前

• 在 …（…）上有 root 权限、curl 和集群的 HTTP CA 证书（…）；掌握 elastic 用户（或具有 manage + 索引权限的用户）的密码。API 调用通过 HTTPS 发往该节点。
• 已创建变更记录并通知应用团队。分片迁移、reindex 和 resize 操作会带来磁盘、网络和 CPU 负载；请在业务高峰之外执行。执行不可逆步骤（删除、stale/empty primary）之前必须有最新快照：快照。
• 新服务器已按集群安装指南中的操作系统准备和软件安装阶段准备就绪：相同的 Elasticsearch 版本、vm.max_map_count、heap、已关闭 swap、防火墙已放行 9200/9300；服务从未启动过（enrollment 只能在首次启动之前进行）。

指南阶段

• API 访问 — API 临时凭据文件
• 状态：健康、节点、分片、磁盘（只读） — 集群健康、节点和未分配分片 · 查询分片未分配的原因（allocation explain） · 磁盘使用率和 watermark · 挂起任务及结果解读
• 1. 诊断：分片为什么没有分配？ — 索引的分片及 explain 结论
• 2. 执行 — 重试失败的分配（retry_failed） · 使副本数与节点数匹配 · 移除 allocation filtering · 转到磁盘问题 · 从旧副本分配主分片（allocate_stale_primary） · 分配空主分片（allocate_empty_primary）
• 3. 验证 — 观察分片启动
• 1. 诊断 — 磁盘使用率和当前阈值
• 2. 执行 — …修改阈值…将阈值恢复为默认值…
• 1. 诊断：块与磁盘 — 查看被加块的索引和磁盘 · 释放磁盘空间的方法
• 2. 执行 — 移除块
• 3. 验证 — 测试写入是否正常
• 1. 诊断 — 查看集群状态
• 2. 执行：enrollment 与加入 — 创建节点 enrollment token · 使用 token 配置新节点 · 检查 node.name 和网络设置 · 启动服务
• 3. 验证 — 验证节点已加入并开始接收分片
• 1. 诊断 — 查看节点的分片和角色
• 2. 执行：腾空并关闭 — 将分片迁出节点（allocation exclude） · 等待节点腾空 · 将 master-eligible 节点移出投票 · 停止节点 · 移除 exclude 和 voting exclusion
• 3. 验证 — 验证集群健康
• 1. 诊断与准备 — 查看源索引和别名 · 使用新 mapping/设置创建新索引
• 2. 执行：复制并切换别名 — 复制数据（_reindex，后台运行） · 监控任务 · 准备新索引并比较数量 · 将别名原子地切换到新索引
• 3. 后续 — 关闭旧索引（稍后删除）
• 1. ILM 策略、模板和初始索引 — 创建 ILM 策略 · 创建索引模板 · 创建带写别名的初始索引
• 诊断：ILM 为何不推进？ — 查看 ILM 状态和失败的索引 · 重试失败的步骤
• 手动 rollover — 立即 rollover 别名
• 1. 诊断 — 索引的分片数和大小
• 3. 执行 — …Shrink…Split…：… → …（… 个分片） · 将别名切换到新索引
• 4. 后续 — 关闭源索引（稍后删除）
• 1. 诊断：快照中是否有该索引？ — 查看快照及其中的索引
• 2. 执行：以新名称恢复 — 以 …… 名称恢复索引 · 验证并投入使用
• 清理 — 删除凭据文件