系列文章 :《Elasticsearch 9.x 从入门到精通》共 7 篇,本篇为第 5 篇,覆盖第 21~26 章。
基线 :Elasticsearch 9.x 源码 main 分支(
34eafb4ac58d,Version.CURRENT = V_9_7_0)与官方全量文档。写作纪律 :每个知识点标注官方文档出处,涉及实现原理均给出源码锚点
路径:行号,禁止编造 API。
本篇目录
- 第 21 章 集群拓扑与节点角色
- 第 22 章 分片:分配、路由与再平衡
- 第 23 章 快照与恢复
- 第 24 章 ILM 与数据生命周期管理
- 第 25 章 安全体系(Security)
- 第 26 章 性能与可观测性
第 21 章 集群拓扑与节点角色
出处:
refs/docs-content/deploy-manage/distributed-architecture/clusters-nodes-shards/node-roles.md、
discovery-cluster-formation/modules-discovery-quorums.md、
modules-discovery-voting.md;
refs/official-docs/reference/elasticsearch/configuration-reference/node-settings.md、
discovery-cluster-formation-settings.md源码:
server/src/main/java/org/elasticsearch/cluster/node/、
server/src/main/java/org/elasticsearch/cluster/coordination/
一个节点就是一次 Elasticsearch JVM 进程。节点角色不是"职责建议",而是决定
它能承载 shard、处理 ingest、执行 ML、连接 remote cluster、参加选举还是只做
协调。所有节点同时都是 coordinating node;这无法关闭,也不算一个可配置角色。
21.1 node.roles:默认、显式与空数组
未设置 node.roles 时,节点拥有以下角色:
yaml
master
data
data_content
data_hot
data_warm
data_cold
data_frozen
ingest
ml
remote_cluster_client
transform
显式设置后只拥有列出的角色:
yaml
node.roles: [ data_hot, data_content, ingest ]
空数组表示 coordinating-only node:
yaml
node.roles: [ ]
重要约束:
- 任何集群都需要
master,以及data_content + data_hot或通用data。 - CCS/CCR 需要
remote_cluster_client。 - ingest pipeline、monitoring 需要
ingest。 - transform、Fleet、Security 应用通常需要
transform;跨集群使用这些功能时
还需要remote_cluster_client。 - ML 异常检测需要
ml。 - 不要在专用 data tier 节点上同时设置通用
data角色;通用data会匹配任何
tier,削弱分层边界。
data 是通用角色,能匹配所有 data tier;data_content/hot/warm/cold/frozen
是专用 tier 角色。_tier_preference 不能写 data,因为 data 不是 tier。
源码中 DataTier.java:145-168 同时接受 tier 角色和通用 data 用于节点筛选。
21.2 角色地图与资源画像
| 角色/节点类型 | 主要责任 | 压力来源 | 常见误用 |
|---|---|---|---|
| master | 管理 cluster state、创建/删除索引、分配 shard | cluster state 写入、发布协议、元数据恢复 | 与重索引/ML 混部署导致 master 慢 |
| data_content | 商品、文章等长期可查内容 | 查询、聚合、少量索引 | 只给大磁盘不给 CPU |
| data_hot | 时间序列最近数据、新 data stream | 高写入 + 高查询 | refresh 太短、shard 过多 |
| data_warm | 近期较少查询数据 | 查询为主、偶发写入 | 与 hot 同硬件且不限制写入 |
| data_cold | 历史低频查询,可挂 fully mounted searchable snapshot | 偶发查询、恢复 | 期待 frozen 级别的存储节省 |
| data_frozen | partially mounted searchable snapshot | 仓库 IO、共享缓存 | 没有快照仓库或缓存过小 |
| ingest | 执行 ingest pipeline | enrich、NLP、解析 | 只设 ingest 没有数据角色,enrich lookup 远程化 |
| ml | ML job、异常检测、推理 | 原生进程、模型内存 | 误当普通数据节点 |
| transform | transform 持续物化 | 聚合+写入 | 长时间占用通用数据节点 |
| coordinating-only | 路由请求、gather/reduce | 高峰请求放大、内存 | 加太多,master 发布确认变慢 |
每类节点都仍是 coordinating node。大搜索请求的 gather phase 在接收请求的节点上
发生;如果这个节点资源不足,即使 data 节点很快,客户端也会感受到慢。
21.3 master、quorum 与脑裂
Elasticsearch 9.x 不再用旧版 ZooKeeper 式表述,也不再建议把协调子系统叫
"Zen2"作为生产配置语言。核心机制是 quorum-based coordination:
- 只有 voting configuration 中的 master-eligible 节点的响应参与决策;
- 决策需要超过一半(more than half)投票节点响应;
- 每个 cluster state 变更都要发布并得到确认;
- 每个节点保存上一接受的 cluster state,重启后据此恢复。
可用性公式:
text
tolerated_failures = floor((voting_nodes - 1) / 2)
因此 3 或 4 个 master-eligible voting 节点可容忍 1 个失败;5 或 6 个可容忍
2 个失败。官方文档强调:不要同时停止一半或更多 voting configuration 节点。
| master-eligible 数量 | 投票节点数(通常) | 可容忍故障 |
|---|---|---|
| 1 | 1 | 0 |
| 2 | 2 | 0 |
| 3 | 3 | 1 |
| 4 | 3 | 1 |
| 5 | 5 | 2 |
| 6 | 5 | 2 |
偶数节点通常会让 voting configuration 保持奇数:例如 4 个 master-eligible 时,
其中 3 个进入 voting configuration。这样网络平分时,其中一半可能有 2/3 投票,
可以继续决策;若 4 个都投票,平分时两侧都不够 3 票,集群反而无法推进。
生产建议:
- HA 集群至少 3 个 master-eligible 节点,其中至少 2 个不是
voting_only; - master 节点使用低延迟、持久可靠的本地磁盘;
- 不要用 "2 主节点 + 1 热备但不开 master"作为 HA 方案;
- 增删 master-eligible 节点要等待 voting configuration 调整完成;
- 不确定时用 voting exclusions API 管理退出节点。
21.4 master-eligible 变体
专用 master
yaml
node.roles: [ master ]
适合中大型集群。它仍然可作为 coordinating node,但不应让客户端主动把这种节点
当搜索入口。它的价值是让 cluster state 发布不受 indexing/search 阻塞。
voting-only master
yaml
node.roles: [ master, voting_only ]
或带 data 角色:
yaml
node.roles: [ data_hot, master, voting_only ]
它能参与选举和 cluster state 发布,但不会被选为 master。HA 集群要求至少 3 个
master-eligible,其中至少 2 个不是 voting-only。它可以用作第三台投票机器,
但不是降低 master 资源要求的万能药:它仍在 cluster state 发布关键路径上。
coordinating-only
yaml
node.roles: [ ]
它不是"无角色",而是只做协调。大集群用它把路由和 gather 压力从 data/master
节点移出来。但每个新协调节点都要接收完整 cluster state 并在 cluster state
发布时确认;加太多会增加 master 发布开销。
21.5 数据分层
| tier | 写入 | 查询频率 | 存储/副本策略 | 典型搜索方式 |
|---|---|---|---|---|
| content | 低且不再更新 | 持续查询 | 通常有副本 | 普通索引 |
| hot | 高 | 高 | 至少 1 副本 | 普通索引 |
| warm | 很低 | 较高 | 至少 1 副本 | 普通索引 |
| cold | 只读/几乎不写 | 低 | 可用 fully mounted searchable snapshot;无副本 | 普通索引或 searchable snapshot |
| frozen | 只读 | 极低 | partially mounted;共享缓存 | searchable snapshot |
_tier_preference 是"按顺序找第一个可用 tier",不是"必须全部存在"。
http
PUT logs-2026.11.01/_settings
{
"index.routing.allocation.include._tier_preference": "data_cold,data_warm,data_hot"
}
含义:优先 data_cold;cold 没有节点则退到 warm;warm 也没有则退到 hot。
data stream 的新 backing index 默认进入 hot;非 data stream 普通索引通常进入
content tier。
冻结层要求快照仓库;partially mounted index 只能分配到有 shared cache 的节点。
专用 frozen 节点默认共享缓存约为磁盘空间的 90%,另有 100GB headroom 上限。
相关设置 xpack.searchable.snapshot.shared_cache.size 只能配置在
data_frozen 节点上。
21.6 变更角色与重启
节点的磁盘数据会随角色变化变得"多余":
- 数据节点保存 shard 数据、索引元数据、cluster-wide metadata;
- master-eligible 保存所有索引元数据和 cluster-wide metadata。
节点启动会检查数据路径。去掉 data 角色后如果还有 shard 数据,或去掉
master + data 后还有索引元数据,节点会拒绝启动。官方给出的路径是:
- 先用 allocation filter 迁走 shard;
- 关闭节点并改角色;
- 用空数据路径启动全新节点,或使用
elasticsearch-node repurpose清理多余数据。
不要手工删除数据目录内容。Elasticsearch 不支持从手工文件系统备份恢复;备份
使用 Snapshot and restore。
21.7 首次引导与常用诊断
首次创建集群必须显式 bootstrap。elasticsearch.yml 只在一个初始
master-eligible 节点上设置一次:
yaml
cluster.initial_master_nodes:
- master-a
- master-b
- master-c
生产集群不要把这个配置长期留在所有节点上。已加入集群的节点不需要它。
源码里 ClusterBootstrapService.java:103-108 只在本地节点未加入已 bootstrap
集群时把 cluster.initial_master_nodes 作为需求集合;:198 要求满足需求的节点
超过一半才继续。
诊断命令:
http
GET _cat/nodes?v&h=ip,name,node.role,master,heap.percent,disk.used_percent
GET _cluster/health
GET _cluster/state?filter_path=metadata.cluster_coordination.last_committed_config
GET _cluster/allocation/explain
| 现象 | 先查 |
|---|---|
| 一直 "master not discovered" | voting configuration、initial_master_nodes、网络、TLS |
| yellow 但可查询 | 副本未分配、磁盘水位、tier preference |
| red | 有 primary 未分配;立刻看 allocation explain |
| 新节点不启动 | 角色 repurpose 后数据路径残留 |
| remote cluster 失败 | 节点是否缺 remote_cluster_client |
第 22 章 分片:分配、路由与再平衡
出处:
refs/official-docs/reference/elasticsearch/index-settings/shard-allocation.md、
configuration-reference/cluster-level-shard-allocation-routing-settings.md、
index-settings/data-tier-allocation.md、index-settings/total-shards-per-node.md;
refs/docs-content/deploy-manage/distributed-architecture/shard-allocation-relocation-recovery/源码:
server/src/main/java/org/elasticsearch/cluster/routing/allocation/
分片分配回答三个问题:新 shard 放哪里;节点离开后副本是否补;集群何时移动
shard。文档路由回答另一个问题:一个文档属于哪个 primary shard。两者经常被
混为一谈,但前者是 master 的 allocation 决策,后者是写入请求的哈希计算。
22.1 路由公式与请求路径
普通索引的文档路由从 9.4 起是:
text
shard = hash(_routing) % number_of_shards
_routing 默认是 _id。显式 routing 会替换默认 _id:
http
PUT orders/_doc/1?routing=tenant-42
{ "order_id": "1" }
路由值不变时,同一文档总是进入同一 shard。显式 routing 的收益是按租户、用户、
设备等业务键把相关文档聚到同一 shard;代价是查询也必须带相同 routing,否则
会扫所有 shard。
index.number_of_routing_shards 在 9.6 已标记 deprecated。9.4 之后创建的索引
使用新的哈希路由;旧索引或旧自定义路由场景才需要理解 legacy routing factor。
搜索请求默认访问所有 primary/replica 副本中可用的 shard copy。显式 routing
可以让搜索只访问目标 shard,但会改变"全量"语义;不要用它做普通查询优化。
22.2 allocation 决策树
master 在每次 cluster state 变化、节点加入/离开、索引创建、设置更新时触发
allocation。决策不是单一规则,而是多个 decider 依次判断:
text
unassigned / can_remain shard
→ AllocationService
→ ShardsAllocator(desired_balance 或 balanced)
→ AllocationDeciders
same_shard:primary 和 replica 不能同节点
filtering:include/require/exclude
awareness:rack/zone 分散
disk threshold:low/high/flood watermark
shards limit:cluster/index total_shards_per_node
throttling:并发恢复/再平衡限速
enable:all/primaries/new_primaries/none
9.x 默认 allocator 是 desired_balance。它由 master 后台计算目标平衡状态,
然后移动 shard;旧的 balanced allocator 在 8.8 已标记 deprecated,只用于兼容。
22.3 include、require、exclude
索引级 filter:
http
PUT test/_settings
{
"index.routing.allocation.require.size": "big",
"index.routing.allocation.require.rack": "rack1"
}
| 过滤器 | 语义 |
|---|---|
include.<attr> |
节点属性至少匹配一个逗号分隔值 |
require.<attr> |
节点属性必须匹配全部列出的值 |
exclude.<attr> |
节点属性不能匹配任何列出的值 |
内置属性:
text
_name, _host_ip, _publish_ip, _ip, _host, _id, _tier, _tier_preference
集群级 filter 同样支持这些语义,用于下线节点:
http
PUT _cluster/settings
{
"persistent": {
"cluster.routing.allocation.exclude._ip": "10.0.0.1"
}
}
多个 filter 同时存在时必须同时满足。如果 filter 太严格,可能导致 shard 永远
unassigned;此时用 _cluster/allocation/explain 查看具体 decider。
22.4 awareness 与 forced awareness
awareness 用节点属性表达物理拓扑:
yaml
node.attr.rack_id: rack1
http
PUT _cluster/settings
{
"persistent": {
"cluster.routing.allocation.awareness.attributes": "rack_id"
}
}
awareness 尽量把同一 shard 的 primary 和 replica分散到不同 rack/zone。
forced awareness 进一步要求每个 zone 都有可用容量,避免一个 zone 故障后所有
副本挤到另一个 zone:
http
PUT _cluster/settings
{
"persistent": {
"cluster.routing.allocation.awareness.force.rack_id.values": "rack1,rack2,rack3"
}
}
forced awareness 是容量承诺:如果某个 zone 的容量不足,副本可能无法分配,
集群变 yellow。它不是"自动扩容"。
源码锚点:AwarenessAllocationDecider.java:70。
22.5 数据分层与 _tier_preference
_tier_preference 是 data tier 的首选顺序:
http
PUT logs-2026.11.01/_settings
{
"index.routing.allocation.include._tier_preference": "data_warm,data_hot"
}
含义:优先 warm;warm 没有可用节点则退到 hot。这防止索引因为首选 tier 缺失而
unassigned。
| tier | 角色 |
|---|---|
| content | data_content |
| hot | data_hot |
| warm | data_warm |
| cold | data_cold |
| frozen | data_frozen |
通用 data 角色能匹配任何 tier,但不是合法 _tier_preference 值。
22.6 total_shards_per_node
集群级设置:
http
PUT _cluster/settings
{
"persistent": {
"cluster.routing.allocation.total_shards_per_node": 100
}
}
索引级设置:
http
PUT logs-2026.11.01/_settings
{
"index.routing.allocation.total_shards_per_node": 5
}
这个值统计 primary + replica。默认 -1 表示不限。它不是"每节点最大数据量",
而是 shard 数量保护。设置过低会阻止副本分配;设置过高则失去保护意义。
源码锚点:
text
ShardsLimitAllocationDecider.java:53 // index setting
ShardsLimitAllocationDecider.java:65 // cluster setting
22.7 再平衡
集群平衡不是"磁盘使用率相同"。官方文档明确说:磁盘使用率与真实资源需求没有
必然关系。平衡权重综合考虑:
- 每节点 shard 数;
- 每索引 shard 分布;
- 预估磁盘占用;
- 预估写入线程负载。
常用设置:
| 设置 | 默认 | 说明 |
|---|---|---|
cluster.routing.allocation.allow_rebalance |
always |
何时允许再平衡 |
cluster.routing.rebalance.enable |
all |
可限制 primaries/replicas/none |
cluster.routing.allocation.cluster_concurrent_rebalance |
2 | 全集群并发再平衡 |
cluster.routing.allocation.balance.threshold |
1.0 | 权重改善低于阈值就不移动 |
cluster.routing.allocation.balance.shard |
0.45 | shard 数权重 |
cluster.routing.allocation.balance.index |
0.55 | 同索引分布权重 |
cluster.routing.allocation.balance.disk_usage |
2e-11 | 磁盘占用权重 |
cluster.routing.allocation.balance.write_load |
10.0 | 写入负载权重 |
官方不建议调整后四个权重。大集群可以适度提高 balance.threshold,接受轻微
不均衡,减少 shard 移动。
源码锚点:BalancedShardsAllocator.java:84;
DesiredBalanceShardsAllocator.java:56;DesiredBalanceComputer.java:59。
22.8 磁盘水位
| 水位 | 默认 | 行为 |
|---|---|---|
| low | 85% | 超过后不再分配新 shard;不影响新索引 primary |
| high | 90% | 尝试把 shard 移走 |
| flood_stage | 95% | 对受影响索引加 index.blocks.read_only_allow_delete |
max headroom 只对百分比/比例水位生效,用于大磁盘场景限制所需空闲空间:
text
low.max_headroom 默认 200GB
high.max_headroom 默认 150GB
flood_stage.max_headroom 默认 100GB
frozen flood_stage.max_headroom 默认 20GB
百分比表示已用空间;字节值表示剩余空间。不要混用百分比和字节值。
源码锚点:DiskThresholdSettings.java:32、:168、:190;
DiskThresholdDecider.java:68。
22.9 恢复优先级与限速
unassigned shard 按优先级恢复:
index.priority高者优先;- 创建日期新者优先;
- 索引名高者优先。
http
PUT current-logs/_settings
{
"index.priority": 100
}
恢复并发:
| 设置 | 默认 | 说明 |
|---|---|---|
node_concurrent_incoming_recoveries |
2 | 每节点并发 incoming |
node_concurrent_outgoing_recoveries |
2 | 每节点并发 outgoing |
node_concurrent_recoveries |
2 | 同时设置 incoming/outgoing |
node_initial_primaries_recoveries |
4 | 本地 primary 恢复更快,可更高 |
indices.recovery.max_bytes_per_sec |
取决于节点配置 | 网络恢复限速 |
不要为了"快点恢复"盲目调大并发。恢复会占用 CPU、磁盘 IO、网络和 heap;
如果集群本来已经过载,更高并发只会放大问题。
源码锚点:ThrottlingAllocationDecider.java:239;
ShardRouting.java:1008-1009 描述 recovery priority 的语义。
22.10 reroute 与手动干预
POST /_cluster/reroute 用于显式移动 shard 或解释分配。常用命令包括
move、allocate_stale_primary、allocate_empty_primary、cancel。
http
POST _cluster/reroute
{
"commands": [
{
"move": {
"index": "logs-2026.11.01",
"shard": 0,
"from_node": "hot-1",
"to_node": "warm-1"
}
}
]
}
allocate_stale_primary 和 allocate_empty_primary 是危险命令:
allocate_stale_primary接受可能过期的 primary,可能丢最近写入;allocate_empty_primary创建空 primary,明确接受数据丢失;- 两者都应只在确认副本/备份不可用时使用。
22.11 排障
http
GET _cluster/health
GET _cat/shards?v&h=index,shard,prirep,state,node,unassigned.reason
GET _cluster/allocation/explain
GET _cat/allocation?v
| 现象 | 可能原因 |
|---|---|
| primary unassigned | 磁盘水位、filter、节点角色、数据损坏、需要 allocate 命令 |
| replica unassigned | 副本数大于可用节点、awareness/forced awareness、total_shards_per_node |
| yellow 持续 | 有副本未分配;先看 allocation explain |
| red 但 primary 正常 | 通常有 replica 丢失或索引关闭/损坏 |
| rebalance 不停 | 权重阈值过低、节点容量差异大、写入负载估算变化 |
| 磁盘只读 | flood stage;清理数据或临时调整水位后删除只读块 |
第 23 章 快照与恢复
出处:
refs/docs-content/deploy-manage/tools/snapshot-and-restore/、
refs/official-docs/reference/elasticsearch/configuration-reference/snapshot-restore-settings.md、
cluster-state-encryption-key.md源码:
server/src/main/java/org/elasticsearch/snapshots/、
server/src/main/java/org/elasticsearch/repositories/、
x-pack/plugin/slm/、x-pack/plugin/searchable-snapshots/
快照是 Elasticsearch 官方备份机制,不是文件系统备份。它备份 shard 数据、索引
元数据和可选 cluster state/feature state;不备份 $ES_PATH_CONF 下的
elasticsearch.yml、keystore、TLS 证书和 realm 私钥。
23.1 repository:fs、url、S3、Azure、GCS、HDFS、source
repository 是快照的存放位置,必须先注册并验证。常用类型:
| type | 说明 | 注意 |
|---|---|---|
fs |
共享文件系统 | 所有节点必须能访问同一目录;不要只在一台节点挂载 |
url |
只读 HTTP/HTTPS/文件 URL | 只读,不能作为写入 repository |
s3 |
AWS S3 或兼容对象存储 | 支持可写快照和 searchable snapshot |
azure |
Azure Blob Storage | 支持可写快照和 searchable snapshot |
gcs |
Google Cloud Storage | 支持可写快照和 searchable snapshot |
hdfs |
Hadoop HDFS | 支持 searchable snapshot |
source |
source-only repository | 只存 _source,不能对 searchable snapshot 索引再快照 |
fs 示例:
http
PUT _snapshot/local_repo
{
"type": "fs",
"settings": {
"location": "/mnt/es-snapshots"
}
}
S3 示例:
http
PUT _snapshot/s3_repo
{
"type": "s3",
"settings": {
"bucket": "es-snapshots",
"region": "us-east-1"
}
}
9.4 引入 repositories.default_repository,当前用于 DLM frozen tier transition;
必须是已注册、非只读 repository。源码见
RepositoriesService.java:120、:171-173。
23.2 手动快照
http
PUT _snapshot/s3_repo/snap-20261114?wait_for_completion=true
{
"indices": "*",
"include_global_state": true
}
要点:
- 同一 repository 内快照名必须唯一;
- 快照自动去重,频繁快照的存储增量通常很小;
- 每个快照逻辑独立,可单独删除;
wait_for_completion=true会阻塞客户端,生产大快照通常用false后轮询状态;- 快照开始后新写入不包含在本次快照中;
- 快照过程可能短暂暂停 shard allocation,但不阻塞索引;
- data stream 快照包含 backing indices 和 stream metadata;只选部分 backing
index 时不会包含完整 data stream metadata。
监控:
http
GET _snapshot/s3_repo/_current
GET _snapshot/_status
GET _slm/stats
并发快照操作受 snapshot.max_concurrent_operations 限制,默认 1000,覆盖
创建、克隆、删除。
23.3 SLM:策略、保留与安全
SLM 是定时快照和保留策略。下面策略每天 01:30 UTC 备份全量数据,保留 30 天:
http
PUT _slm/policy/nightly-snapshots
{
"schedule": "0 30 1 * * ?",
"name": "<nightly-snap-{now/d}>",
"repository": "s3_repo",
"config": {
"indices": "*",
"include_global_state": true
},
"retention": {
"expire_after": "30d",
"min_count": 5,
"max_count": 50
}
}
手动执行:
http
POST _slm/policy/nightly-snapshots/_execute
保留任务独立于快照任务运行,默认每天 01:30 UTC:
http
PUT _cluster/settings
{
"persistent": {
"slm.retention_schedule": "0 30 1 * * ?"
}
}
| 设置 | 默认 | 说明 |
|---|---|---|
slm.history_index_enabled |
true | 记录 SLM 历史到 slm-history-* |
slm.retention_schedule |
0 30 1 * * ? |
保留任务 cron |
slm.retention_duration |
1h | 限制删除旧快照时长 |
slm.health.failed_snapshot_warn_threshold |
5 | 连续失败次数触发健康警告 |
snapshot.max_concurrent_operations |
1000 | 并发快照操作上限 |
安全权限:
manage_slm:管理策略、启动/停止 SLM;read_slm:读取策略和状态;cluster:admin/snapshot/*:创建/删除快照;.slm-history-*需要相应索引权限。
23.4 feature state 与 cluster state
include_global_state: true 时,快照包含 cluster state,并默认包含所有
feature state。include_global_state: false 时默认不包含 feature state。
也可以只选特定 feature state:
http
PUT _slm/policy/security-state-only
{
"schedule": "0 30 2 * * ?",
"name": "<security-state-{now/d}>",
"repository": "secure_repo",
"config": {
"include_global_state": true,
"indices": "-*",
"feature_states": ["security"]
},
"retention": {
"expire_after": "30d",
"min_count": 5,
"max_count": 50
}
}
security feature state 包含用户、角色、API key 等系统索引。官方建议把
cluster state 快照放到专用 repository,并严格控制访问。恢复 security feature
state 会覆盖认证系统索引,必须提前准备恢复用管理员。
23.5 restore
常规索引/数据流
http
POST _snapshot/s3_repo/snap-20261114/_restore
{
"indices": "orders,logs-2026.11.01",
"rename_pattern": "(.+)",
"rename_replacement": "restored-$1",
"include_global_state": false,
"index_settings": {
"index.number_of_replicas": 1
}
}
规则:
- 已存在且打开的同名索引不能直接 restore;
- 已存在索引若要覆盖,必须先关闭,且 primary shard 数相同;
- restore 完成后索引自动打开;
- data stream restore 需要匹配的 index template;
- 跨集群 restore 不要求拓扑相同,但版本必须兼容;
- 原 cluster 仍有写权限时,新集群应把 repository 注册为 read-only。
feature state
http
POST _snapshot/s3_repo/snap-20261114/_restore
{
"feature_states": ["security"],
"include_global_state": false,
"indices": "-*"
}
feature state 恢复会关闭并覆盖对应系统索引。恢复 security 前必须确保仍能
访问集群;ECE/ECH 用 API console,自管/ECK 可临时创建文件 realm 恢复用户。
整个集群
整集群恢复是灾难恢复路径,不是常规迁移。必须先停止索引和自动管理组件,
包括 GeoIP downloader、ILM history、ILM、ML upgrade mode、monitoring、Watcher、
Universal Profiling 模板管理。然后删除现有数据流和索引,再 restore
cluster state + feature states。
源码锚点:RestoreService.java:159。
23.6 searchable snapshots
searchable snapshot 让索引从快照挂载,而不是把完整数据复制到节点。它需要
Enterprise license。
| 挂载方式 | cold/frozen | 本地存储 | 查询性能 |
|---|---|---|---|
| fully mounted | cold | 完整缓存 shard 数据 | 接近普通索引 |
| partially mounted | frozen | 共享缓存只保留最近访问数据 | 缓存未命中时读仓库,更慢 |
ILM 会自动转换;手动挂载用:
http
POST _snapshot/s3_repo/snap-20261114/_mount?wait_for_completion=true
{
"index": "logs-2026.11.01",
"renamed_index": "partial-logs-2026.11.01",
"storage": "shared_cache"
}
要点:
- searchable snapshot 索引默认没有 replica;快照就是数据副本;
- 节点故障后从 repository 恢复,不需要普通 replica;
- 需要更高查询吞吐时可以加 replica;
- 挂载前建议 force merge 到每 shard 1 个 segment;
- 不要删除仍有 mounted index 的快照或注销 repository;
- searchable snapshot 索引的快照只包含指向原始快照的 metadata,不复制数据;
- source-only repository 不能对 searchable snapshot 索引再快照。
共享缓存:
yaml
xpack.searchable.snapshot.shared_cache.size: 4TB
专用 frozen 节点默认约为磁盘 90%,并受 100GB headroom 上限影响;非专用节点
默认 0,必须显式设置。只有 data_frozen 节点可配置。
23.7 cluster state encryption
cluster state encryption 保护 feature-managed secrets,例如 ES|QL data federation
凭据。它与 keystore secure settings 不同:keystore 存放运维提供的本地安全配置;
cluster state encryption 保护通过集群 API 创建并复制到所有节点的秘密。
9.5 起 ES 自动生成集群级 encryption key。key 不通过 REST 暴露,也不进入快照。
节点内存中保留 key,并把本地副本持久化到磁盘;磁盘副本用 keystore 中的密码
保护:
yaml
cluster.state.encryption.password.<id>
cluster.state.encryption.active_password_id
自管集群示例:
shell
bin/elasticsearch-keystore add cluster.state.encryption.password.v1
bin/elasticsearch-keystore add -f cluster.state.encryption.active_password_id
然后 reload:
http
POST _nodes/reload_secure_settings
cluster.state.encryption.required 默认 true。设为 false 不推荐,因为会回退
明文存储。key 自动轮换由:
text
xpack.encryption.key_rotation.interval 默认 30d
xpack.encryption.key_rotation.check_interval 默认 1h
密码轮换按节点进行;旧密码要保留到节点加载新密码并重写本地 key 后再删除。
丢失密码时只能重置 key,且会永久丢失用旧 key 加密的数据:
http
POST _encryption/_reset?accept_data_loss=true
23.8 排障
| 现象 | 先查 |
|---|---|
| repository 验证失败 | 所有节点是否能访问;对象存储权限;路径是否共享 |
| 快照失败 | _snapshot/_status、对象存储错误、并发操作上限 |
| restore 冲突 | 同名 open index;primary shard 数不同;data stream 模板缺失 |
| frozen 索引慢 | shared cache 命中率、仓库延迟、segment 数 |
| searchable snapshot 数据丢失风险 | 是否删除了底层快照或 repository |
| cluster state encryption yellow | keystore 密码、active id、reload、节点磁盘 |
第 24 章 ILM 与数据生命周期管理
出处:
refs/docs-content/manage-data/lifecycle/index-lifecycle-management/index-lifecycle.md、
refs/official-docs/reference/elasticsearch/index-lifecycle-actions/index.md、
configuration-reference/index-lifecycle-management-settings.md、
configuration-reference/data-stream-lifecycle-settings.md源码:
x-pack/plugin/core/src/main/java/org/elasticsearch/xpack/core/ilm/、
x-pack/plugin/ilm/、modules/data-streams/、x-pack/plugin/downsample/
ILM 管理普通索引和 data stream backing index 的阶段流转。9.x 中另一条路线是
data stream lifecycle(DLM) :更轻量,只做 data stream 必需的操作,如
rollover、tail merging、retention、downsampling 和 frozen transition。
24.1 五个 phase
| phase | 写入 | 查询 | 典型动作 |
|---|---|---|---|
| hot | 活跃 | 高 | rollover、read-only、downsample、shrink、force merge、searchable snapshot |
| warm | 很少 | 较高 | allocate、migrate、shrink、force merge |
| cold | 不写 | 低 | searchable snapshot、allocate、migrate |
| frozen | 不写 | 极低 | searchable snapshot(partially mounted) |
| delete | 不适用 | 不适用 | wait_for_snapshot、delete |
阶段流转由索引年龄触发。规则:
- 当前 phase 的所有 action 完成;
- 索引年龄超过下一个 phase 的
min_age; min_age必须随 phase 增加或不变。
rollover 后,min_age 相对 rollover 时间计算,而不是索引创建时间。ILM 会把
进入 phase 的定义缓存到索引 metadata,避免策略更新把索引卡死在无法退出的状态。
ILM 轮询间隔:
http
PUT _cluster/settings
{
"persistent": {
"indices.lifecycle.poll_interval": "10m"
}
}
默认 10 分钟。即使 10 分钟时满足条件,如果某个步骤尚未安全推进,可能下一轮
才完成。
24.2 12 个 action
官方 ilm-actions 列出 12 个 action:allocate、delete、force_merge、
migrate、read_only、rollover、downsample、searchable_snapshot、
set_priority、shrink、unfollow、wait_for_snapshot。
allocate
更新节点过滤和副本数:
http
{
"allocate": {
"number_of_replicas": 0,
"include": {},
"exclude": {},
"require": { "_tier": "data_warm" }
}
}
只用于 warm/cold。源码锚点:AllocateAction.java:27。
delete
永久删除索引。通常放在 delete phase,与 wait_for_snapshot 组合。
源码锚点:DeleteAction.java:26。
force_merge
合并 segment、清除已删除文档:
http
{
"force_merge": {
"max_num_segments": 1
}
}
用于 hot/warm。只对不再写入的索引做;活跃索引 force merge 会反复制造新 segment。
源码锚点:ForceMergeAction.java:36。
migrate
把索引移到当前 phase 对应的 data tier,本质是更新
index.routing.allocation.include._tier_preference。用于 warm/cold。
源码锚点:MigrateAction.java:33。
read_only
添加写 block。用于 hot/warm/cold。源码锚点:ReadOnlyAction.java:26。
rollover
在满足条件时把写目标切到新 backing index。只用于 hot。
http
{
"rollover": {
"max_primary_shard_size": "50gb",
"max_age": "1d",
"max_docs": 1000000
}
}
普通 alias 需要设置 index.lifecycle.rollover_alias;data stream 不需要。
源码锚点:RolloverAction.java:30。
downsample
把 TSDS 索引聚合到更低时间粒度的新只读索引。可用于 hot/warm/cold。
http
{
"downsample": {
"fixed_interval": "1h"
}
}
源码锚点:DownsampleAction.java:47。
searchable_snapshot
在指定 repository 中快照索引并挂载为 searchable snapshot。hot/cold/frozen 可用;
cold 常为 fully mounted,frozen 为 partially mounted。
http
{
"searchable_snapshot": {
"snapshot_repository": "s3_repo"
}
}
源码锚点:SearchableSnapshotAction.java:52。
set_priority
设置 index.priority,影响重启后的恢复顺序。
http
{
"set_priority": { "priority": 100 }
}
用于 hot/warm/cold。源码锚点:SetPriorityAction.java:30。
shrink
把索引收缩到更少 primary shard。要求目标 shard 数能整除原 shard 数,且 source
索引只读,并先把 shard 移到单节点。
http
{
"shrink": { "number_of_shards": 1 }
}
用于 hot/warm。index.lifecycle.step.wait_time_threshold 默认 12h,
必须大于 1h。源码锚点:ShrinkAction.java:41。
unfollow
把 CCR follower index 转成普通 index。在 rollover、shrink、searchable snapshot
等 action 前自动执行。
http
{ "unfollow": {} }
源码锚点:UnfollowAction.java。
wait_for_snapshot
delete phase 中等待 SLM 策略完成,确保索引已被快照:
http
{
"wait_for_snapshot": {
"policy": "nightly-snapshots"
}
}
源码锚点:WaitForSnapshotAction.java:26。
24.3 阶段与 action 可用性
| action | hot | warm | cold | frozen | delete |
|---|---|---|---|---|---|
| allocate | yes | yes | |||
| delete | yes | ||||
| downsample | yes | yes | yes | ||
| force_merge | yes | yes | |||
| migrate | yes | yes | |||
| read_only | yes | yes | yes | ||
| rollover | yes | ||||
| searchable_snapshot | yes | yes | yes | ||
| set_priority | yes | yes | yes | ||
| shrink | yes | yes | |||
| unfollow | yes | yes | yes | yes | |
| wait_for_snapshot | yes |
24.4 策略示例
http
PUT _ilm/policy/logs-policy
{
"policy": {
"phases": {
"hot": {
"actions": {
"rollover": {
"max_primary_shard_size": "50gb",
"max_age": "1d"
},
"set_priority": { "priority": 100 }
}
},
"warm": {
"min_age": "7d",
"actions": {
"migrate": {},
"allocate": { "number_of_replicas": 1 },
"set_priority": { "priority": 50 },
"force_merge": { "max_num_segments": 1 }
}
},
"cold": {
"min_age": "30d",
"actions": {
"migrate": {},
"set_priority": { "priority": 10 },
"searchable_snapshot": { "snapshot_repository": "s3_repo" }
}
},
"delete": {
"min_age": "180d",
"actions": {
"wait_for_snapshot": { "policy": "nightly-snapshots" },
"delete": {}
}
}
}
}
}
索引模板绑定:
http
PUT _index_template/logs-template
{
"index_patterns": ["logs-app-*"],
"data_stream": {},
"template": {
"settings": {
"index.lifecycle.name": "logs-policy"
}
}
}
24.5 data stream lifecycle(DLM)
DLM 是 data stream 内建生命周期,不是 ILM 的完整替代。它更轻量:
- 自动 rollover;
- tail merging:对最新 backing index设置 merge policy,避免大量小 segment;
- retention:到期删除;
- downsampling;
- frozen transition:9.5 起可自动把旧 backing index转为 searchable snapshot。
DLM 不做 warm/cold phase 里的全部动作。一个 backing index 若同时有 ILM policy
和 DLM,由 index.lifecycle.prefer_ilm 决定:
| 值 | 管理者 |
|---|---|
| true(默认) | ILM |
| false | DLM |
9.6 起,使用未修改预装 metrics ILM policy 的时间序列 data stream 默认倾向
DLM:
text
data_streams.lifecycle.prefer_by_default.metrics_enabled 默认 true
最小生命周期:
text
data_streams.lifecycle.minimum.enabled 默认 true
没有自有 DLM 的时间序列 data stream 会被 minimum lifecycle 管理,只执行保持
健康的操作,例如 rollover 和 tail merging,不做删除或 downsampling。
关键设置:
| 设置 | 默认 |
|---|---|
data_streams.lifecycle.poll_interval |
5m |
data_streams.lifecycle.retention.default |
unset |
data_streams.lifecycle.retention.max |
unset |
data_streams.lifecycle.minimum.enabled |
true |
cluster.lifecycle.default.rollover |
max_age=auto,max_primary_shard_size=50gb,min_docs=1,max_primary_shard_docs=200000000 |
data_streams.lifecycle.target.merge.policy.merge_factor |
16 |
data_streams.lifecycle.target.merge.policy.time_series_merge_factor |
8 |
data_streams.lifecycle.target.merge.policy.floor_segment |
100MB |
data_streams.lifecycle.target.merge.policy.time_series_floor_segment |
512MB |
data_streams.lifecycle.downsampling.max_indices_in_progress |
10 |
frozen transition
DLM frozen transition 在 master 上运行,把超过 frozen_after 的 backing index
转为 frozen tier 上的 searchable snapshot。
http
PUT _data_stream/logs-app
{
"lifecycle": {
"data_retention": "180d",
"downsampling": [
{
"after": "7d",
"fixed_interval": "1h"
}
],
"frozen_after": "90d"
}
}
相关设置:
text
dlm.frozen.transition.poll_interval 默认 5m,最小 1m
dlm.frozen.transition.thread_pool.size 默认 min(2 * cpu, 100)
dlm.frozen.transition.thread_pool.queue_size 默认 min(20 * cpu, 1000)
dlm.frozen.cleanup.poll_interval 默认 1d,最小 1h
dlm.frozen_transitions.enabled 默认 true
24.6 downsampling 实战
downsampling 只适用于 TSDS。它按固定时间间隔聚合 metric 字段:
- gauge:avg/min/max/sum/value_count;
- counter:可重建 reset/last/delta;
- label:通常保留 last value;
- histogram:继续聚合直方图。
手动执行:
http
POST metrics-2026.11.14/_downsample/metrics-2026.11.14-1h
{
"fixed_interval": "1h"
}
ILM 定义见 24.2。DLM 定义用 downsampling 数组,支持按年龄做多级 downsample。
目标索引只读并继承必要 mapping。不要把 downsample 当作通用压缩;它保留的是
聚合语义,不是原始事件。
24.7 explain 与错误排查
http
GET logs-2026.11.01/_ilm/explain
GET _data_stream/logs-app/_lifecycle/explain
GET _ilm/status
GET _ilm/move/logs-2026.11.01
POST _ilm/move/logs-2026.11.01
{
"current_step": {
"phase": "warm",
"action": "migrate",
"name": "migrate"
},
"next_step": {
"phase": "warm",
"action": "complete",
"name": "complete"
}
}
健康诊断设置:
| 设置 | 默认 |
|---|---|
health.ilm.max_time_on_action |
1d |
health.ilm.max_time_on_step |
1d |
health.ilm.max_retries_per_step |
100 |
常见问题:
| 现象 | 原因 |
|---|---|
| 索引不进入下一 phase | min_age 顺序错误;前序 action 未完成;rollover 时间基准理解错 |
| 卡在 shrink | 源索引未只读、shard 未到单节点、目标 shard 数不整除 |
| 卡在 rollover | alias 缺 is_write_index 或 rollover_alias;条件未满足 |
| searchable snapshot 不挂载 | repository 不可用、license、frozen 缓存不足 |
| DLM 与 ILM 冲突 | prefer_ilm 未显式设置;模板同时绑定两者 |
| frozen transition 卡住 | repository 不可用、shared cache 没配、frozen_after 太近 |
第 25 章 安全体系(Security)
出处:
refs/docs-content/deploy-manage/users-roles/cluster-or-deployment-auth/、
refs/docs-content/deploy-manage/security/、
refs/official-docs/reference/elasticsearch/security-privileges.md、
roles.md、elasticsearch-audit-events.md源码:
x-pack/plugin/security/src/main/java/org/elasticsearch/xpack/security/
Elasticsearch 安全体系由五层组成:
text
身份认证 → 谁在请求
授权 → 请求能做什么
传输安全 → HTTP/transport 是否加密与校验
审计 → 谁、何时、从哪里、做了什么
集群间安全 → remote cluster 凭据与信任模型
生产集群至少要:transport TLS、受限用户/角色、审计日志、定期轮换凭据。
25.1 认证 realms
realm 负责把请求凭据解析为用户。官方分两类:
| 类型 | realm | 说明 |
|---|---|---|
| internal | native |
用户存放在 Elasticsearch 系统索引 |
| internal | file |
用户存放在本地文件,适合恢复账号 |
| external | ldap / active_directory |
目录服务认证与组映射 |
| external | jwt |
JWT bearer 认证 |
| external | kerberos |
Kerberos SPNEGO |
| external | oidc |
OpenID Connect |
| external | saml |
SAML 2.0 Web SSO |
| external | pki |
TLS 客户端证书认证 |
| custom | custom realm plugin | 集成自有身份系统 |
内部 realm 每种最多一个;外部 realm 可配置多个。多个 realm 组成 realm chain,
按优先级尝试。9.x 还支持 security domains,把多个 realm 组织成一个逻辑认证域。
密码、token、API key 是不同身份机制,不要混用:
| 机制 | 适用 |
|---|---|
| 用户密码 | 人或简单服务 |
| token service | 短期会话 |
| API key | 应用/服务,可绑定角色描述符 |
| service account | Fleet/Kibana 等固定外部服务 |
| PKI/JWT/SAML/OIDC | 企业身份体系 |
25.2 授权模型
角色包含四类权限:
| 权限类别 | 作用 |
|---|---|
| cluster | 集群操作,如 monitor、manage、manage_security、create_snapshot |
| indices | 索引/数据流操作,如 read、write、create_index、delete_index |
| run_as | 允许以指定用户身份发起请求 |
| application | 应用自有权限模型,不直接授权 Elasticsearch 操作 |
角色示例:
http
POST _security/role/readonly_logs
{
"cluster": ["monitor"],
"indices": [
{
"names": ["logs-app-*"],
"privileges": ["read", "view_index_metadata"],
"field_security": {
"grant": ["@timestamp", "host.name", "message"],
"except": ["user.email"]
},
"query": "{ \"term\": { \"tenant\": \"team-a\" } }"
}
]
}
索引权限要点:
read是只读数据权限;view_index_metadata允许查看 mappings/settings;write包括 index/update/delete,不等于允许显式 mapping 更新;- 显式 mapping 更新用
manage,自动 mapping 更新用auto_configure; - DLS 用 role 中索引条目的
query; - FLS 用
field_security.grant/except; run_as只是允许 impersonation,还要求目标请求拥有相应权限。
25.3 API keys
API key 用于服务认证,比长期用户密码更适合应用。类型:
| 类型 | 用途 |
|---|---|
| personal/user API key | 外部服务代表用户访问 Elasticsearch/Kibana |
| cross-cluster API key | 远程集群访问,用于 CCS/CCR |
| managed API key | Kibana 后台任务使用 |
创建:
http
POST _security/api_key
{
"name": "logs-reader",
"expiration": "30d",
"role_descriptors": {
"logs_reader": {
"cluster": ["monitor"],
"indices": [
{ "names": ["logs-app-*"], "privileges": ["read"] }
]
}
}
}
要点:
- 创建 API key 需要集群权限
manage_api_key或manage_own_api_key; grant_api_key允许代表其他用户创建 key;- cross-cluster API key 需要 Enterprise license 和
manage_security; - key 应设置过期时间,并按服务分实例分发;
- 泄露后立即 invalidate,并审计创建来源。
源码锚点:authc/ApiKeyService.java:172。
25.4 service accounts
service account 是预定义服务身份, privileges 固定、不能认证个人用户。
常见内置账号:
text
elastic/fleet-server
elastic/kibana
服务账号必须使用 service token 认证,不能 basic auth:
shell
curl -H "Authorization: Bearer AAEAAWVsYXN0aWM..." \
https://es:9200/_security/_authenticate
推荐用 REST API 创建 token,存入 .security 索引并可随快照备份;CLI 适合
ECE/ECK 等编排系统。service token 不过期,不再使用时必须显式删除。
源码锚点:authc/service/ServiceAccountService.java:51。
25.5 TLS:transport 与 HTTP
transport TLS
transport 层是节点间通信,必须 mutual TLS。推荐为集群生成专用 CA:
shell
bin/elasticsearch-certutil ca
bin/elasticsearch-certutil cert --ca elastic-stack-ca.p12
每个节点配置:
yaml
xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.verification_mode: certificate
xpack.security.transport.ssl.client_authentication: required
xpack.security.transport.ssl.keystore.path: elastic-certificates.p12
xpack.security.truststore.path: elastic-certificates.p12
密码放入 keystore:
shell
bin/elasticsearch-keystore add xpack.security.transport.ssl.keystore.secure_password
bin/elasticsearch-keystore add xpack.security.transport.ssl.truststore.secure_password
使用同一个 keystore/truststore 文件作为"集群成员密钥"时,verification_mode 为
certificate。若使用 per-host 证书并做 hostname verification,则用 full。
生产模式集群未启用 transport TLS 不会启动。
HTTP TLS
HTTP 层保护客户端与集群:
yaml
xpack.security.http.ssl.enabled: true
xpack.security.http.ssl.keystore.path: http.p12
HTTP TLS 不是节点间信任的替代;两者作用不同。transport TLS 控制谁能成为集群
成员,HTTP TLS 控制客户端通道。
25.6 审计
审计不是访问日志,也不是应用日志;它记录安全决策与安全配置变化。
常见 event type:
| event | 说明 |
|---|---|
authentication_success |
认证成功 |
authentication_failed |
凭据无法匹配用户 |
anonymous_access_denied |
缺少凭据 |
access_granted |
授权通过,通常非系统用户 |
access_denied |
授权失败 |
run_as_granted/denied |
impersonation 结果 |
connection_granted/denied |
IP filter 结果 |
tampered_request |
请求签名/完整性失败 |
security_config_change |
用户、角色、API key、service token 等配置变化 |
审计事件带 request.id,可用于把一次客户端请求跨节点关联。security_config_change
默认不含 actor 字段;需要时开启:
yaml
xpack.security.audit.logfile.events.emit_security_config_change_actor: true
不要无差别开启 system_access_granted,否则内部系统用户事件会淹没日志。
源码锚点:audit/AuditTrailService.java:30。
25.7 跨集群安全
remote cluster 有两种安全模型:
| 模型 | 适用 | 特点 |
|---|---|---|
| API key | 8.14+,推荐 | 双方可细粒度授权,本地/远程职责清晰 |
| TLS certificate | 9.0 deprecated | 适合同一安全域;本地 superuser 对远程有全局读 |
连接模式:
| 模式 | 配置 |
|---|---|
| sniff | cluster.remote.<alias>.seeds,本地节点直连 remote gateway |
| proxy | cluster.remote.<alias>.mode: proxy 和 proxy_address,适合受限网络 |
使用 API key 模型时,remote cluster 需要创建 cross-cluster API key,本地 cluster
用它访问远程索引。使用 CCR 时,本地所有 master-eligible 节点还需要
remote_cluster_client 角色,并且至少有一个 data 节点带该角色。
9.6+ cross-cluster API key 支持 strong identity verification,通过本地签名证书
DN pattern 限制身份。
源码锚点:transport/RemoteClusterService.java:542-552。
25.8 排障
http
GET _security/_authenticate
GET _security/user/<user>
GET _security/role/<role>
GET _security/_query/api_key
GET _cluster/settings?include_defaults=true&filter_path=*.xpack.security*
| 现象 | 先查 |
|---|---|
authentication_failed |
realm chain、凭据、_security/_authenticate |
access_denied |
角色 privileges、索引 pattern、DLS query |
| HTTP 429/503 | 触发限流、cluster state encryption 未配置、系统索引不可用 |
| 新节点无法加入 | transport TLS、CA、cluster.name、路径/权限 |
| API key 请求失败 | key 是否过期/失效、role descriptor 是否包含权限 |
| service account 失败 | token 类型、是否用 bearer、token 是否删除 |
| remote cluster 认证失败 | API key 模型、remote_cluster_client、证书 DN pattern |
第 26 章 性能与可观测性
出处:
refs/official-docs/reference/elasticsearch/configuration-reference/:
thread-pool-settings.md、circuit-breaker-settings.md、
node-query-cache-settings.md、field-data-cache-settings.md、
shard-request-cache-settings.md、indexing-pressure-settings.md、
health-diagnostic-settings.md;index-settings/slow-log.md、store.md、
preloading-data-into-file-system-cache.md;rest-apis/search-profile.md源码:
server/src/main/java/org/elasticsearch/threadpool/、
indices/、index/IndexingPressure.java、search/profile/、health/
性能问题先看资源画像,再改设置。一个节点同时面对 CPU、heap、磁盘 IO、
网络、OS page cache 和 shard 数量压力。盲目调大线程池、cache、断路器
只会把失败从拒绝请求变成 OOM。
26.1 线程池与队列
线程池控制"允许多少并发工作";queue 控制"忙不过来时缓存多少工作"。
队列满通常导致请求拒绝,这是保护而不是错误。
| pool | 类型 | 关键默认 |
|---|---|---|
search |
fixed | size int(processors*3/2)+1;9.0 起 queue 1000 * size |
search_coordination |
fixed | size processors/2;queue 1000 |
get |
fixed | size int(processors*3/2)+1;queue 1000 |
write |
fixed | size processors;queue max(10000, processors*750);最大 1 + processors |
write_coordination |
fixed,9.1+ | size processors;queue 10000 |
refresh |
scaling | max min(10, processors/2) |
flush |
scaling | max min(5, processors/2) |
merge |
scaling | max processors |
force_merge |
fixed | size max(1, processors/8);队列无界 |
snapshot |
scaling | 大节点 max 10;小节点更低 |
esql_worker |
fixed | size int(processors*3/2)+1;queue 1000 |
线程池设置是 static,需要改配置文件并重启。示例:
yaml
thread_pool:
write:
size: 30
queue_size: 1000
node.processors 决定自动计算。不要为了压测虚拟 CPU 而盲目覆盖;多进程
共享宿主机时应按 CPU 配额设置比例。
排障信号:
| 现象 | 说明 |
|---|---|
| rejected | 队列满;提高并发或收窄请求 |
| search slow | CPU、磁盘、高基数聚合、shard 过多 |
| write rejected | bulk 太大、ingest 太重、replica 复制慢、indexing pressure |
| merge 慢 | refresh 太频繁、大 segment 合并、磁盘 IO |
26.2 断路器
断路器不是缓存,而是内存保护。达到限制时请求失败,节点继续存活。
| breaker | 默认 | 作用 |
|---|---|---|
| parent | use_real_memory=true 时 95% heap |
全局总限制 |
| fielddata | 40% heap | 加载 fielddata/global ordinals |
| request | 60% heap | 聚合、ES |
| in-flight requests | 100% heap,受 parent 约束 | 请求体与结构化对象 |
| script compilation | 150/5m |
限制唯一脚本编译 |
| regex | limited |
限制 Painless regex 复杂度 |
| EQL sequence | 50% heap | EQL sequence 内存 |
| model inference | 50% heap | 模型推理内存 |
| synonym | 使用 parent | 9.4+ 同义词构建时检查 real heap |
ES|QL 没有专属断路器;它共用 request breaker。
源码锚点:indices/breaker/CircuitBreakerService.java:18。
调整原则:
- 先找触发者,不要先调限制;
indices.breaker.total.use_real_memory保持 true;- fielddata/cache 大小应小于 fielddata breaker;
- regex 保持
limited; - 高堆使用率先降数据量/shard 数,再考虑 JVM。
26.3 缓存三件套
node query cache
缓存 filter context 的查询结果,每节点共享。LRU;只缓存至少 10,000 docs 且
至少占 shard 总文档 3% 的 segment;segment merge 会失效。
yaml
indices.queries.cache.size: 10%
索引级:
http
PUT logs-2026.11.01/_settings
{
"index.queries.cache.enabled": true
}
源码锚点:IndicesQueryCache.java:55,indices.queries.cache.size。
field data cache
保存 fielddata 和 global ordinals。默认无上限,由 fielddata breaker 控制。
若显式设置:
yaml
indices.fielddata.cache.size: 38%
必须小于 fielddata breaker。更好的方案是:不要给 text 字段开 fielddata;
聚合用 keyword 子字段;用 eager global ordinals 只对确有需要的热字段。
源码锚点:
text
indices/fielddata/cache/IndicesFieldDataCache.java:45
IndicesFieldDataCache.java:50
shard request cache
缓存 shard 级请求结果,默认 1% heap。索引 refresh 时自动失效。
yaml
indices.requests.cache.size: 1%
请求级 request_cache=true 只适合可重放、确定性请求;不要用于带随机性、
评分会变化的查询。
源码锚点:IndicesRequestCache.java:55,indices.requests.cache.size。
26.4 索引性能:refresh、translog、merge、indexing pressure
refresh
refresh 让新写入可搜索,不等于 flush。
| 参数 | 值 |
|---|---|
index.refresh_interval 默认 |
stack 1s;serverless 5s |
| 写入 API refresh | false 默认;wait_for;true |
index.search.idle.after |
30s |
index.max_refresh_listeners |
1000 |
高写入负载常见做法:
http
PUT logs-2026.11.01/_settings
{
"index.refresh_interval": "30s"
}
不要在业务流中反复 refresh=true;它会创建小 segment,增加 search 和 merge
成本。wait_for 更好,但也要成批放入 bulk。
源码锚点:IndexSettings.java:337 定义 refresh interval;
refresh-parameter.md 给出三种 refresh 语义。
translog 与 flush
translog 提供 durability;flush 把 translog fsync 并创建可恢复点。高频 refresh
不会替代 flush。大 bulk、高并发副本和慢磁盘都会放大 flush/fsync。
merge
merge 是 Lucene 后台行为,与 refresh/flush 并行但共享磁盘/CPU。不要频繁
force merge 活跃索引。force merge 主要用于只读索引、快照前、或 archive 数据。
indexing pressure
索引压力跟踪 coordinating、primary、replica 三个阶段的在途字节。
yaml
indexing_pressure.memory.limit: 10%
默认 10% heap。coordinating/primary 超限拒绝新请求;replica 阶段达到
1.5 倍限制时拒绝 replica work,从而优先保护已有 replica。
源码锚点:IndexingPressure.java:28、:31。
26.5 search profile
http
POST logs-2026.11.01/_search
{
"profile": true,
"size": 0,
"query": {
"bool": {
"filter": [{ "range": { "@timestamp": { "gte": "now-1d" } } }]
}
},
"aggs": {
"by_host": { "terms": { "field": "host.name", "size": 20 } }
}
}
profile 输出 query tree、rewrite time、collector tree、aggregation time。
它本身有开销,用于定位单个请求,不要长期开启。
26.6 slow log 与 query log
slow log 分 search 和 indexing 两类。search slow log 按 shard 记录;indexing
slow log 按文档记录。
http
PUT logs-2026.11.01/_settings
{
"index.search.slowlog.threshold.query.warn": "10s",
"index.search.slowlog.threshold.query.info": "5s",
"index.search.slowlog.threshold.fetch.warn": "1s",
"index.indexing.slowlog.threshold.index.warn": "10s",
"index.indexing.slowlog.source": "3000",
"index.search.slowlog.include.user": true
}
9.4 preview 引入统一 query logging,覆盖 Query DSL、ES|QL、EQL、SQL,并记录
端到端耗时。官方建议搜索类慢查询逐步迁移到 query logging;indexing slow log
仍是唯一选择。
26.7 health API 与 diagnostic settings
Health API 汇总 disk、master history、shard availability、ILM、DLM、
shard capacity 等指标。
http
GET _health_report
GET _cluster/health
GET _cluster/state
GET _nodes/stats
GET _cat/nodes?v&h=name,heap.percent,ram.percent,cpu,load_1m,disk.used_percent,node.role
关键诊断设置:
| 设置 | 默认 |
|---|---|
health.node.enabled |
dynamic |
health.master_history.has_master_lookup_timeframe |
30s |
master_history.max_age |
30m |
health.master_history.identity_changes_threshold |
4 |
health.master_history.no_master_transitions_threshold |
4 |
health.reporting.local.monitor.interval |
dynamic |
health.ilm.max_time_on_action |
1d |
health.ilm.max_time_on_step |
1d |
health.ilm.max_retries_per_step |
100 |
health.periodic_logger.enabled |
false |
health.periodic_logger.poll_interval |
60s |
health.shard_capacity.unhealthy_threshold.yellow |
10 |
health.shard_capacity.unhealthy_threshold.red |
5 |
26.8 存储与 OS cache
默认 store type 是 hybridfs:term dictionary、norms、doc values 等随机访问
文件用 mmap,其他文件用 NIO。Windows 或受限环境可禁用 mmap:
yaml
node.store.allow_mmap: false
index.store.preload 告诉 OS 在打开索引时预热文件。默认空数组。
http
PUT hot-index
{
"settings": {
"index.store.preload": ["nvd", "dvd", "tim", "doc", "dim"]
}
}
扩展名含义:
| 扩展 | 内容 |
|---|---|
nvd |
norms |
dvd |
doc values |
tim |
terms dictionary |
doc |
postings |
dim |
points |
不要用 ["*"] 盲目预热全量索引。索引大于宿主内存时,merge/reopen 会冲刷
page cache,反而变慢。向量索引有自己的 preload 文件集合,参考向量搜索文档。
源码/文档锚点:index-settings/preloading-data-into-file-system-cache.md;
index-settings/store.md。
26.9 性能检查表
索引侧
| 检查 | 目标 |
|---|---|
| shard 数 | 每 shard 10~50GB 附近,避免过小 shard |
| refresh_interval | 高写入负载 30s 或更长 |
| bulk size | 5~15MB 起测,避免单请求数百 MB |
| mapping | 聚合字段有 doc values/keyword 子字段 |
| mapping | 避免 dynamic text + 无界 mapping |
| codec | 归档数据可测 best_compression |
| force merge | 只在只读索引/快照前 |
查询侧
| 检查 | 目标 |
|---|---|
| 过滤条件 | 尽量 filter context,尤其时间范围 |
| fields | _source 只取需要字段 |
| pagination | 大翻页用 search_after/PIT,不要拉大 from |
| aggregation | 控制 size/shard_size/max_buckets |
| profile | 单请求定位后再关闭 |
| cache | 确定性 filter/request 才启用 |
运维侧
| 检查 | 目标 |
|---|---|
| heap GC | 慢 GC 是第一信号 |
| disk IO | merge、flush、search 共享磁盘 |
| memory pressure | fielddata、聚合、ES |
| node role | master/data/ingest 不混载 |
| thread pool | rejected 不是调大队列的理由 |
| slow log | 按阶段定位 query/fetch/index |
系列导航
- Elasticsearch 9.x 从入门到精通(1/7):初识 Elasticsearch(第 01~04 章)
- Elasticsearch 9.x 从入门到精通(2/7):数据建模与索引管理(第 05~08 章)
- Elasticsearch 9.x 从入门到精通(3/7):检索与查询(第 09~16 章)
- Elasticsearch 9.x 从入门到精通(4/7):聚合分析与文本分析(第 17~20 章)
- Elasticsearch 9.x 从入门到精通(5/7):集群、分布式与运维(第 21~26 章)(本篇)
- Elasticsearch 9.x 从入门到精通(6/7):生态与扩展(第 27~30 章)
- Elasticsearch 9.x 从入门到精通(7/7):源码内幕与贡献(第 31~33 章)