适用版本： 7.x-8.x
1. 错误异常的基本描述 #
failed to read global metadata 表示 Elasticsearch 在访问快照仓库时，尝试读取某个快照对应的全局元数据文件（global-* blob）失败。该错误通常发生在执行快照恢复、快照状态查询或仓库验证等操作中。
全局元数据（global metadata）包含集群的持久化设置、索引模板、SLM 策略等跨索引信息。当 Elasticsearch 无法从快照仓库中正确读取这些内容时，就会抛出该异常。
常见现象 #
- 执行
GET _snapshot/<repo>/<snapshot>时返回错误，快照状态显示为FAILED或INCOMPATIBLE。 - 恢复快照时失败，错误信息中包含
failed to read global metadata。 - 集群日志中反复出现该异常，可能伴随多个快照同时无法访问。
- Kibana 快照管理界面无法正常展示快照详情或恢复选项。
典型报错与异常栈 #
org.elasticsearch.snapshots.SnapshotException: [my_repo] [snapshot_2024-01-01] failed to read global metadata
Caused by: java.io.IOException: Failed to read blob [global-xxxx]
Caused by: java.nio.file.NoSuchFileException: /mnt/backups/my_repo/indices/global-xxxx
2. 为什么会发生这个错误 #
failed to read global metadata 的本质是快照仓库中的全局元数据文件不可读。以下是常见原因：
- 元数据文件被误删或覆盖：人工直接操作仓库后端（文件系统或对象存储）时，误删了
global-*相关 blob，或上传了不完整文件。 - 对象存储 I/O 异常：S3/OSS 等远端存储出现短时不可用、限流（429）、权限变更或网络超时，导致读取失败。
- 仓库挂载点不一致：多个节点对共享文件系统仓库（type:
fs）的挂载路径不同，部分节点看不到完整文件。 - 仓库被外部进程修改：非 Elasticsearch 进程（如备份脚本、清理任务）修改了仓库目录结构，破坏了元数据与数据 blob 的一致性。
- 快照写入未完成即被中断：集群在快照过程中崩溃或强制重启，导致全局元数据文件写入不完整。
- 仓库版本不兼容：快照仓库由旧版本 ES 创建，升级后格式变化导致读取失败。
3. 如何排查这个异常 #
建议按以下顺序进行排查：
- 从报错日志中获取准确的仓库名（
repo）和快照 ID（snapshotId），确认影响范围。 - 执行
GET _snapshot/<repo>/_all列出所有快照，确认是个别快照还是批量快照受影响。 - 执行
POST _snapshot/<repo>/_verify验证仓库连通性和节点访问一致性。 - 到仓库后端直接检查
global-*blob 是否存在、大小是否合理（通常为几百字节到几 KB）。 - 检查对象存储的访问日志或文件系统的 audit log，确认文件是否被外部操作修改或删除。
- 对比所有 master 和 data 节点的仓库配置（
GET _snapshot/<repo>），确认路径、权限和凭证一致。
排查时注意的问题 #
- 不要只看作 Elasticsearch 单条错误日志，需结合同一时间窗口内的集群状态变更记录（如节点加入/离开、master 重选举）。
- 如果仓库是 S3/OSS 类型，注意检查是否开启了生命周期规则（ILM/归档）导致对象被转入冷存储或删除。
- 如果问题只在部分节点出现，优先检查这些节点的仓库挂载方式和网络连通性。
4. 如何解决这个错误 #
常用修复思路 #
- 修复仓库可用性：如果是临时 I/O 问题，修复网络、权限或存储服务后重新执行快照操作即可。
- 放弃损坏快照：如果确认是个别快照的全局元数据已丢失且无法恢复，建议删除该快照（
DELETE _snapshot/<repo>/<snapshot>），使用其他可用快照进行恢复。 - 从备份重建仓库：如果仓库整体损坏严重，可以重新注册一个空仓库，从其他集群备份或先前导出的快照重新导入。
- 禁止人工操作仓库目录：将快照仓库路径纳入变更管控，禁止任何非 Elasticsearch 进程直接修改其内容。
- 增加一致性校验：定期执行
POST _snapshot/<repo>/_verify和快照状态检查，将异常纳入监控告警。
快照删除示例 #
# 删除损坏的快照（注意：此操作不可恢复）
DELETE _snapshot/my_repo/snapshot_2024-01-01
后续注意事项与推荐建议 #
- 为快照操作设置专门的监控项，包括快照成功率、仓库可用性和执行耗时，出现异常时及时告警。
- 快照仓库建议使用独立存储，避免与业务数据共用同一块磁盘或同一 bucket，减少相互干扰。
- 对于生产环境，建议保留至少 2 份不同时间点的快照，避免单快照损坏导致无法恢复。
- 在变更快照仓库配置前，先在测试环境验证，确认所有节点都能正常访问后再应用到生产。
借助 INFINI 产品提升排障效率 #
- INFINI Console 适合查看集群健康度、快照状态、仓库配置和恢复进度，帮助快速判断是仓库问题还是集群问题。
- INFINI Gateway 可部署在 Elasticsearch 前面，对快照相关请求进行观测和限流，防止大量并发快照操作对集群造成压力。
- 建议将快照执行结果、仓库错误日志和存储访问日志统一接入监控面板，缩短从"快照失败"到"定位根因"的时间。
5. 小结 #
failed to read global metadata 说明问题落在快照仓库元数据读取阶段，而非查询语句或索引 mapping。排查重点应放在仓库文件是否存在、底层存储是否可读、仓库是否被外部流程破坏，以及各节点对仓库的访问是否一致。通过规范仓库管理流程、加强监控和备份策略，可以有效降低此类问题的发生概率。
相关错误 #
- index-not-found-in-repository：仓库中未找到索引
- snapshot-already-running：快照已在运行
- another-snapshot-is-currently-running：另一个快照正在运行
- all-failed-to-update-cluster-state：更新集群状态失败
附：日志上下文 #
try {
return GLOBAL_METADATA_FORMAT.read(metadata.name(), blobContainer(), snapshotId.getUUID(), namedXContentRegistry);
} catch (NoSuchFileException ex) {
throw new SnapshotMissingException(metadata.name(), snapshotId, ex);
} catch (IOException ex) {
throw new SnapshotException(metadata.name(), snapshotId, "failed to read global metadata", ex);
}
}
@Override
public IndexMetadata getSnapshotIndexMetaData(RepositoryData repositoryData, SnapshotId snapshotId, IndexId index) throws IOException {
