Elasticsearch 9.x 从入门到精通(5/7):集群、分布式与运维

系列文章 :《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 票,集群反而无法推进。

生产建议:

  1. HA 集群至少 3 个 master-eligible 节点,其中至少 2 个不是 voting_only;
  2. master 节点使用低延迟、持久可靠的本地磁盘;
  3. 不要用 "2 主节点 + 1 热备但不开 master"作为 HA 方案;
  4. 增删 master-eligible 节点要等待 voting configuration 调整完成;
  5. 不确定时用 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 后还有索引元数据,节点会拒绝启动。官方给出的路径是:

  1. 先用 allocation filter 迁走 shard;
  2. 关闭节点并改角色;
  3. 用空数据路径启动全新节点,或使用 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 按优先级恢复:

  1. index.priority 高者优先;
  2. 创建日期新者优先;
  3. 索引名高者优先。
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

阶段流转由索引年龄触发。规则:

  1. 当前 phase 的所有 action 完成;
  2. 索引年龄超过下一个 phase 的 min_age;
  3. 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。

调整原则:

  1. 先找触发者,不要先调限制;
  2. indices.breaker.total.use_real_memory 保持 true;
  3. fielddata/cache 大小应小于 fielddata breaker;
  4. regex 保持 limited;
  5. 高堆使用率先降数据量/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。

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 章)
相关推荐
进击的荆棘32 分钟前
Linux网络——网络基础概念
linux·运维·服务器·网络
筑梦之人35 分钟前
Elasticsearch 9.x 从入门到精通(4/7):聚合分析与文本分析
大数据·elasticsearch·jenkins
tianyuanwo38 分钟前
QEMU 虚拟化入门:从“软件模拟一台电脑”到 KVM 时代的基础设施组件
运维·qemu·虚拟化
.YM.Z1 小时前
从操作系统进入Linux进程概念及进程状态
linux·运维·服务器
Decay__14 小时前
VMware 安装 SQL Server 双节点 AlwaysOn 可用性组教程 —— WSFC、AG 与侦听器完整部署(系列核心篇)
运维·数据库·sql·mysql·架构
测试界的小码农14 小时前
【Linux 命令实战(06):Linux 文件权限管理,掌握 chmod、chown、chgrp】
linux·运维·服务器
陈希12315 小时前
负载均衡与高可用:LVS、HAProxy、Keepalived 实战
运维·负载均衡·lvs
SQL7719 小时前
IT运维发展史,一部宏伟史诗
运维·运维发展史
分布式存储与RustFS20 小时前
Terraform 状态文件老在本地丢、并发还撞锁:把 state 锁进 RustFS
运维·云原生·开源·对象存储·分布式存储·s3·性能基准