Elasticsearch 的索引一旦创建，如果不加干预，分片数量、段文件大小和磁盘占用会持续膨胀。对于日志、指标、追踪这类按时间滚动的数据，靠人工定期删除旧索引或手动合并段非常低效。ILM（Index Lifecycle Management）允许管理员预先定义索引从出生到删除的完整策略，集群会按照时间或条件自动执行滚动、压缩、冻结和清理动作。下面的内容会围绕策略阶段、模板绑定和运行排查展开，所有配置都可以直接粘贴到 Kibana Dev Tools 中执行。
一、ILM 的四个阶段与核心动作
ILM 把索引生命周期拆成 Hot、Warm、Cold、Delete 四个可选阶段。Hot 阶段处理最新写入的数据，重点保障吞吐量；Warm 阶段处理查询频率下降但仍需快速读取的数据，通常会合并段和收缩分片；Cold 阶段适合很少被访问的归档数据，可冻结索引降低内存占用；Delete 阶段则按保留天数删除索引。每个阶段可以配置多个 action，并按顺序执行，比如先做 forcemerge 再做 shrink。
需要特别区分的是 min_age。它并不是从上一个阶段完成后的时间开始计算，而是从索引创建时间或 Rollover 后新索引起始时间计算。比如 min_age 设为 30d，表示索引创建满 30 天后才会进入该阶段；如果前面 Warm 阶段已经消耗了 15 天，Cold 阶段的 min_age 应该设为 45d 而不是 30d。这个计算方式经常被误解，导致索引卡在某一阶段无法流转。
下面是一个完整的 ILM 策略示例，包含四个阶段和常用动作。实际使用中可以根据数据规模删减 Warm 或 Cold 阶段，但建议至少保留 Hot 和 Delete，否则旧数据会一直占用磁盘。
{
"policy": {
"phases": {
"hot": {
"min_age": "0ms",
"actions": {
"rollover": {
"max_age": "7d",
"max_size": "50gb",
"max_docs": 100000000
},
"set_priority": {
"priority": 100
}
}
},
"warm": {
"min_age": "3d",
"actions": {
"forcemerge": {
"max_num_segments": 1
},
"shrink": {
"number_of_shards": 1
},
"allocate": {
"number_of_replicas": 1
}
}
},
"cold": {
"min_age": "30d",
"actions": {
"freeze": {},
"set_priority": {
"priority": 0
}
}
},
"delete": {
"min_age": "90d",
"actions": {
"delete": {}
}
}
}
}
}
上面策略里 rollover 同时配置了 max_age、max_size 和 max_docs，三者是或关系，只要满足任意一个条件，ILM 就会创建新索引并把写别名切过去。对于日志量波动较大的业务，建议同时配置时间和体积两个条件，避免单索引过大影响查询。
二、把策略绑定到索引模板
ILM 策略本身不会自动生效，必须通过索引模板或者直接在创建索引时指定 index.lifecycle.name。生产环境更推荐使用索引模板，因为模板可以让后续所有匹配的索引都自动继承策略，避免人为遗漏。模板中需要同时设置 ILM 策略名称和滚动别名，其中别名是 rollover 能够正常工作的关键。
下面这段模板会匹配所有 logs-myapp-* 的索引，并在 settings 中指定生命周期策略为 logs_policy，滚动别名为 logs-myapp-write。注意模板中的 index_patterns 必须覆盖首索引和后续滚动生成的索引，否则新索引会脱离管理。
{
"index_patterns": ["logs-myapp-*"],
"template": {
"settings": {
"index.lifecycle.name": "logs_policy",
"index.lifecycle.rollover_alias": "logs-myapp-write"
},
"mappings": {
"properties": {
"@timestamp": {
"type": "date"
},
"level": {
"type": "keyword"
},
"message": {
"type": "text"
}
}
}
}
}
模板创建完成后，还需要手动创建第一个索引，并显式指定写别名。ILM 不会凭空生成初始索引，它的 rollover 动作是在已有写索引上触发的。下面是初始化索引的请求示例，索引名建议带数字后缀，方便确认顺序。
PUT /logs-myapp-000001
{
"aliases": {
"logs-myapp-write": {
"is_write_index": true
}
}
}
当第一个索引满足 rollover 条件后，ILM 会自动创建 logs-myapp-000002，并把 logs-myapp-write 别名从 000001 切换到 000002。此时旧索引继续按照策略进入 Warm 或 Cold 阶段，新索引留在 Hot 阶段接收写入。整个过程中，客户端只需要向固定别名 logs-myapp-write 写入数据，无需关心底层索引名。
三、运行状态监控与错误排查
ILM 配置完成后，建议定期检查索引当前所处的阶段和步骤。Explain API 可以返回某个索引的 ILM 运行详情，包括策略名、当前阶段、当前动作、步骤以及错误信息。下面这条命令可以查看指定索引的状态。
GET /logs-myapp-000001/_ilm/explain
返回结果里最重要的是 step 字段和 phase 字段。正常流转中的索引会显示类似 check-rollover-ready 或 complete 的步骤；如果出现 ERROR，则需要查看 step_info 中的错误原因。常见错误包括 shrink 目标分片数无法整除源分片、forcemerge 因为磁盘空间不足失败、allocate 因为节点过滤条件不匹配无法分配副本等。
{
"indices": {
"logs-myapp-000001": {
"index": "logs-myapp-000001",
"managed": true,
"policy": "logs_policy",
"lifecycle_date_millis": 1700000000000,
"age": "1.5d",
"phase": "hot",
"action": "rollover",
"step": "check-rollover-ready",
"step_time_millis": 1700000000000,
"phase_execution": {
"policy": "logs_policy",
"phase_definition": {
"min_age": "0ms",
"actions": {
"rollover": { }
}
},
"version": 1,
"modified_date_in_millis": 1699999900000
}
}
}
}
当发现问题并修正策略或集群资源后，可以手动触发重试。ILM 的 retry 接口会让卡在错误步骤的索引重新执行当前动作，不需要删除策略重建索引。如果错误一直无法解决，可以先把 operation_mode 调整为 STOPPING 暂停 ILM，排查完成后再恢复为 RUNNING。
POST /logs-myapp-000001/_ilm/retry
四、参数调优与避坑要点
在 Hot 阶段规划好主分片数，可以避免后续 shrink 失败。Shrink 操作要求源索引的主分片数能被目标分片数整除，例如源索引 6 个主分片可以 shrink 到 3、2、1，但不能 shrink 到 4。很多策略一开始设置了 5 个主分片，到 Warm 阶段才想改成 1 个分片，结果只能一直重试报错。建议按最终可能需要的分片数倒推初始主分片数，并配合 number_of_routing_shards 为后续拆分预留空间。
Forcemerge 虽然能把段数量降到 1，但合并过程非常消耗 IO 和 CPU，不应该在写入高峰执行。Warm 阶段是一个比较合适的时机，因为此时索引基本不再写入，合并不会和实时写入争抢资源。合并完成后，段文件更少，文件句柄和内存使用会明显下降，查询性能也会更稳定。对于已经没有查询需求的索引，可以直接进入 Delete 阶段，不必执行 forcemerge。
Cold 阶段的 freeze 动作可以显著降低索引在内存中的开销，但冻结后的索引不能直接查询，需要先调用 _unfreeze 接口解冻。频繁解冻和冻结会产生额外开销，因此 Cold 阶段更适合归档半年以上且偶尔才抽查的数据。如果数据还需要日常查询，建议只停留到 Warm 阶段，不要过早冻结。
最后，监控磁盘水位和节点压力同样重要。ILM 本身不会无限扩容，如果集群整体磁盘使用率接近水位线，rollover 和 allocate 都可能失败。可以通过 _cluster/settings 调整磁盘水位阈值，或者提前增加数据节点。每一条 ILM 策略都应该结合业务的数据保留需求和集群硬件规模来设计，而不是把所有日志都设成相同的 90 天删除策略。
把策略、模板、别名和监控串起来之后，Elasticsearch 的索引生命周期管理才能真正自动化运转。它的价值不在于节省几次手动操作，而在于让索引的存储位置、分片数量和段结构始终处于合理状态，从而长期保持集群的写入和查询性能。
Elasticsearch索引生命周期管理ILM修改时间：2026-09-20 12:52:30