当前位置：首页 > news >正文

Elasticsearch ILM 故障排除：常见问题及修复

news 来源：原创 2025/5/13 9:40:03

作者：来自 Elastic Stef Nestor

大家好！我们的 Elasticsearch 团队正在不断改进我们的索引生命周期管理 (index Lifecycle Management - ILM) 功能。当我第一次加入 Elastic Support 时，我通过我们的使用 ILM 实现自动滚动教程快速上手。在帮助多个用户设置 ILM 后，我注意到升级主要来自少数配置问题。

在以下部分中，我想介绍常见的工单、诊断流程和常见错误恢复。显示的所有命令都可以通过 Kibana 的 Dev Tools 运行。

配置

ILM 后端进程默认运行，但需要用户配置才能影响索引。你可以通过 ILM 状态返回 operation_mode:RUNNING 来验证 ILM 是否正在运行。

常见问题 1：ILM 未运行

ILM 默认运行。如果你之前已停止 ILM，则需要重新启动 ILM。

ILM 设置为在六个连续阶段中保存数据。阶段 “new” 在索引创建时是隐含的，后面是五个可配置阶段。

常见问题 2：数据未删除

人们普遍误以为配置热阶段的滚动会自动删除数据。必须明确配置删除数据阶段才能删除数据。必须明确指定每个可配置阶段。

每个可配置阶段都有一组允许的连续操作。这些操作由你自行配置，但大多数用户至少启用设置优先级、滚动和删除操作。可以通过 Kibana UI 或 Elasticsearch API 配置策略和操作。我经常看到并使用以下策略（可从 “Get ILM Policy” 访问）：

GET _ilm/policy/INDEX_POLICY_NAME
{"policy": {"phases": {"hot": {"actions": {"rollover": {"max_age": "30d","max_size": "50gb"},"set_priority": {"priority": 100}},"min_age": "0ms"},"warm": {"min_age": "7d","actions": {"set_priority": {"priority": 50},"shrink": {"number_of_shards": 1},"forcemerge": {"max_num_segments": 1}}},"delete": {"min_age": "365d","actions": {"delete": {}}}}}
}

此策略（policy）指示系统立即将数据发送至 hot 阶段，创建新索引并每 30 天或 50 GB（以先到者为准）滚动更新以前的数据。滚动更新七天后，索引将不再需要文档更新，从而进入 warm 阶段。此时，该策略附加了以下两个操作：shrink（减少分片数量）和 force merge（压缩数据并擦除已删除的记录）。数据将一直处于 warm 阶段，直到滚动更新 365 天后被删除。

常见问题 3：min_age 计算说明

在与客户合作时，我发现关于 min_age 的工作方式常常存在困惑。min_age 必须在后续阶段之间递增。如果使用了 rollover（滚动），min_age 是根据滚动日期计算的。这是因为滚动操作会生成一个新索引，并使用新索引的创建日期进行计算。否则，min_age 将基于原始索引的创建日期进行计算。

一旦创建策略，就需要明确附加到索引才能生效。

常见问题 4：明确将策略连接到索引

为策略和索引赋予相同的名称并不会将两者联系在一起。例如，将你的策略命名为 filebeat-* 并不会将其连接到你的 filebeat-* 索引；你仍然需要明确将索引附加到策略。

你可以手动将策略附加到现有索引，但通常你会设置模板以在索引通过 Beat YAML 配置文件（例如：Filebeat 和 Metricbeat）或通过索引模板（index template）配置创建时自动附加策略

PUT _index_template/TEMPLATE_NAME
{"index_patterns": ["INDEX_NAME-*"],"template": {"settings": {"number_of_shards": 1,"number_of_replicas": 1,"index.lifecycle.name": "POLICY_NAME","index.lifecycle.rollover_alias": "INDEX_ALIAS"}}
}

你还可以通过 Kibana UI 配置索引模板。越来越多的用户正在转向数据流，它可以自动为你处理这些配置。

常见问题 5：手动管理现有索引

新策略不会自动应用于任何现有索引。索引模板（Index templates）可以附加策略，但模板仅在创建索引时应用。如果你已更新索引模板以自动附加策略和别名，它将在未来应用，但你需要手动将策略附加到任何现有索引。

你可以通过检索索引设置（index settings）来检查当前附加到索引的策略

GET INDEX_NAME-000001/_settings?filter_path=*.settings.index.lifecycle
{"INDEX_NAME-000001" : {"settings" : {"index" : {"lifecycle" : {"name" : "INDEX_POLICY_NAME","rollover_alias" : "INDEX_ALIAS"}}}}
}

常见问题 6：配置错误导致错误

如果这些为 NULL 或配置错误，你将遇到滚动操作错误。这些是我见过的最常见的 ILM 错误，我们将在下面介绍，因为它们取决于用户配置先决条件，而不仅仅是后端系统处理。你可以考虑使用不需要配置滚动别名的数据流（Data Streams）。

策略更新仅存储最新版本。

常见问题 7：仅存储最新的策略版本

用户无法恢复到之前的策略版本，一旦策略被覆盖就无法找回。每次发送的策略 PUT 请求都会创建或完全覆盖之前的版本，而不会部分更新策略的 JSON。

为了在操作切换时保持一致性，索引会将当前正在执行的策略阶段缓存到索引的元数据 phase_execution 中。通过检查 ILM 的 explain 输出，可以查看缓存的策略版本，以及它正在应用于哪个索引、处于哪个阶段、执行哪个操作或步骤。

GET INDEX_NAME-000001/_ilm/explain
{"indices": {"INDEX_NAME-000001": {"index": "INDEX_NAME-000001","managed": true,"policy": "INDEX_POLICY_NAME","lifecycle_date_millis": 1538475653281,"lifecycle_date": "2021-06-01T13:45:21.981Z","age": "25.14s","phase": "hot","phase_time_millis": 1538475653317,"phase_time": "2021-06-01T13:45:22.577Z","action": "rollover","action_time_millis": 1538475653317,"action_time": "2021-06-01T13:45:22.577Z","step": "attempt-rollover","step_time_millis": 1538475653317,"step_time": "2021-06-01T13:45:22.577Z","phase_execution": {"policy": "my_lifecycle3","phase_definition": {"min_age": "0ms","actions": {"rollover": {"max_age": "30m"}}},"version": 2,"modified_date": "2021-06-01T11:00:11.576Z","modified_date_in_millis": 1539609701576}}}
}

phase_execution 显示该策略缓存了其 hot 阶段内容，以便每 30 分钟滚动到新索引。如果将来更新附加策略，则策略缓存将在安全的情况下更新为策略的最新版本。

常见问题 8：策略版本安全更新

在索引进入策略的下一阶段之前，某些策略版本更新不会反映在索引的 phase_execution 缓存中。这是为了保护你的数据，并且一切都按预期运行。

有时用户在继承新系统后会升级工单。通常这是因为

他们需要在业务/网络需求发生变化时启用或禁用数据层。
他们新设置的 Elasticsearch 用户在编辑策略时权限不足，导致策略开始失败。

默认情况下，你需要在集群上拥有 manage_ilm 权限并在相关索引上进行管理，例如通过 super_user 角色。

常见问题 9：ILM 以上次编辑用户的身份运行

ILM 以上次编辑用户的身份执行操作，其权限与上次编辑策略时的用户相同。这些错误将显示为 action [x] is unauthorized for user [y]。以下是 Elastic Discuss 问题的示例。

诊断

如果 ILM explain 报告 ERROR 步骤，你可能需要解决问题才能让 ILM 继续运行。以下是最常见的错误及其解决方法

rollover alias [x] can point to multiple indices, found duplicated alias [x] in index template [z]
- 索引模板定义目标滚动别名。该别名只需要在第一个索引上引导一次，因为滚动操作将管理将别名滚动到下一个索引。你可以在索引模板中指定其他别名，但不能指定用于滚动的别名。

index.lifecycle.rollover_alias [x] does not point to index [y]
- 你需要检查索引设置 index.lifecycle.rollover_alias。索引指向错误的别名，或者别名不存在。你可以通过运行 Get Aliases 来检查后者。这是一个 Elastic Discuss 问题示例。你可以考虑使用 Data Streams 来处理这个问题。

setting [index.lifecycle.rollover_alias] for index [y] is empty or not defined
- 你的索引设置 index.lifecycle.rollover_alias 为空，无法使滚动生效。请更新索引设置以附加滚动别名来解决。以下是 Elastic Discuss 问题示例。你可以考虑使用 Data Streams 来处理此问题。

alias [x] has more than one write index [y,z]
- 运行 “Get Aliases” 时，你会注意到两个索引被标记为 is_write_index:true，但每个别名只能有一个索引。你需要通过 Aliases API 在其中一个索引上切换 is_write_index:false。

index name [x] does not match pattern ^.*-\d+
- 索引名称的正则表达式模式匹配是滚动生效的先决条件。用户最常忽略的问题是没有意识到索引名称需要以尾随数字结尾，例如 my-index-000001，而是只使用符合模式要求的 my-index。以下是 Elastic Discuss 问题示例。你可以考虑使用 Data Streams 来处理这个问题。

circuitBreakingException: [x] data too large, data for [y]
- 这表明集群资源已达到极限。请查看 Elasticsearch 管理和故障排除，以获得临时的系统缓解，以便继续进行 ILM 设置。

high disk watermark [x] exceeded on [y]
- 作为子集资源警告，这表明你的集群数据存储已达到极限。如果你尚未设置 hot 到 warm 节点 ILM 翻转，则通常会出现这种情况。你需要通过增加资源或删除不需要的索引或文档数据（或通过 delete_by_query）为你的集群腾出一些喘息空间。

系统将每十分钟自动重试失败的步骤，或者，一旦解决，你可以通过 Retry Policy Execution 手动触发重试

POST INDEX_NAME-000001/_ilm/retry

如果你想要暂时覆盖此间隔以进行测试，则需要更新集群设置以减少 indices.lifecycle.poll_interval。默认 ILM 集群设置如下

GET _cluster/settings?include_defaults=true&filter_path=*.indices.lifecycle*,*.xpack.ilm*
{ "defaults" : {"indices.lifecycle.history_index_enabled" : "true","indices.lifecycle.poll_interval" : "10m","indices.lifecycle.step.master_timeout" : "30s"}
}

如果策略配置正确且没有报告错误但你的操作没有进展，你需要调查它是否正在等待先决条件运行。

常见问题 10：良好的集群维护有助于 ILM 平稳运行

未分配（UNASSIGNED）分片可能导致策略执行无法继续，因为 ILM 在执行某些操作时会等待索引达到 “绿色” 状态。例如，迁移操作（migrate action）可能因此受阻。

由于我们已经检查了当前状态配置，并开始转向时间序列调查，因此接下来将查看 ILM 历史记录。ILM 历史记录默认通过 Elasticsearch 集群设置 indices.lifecycle.history_index_enabled:true 启用。根据部署版本的不同，可以通过在 Kibana 中创建 .ds-ilm-history-* 或 ilm-history-* 系统索引的索引模式来查看数据。在 Kibana Discover 中，我更喜欢通过切换表格列来浏览创建的索引模式，如：[index, policy, state.phase, state.action, state.step, success]。

如果 ILM 历史记录无法提供足够的详细信息，可以通过启用更详细的集群日志记录来获取更多信息。

PUT /_cluster/settings
{"transient": {"logger.org.elasticsearch.xpack.core.indexlifecycle": "TRACE","logger.org.elasticsearch.xpack.indexlifecycle": "TRACE"}
}

这非常繁重，只能暂时启用。对于本地集群，你可以在 Elasticsearch 日志中看到更详细的日志记录。对于 Elastic Cloud 部署，请参阅我的 Elastic Cloud 设置，了解如何启用和查看这些内容。

结论

我们已经介绍了 ILM 的常见问题、诊断流程和常见错误恢复。此时，如果你在解决问题时遇到困难，请随时联系我们。我们在这里，很乐意为你提供帮助！你可以通过 Elastic Discuss、Elastic Community Slack、咨询、培训和支持与我们联系。

原文：Troubleshooting Elasticsearch ILM: Common issues and fixes | Elastic Blog

配置