集群配置 #

本文介绍通过集群设置 API 管理 Easysearch 集群级别配置的方式，包括动态设置的查看、修改、重置，以及可通过 API 调整的全部动态配置项参考。

节点级别的静态配置（需要写在 easysearch.yml 中、重启后生效的配置）请参见节点配置。

集群设置 API #

大多数集群级调优参数都可以通过集群设置 API 在运行时更改，无需重启节点。

查看设置 #

# 查看所有设置（包含默认值）
GET _cluster/settings?include_defaults=true

# 仅查看用户自定义设置
GET _cluster/settings

设置优先级 #

集群设置 API 中存在三类设置：持久（Persistent）、临时（Transient）和默认（Default）。

优先级从高到低：

Transient 设置 — 临时，集群重启后丢失
Persistent 设置 — 持久，跨重启保留
配置文件 easysearch.yml
默认值

推荐做法：节点相关配置放 easysearch.yml，集群范围的调优通过 API 以 persistent 方式修改，避免每个节点单独改配置文件。

修改设置 #

// 持久化修改（推荐用于集群调优）
PUT /_cluster/settings
{
  "persistent": {
    "action.auto_create_index": false
  }
}

// 临时修改（适合调试，重启后失效）
PUT /_cluster/settings
{
  "transient": {
    "logger.org.easysearch.discovery": "DEBUG"
  }
}

重置设置 #

将配置值设为 null 即可重置为默认值：

PUT /_cluster/settings
{
  "persistent": {
    "action.auto_create_index": null
  }
}

动态配置项参考 #

以下配置项均可通过 PUT /_cluster/settings 在线修改，无需重启节点。

索引行为 #

参数	默认值	说明
`action.auto_create_index`	`true`	是否允许自动创建索引。可设为 `false` 禁止，或指定允许的模式如 `+logs-,-`
`action.destructive_requires_name`	`false`	是否要求删除索引时必须指定具体名称，禁止通配符和 `_all`。生产环境建议设为 `true`

索引默认值 #

以下为集群级别的索引默认值，作用于新创建的索引。部分参数也可以通过 PUT /<index>/_settings 在索引级别动态覆盖（标注"可动态修改"的）。

参数	默认值	说明
`index.number_of_shards`	`1`	新建索引的默认主分片数。注意：索引创建后主分片数不可修改
`index.number_of_replicas`	`1`	新建索引的默认副本数（可动态修改）
`index.refresh_interval`	`1s`	索引刷新间隔（文档写入后多久可被搜索到）。设为 `-1` 可禁用自动刷新
`index.translog.durability`	`request`	Translog 刷写策略。`request`（每次请求同步刷写，最安全）或 `async`（异步刷写，更快但有丢失风险）
`index.translog.flush_threshold_size`	`512mb`	Translog 累积到此大小触发 flush 到 Lucene
`index.max_result_window`	`10000`	搜索结果窗口上限（`from + size` 的最大值）。过大会占用大量堆内存

分片分配 #

参数	默认值	说明
`cluster.routing.allocation.enable`	`all`	分片分配开关。可选：`all`、`primaries`（仅主分片）、`new_primaries`（仅新主分片）、`none`（禁止）。滚动重启时设为 `primaries` 或 `none`
`cluster.routing.allocation.node_concurrent_recoveries`	`2`	单节点并发恢复分片数
`cluster.routing.allocation.node_concurrent_incoming_recoveries`	`2`	单节点并发接收恢复分片数
`cluster.routing.allocation.node_concurrent_outgoing_recoveries`	`2`	单节点并发发送恢复分片数
`cluster.max_shards_per_node`	`1000`	单节点最大分片数（所有索引分片总和）

分片分配感知 #

参数	默认值	说明
`cluster.routing.allocation.awareness.attributes`	—	分片分配感知属性。配合 `node.attr.*` 使用，确保主分片和副本分布在不同区域。例：`zone`
`cluster.routing.allocation.awareness.force.zone.values`	—	强制感知属性值列表。确保即使部分区域不可用也不会将所有副本分配到同一区域。例：`["zone-a", "zone-b"]`

磁盘水位线 #

参数	默认值	说明
`cluster.routing.allocation.disk.threshold_enabled`	`true`	是否启用基于磁盘使用量的分片分配
`cluster.routing.allocation.disk.watermark.low`	`85%`	低水位线：磁盘使用超过此阈值后，不再向该节点分配新分片（已有分片保留不动）
`cluster.routing.allocation.disk.watermark.high`	`90%`	高水位线：超过后不再分配新分片，并开始将已有分片迁移到其他节点
`cluster.routing.allocation.disk.watermark.flood_stage`	`95%`	洪水位线：超过后相关索引变为只读
`cluster.routing.allocation.disk.reroute_interval`	`60s`	磁盘水位线检测间隔（多久检查一次并进行重新分配）
`cluster.routing.allocation.disk.include_relocations`	`true`	是否在磁盘水位线计算中包含正在进行中的副本搬运（已弃用）

示例：调整磁盘水位线

PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.disk.watermark.low": "80%",
    "cluster.routing.allocation.disk.watermark.high": "88%",
    "cluster.routing.allocation.disk.watermark.flood_stage": "93%"
  }
}

分片分配过滤 #

用于节点退役前迁走所有分片：

参数	说明
`cluster.routing.allocation.exclude._name`	按节点名称排除
`cluster.routing.allocation.exclude._ip`	按 IP 地址排除
`cluster.routing.allocation.exclude._host`	按主机名排除
`cluster.routing.allocation.include._name`	仅允许分配到指定节点
`cluster.routing.allocation.require._name`	要求必须分配到指定节点

示例：下线节点前迁移分片

PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.exclude._name": "node-3"
  }
}

分片恢复限流 #

参数	默认值	说明
`indices.recovery.max_bytes_per_sec`	`40mb`	分片恢复时每个节点的最大传输速率。SSD 可适当调高
`indices.store.throttle.max_bytes_per_sec`	`10mb`	段合并限流。SSD 环境可设为 `200mb` 以上

示例：提高恢复速率（SSD 环境）

PUT /_cluster/settings
{
  "persistent": {
    "indices.recovery.max_bytes_per_sec": "200mb"
  }
}

分片延迟分配 #

参数	默认值	说明
`index.unassigned.node_left.delayed_timeout`	`1m`	节点离开后，推迟分片重新分配的时间。避免因短暂网络抖动导致不必要的数据搬运。可通过索引设置 API 修改

内存与缓存 #

参数	默认值	说明
`indices.fielddata.cache.size`	无限制	字段数据缓存上限（百分比或绝对值），超过阈值时触发回收

断路器 #

断路器防止操作导致 OutOfMemoryError：

参数	默认值	说明
`indices.breaker.total.limit`	`70%`	总断路器上限（所有断路器的聚合限制）
`indices.breaker.fielddata.limit`	`40%`	字段数据断路器（加载 fielddata 到内存时触发）
`indices.breaker.request.limit`	`60%`	请求断路器（单次请求中聚合等数据结构）
`network.breaker.inflight_requests.limit`	`100%`	传输中请求断路器（HTTP/Transport 层正在进行的请求）

示例：调整断路器

PUT /_cluster/settings
{
  "persistent": {
    "indices.breaker.total.limit": "75%",
    "indices.breaker.fielddata.limit": "45%"
  }
}

跨集群搜索 #

参数	默认值	说明
`cluster.remote.<alias>.seeds`	—	远程集群的种子节点地址列表
`cluster.remote.<alias>.transport.compress`	`false`	是否压缩跨集群通信
`cluster.remote.<alias>.skip_unavailable`	`false`	远程集群不可用时是否跳过（而非报错）

示例：添加远程集群

PUT /_cluster/settings
{
  "persistent": {
    "cluster.remote.cluster_b.seeds": ["192.168.2.10:9300", "192.168.2.11:9300"],
    "cluster.remote.cluster_b.transport.compress": true,
    "cluster.remote.cluster_b.skip_unavailable": true
  }
}

日志级别 #

可在不重启节点的情况下动态调整任意 Logger 的级别：

// 开启 DEBUG 日志
PUT /_cluster/settings
{
  "transient": {
    "logger.org.easysearch.discovery": "DEBUG"
  }
}

// 恢复默认级别
PUT /_cluster/settings
{
  "transient": {
    "logger.org.easysearch.discovery": null
  }
}

慢日志阈值 #

慢日志可以按索引设置阈值，帮助发现性能问题：

PUT /my-index/_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.threshold.index.info": "5s"
}