---
title: "更新集群设置"
date: 2026-01-22
lastmod: 2026-01-22
description: "更新集群的设置配置，包括持久化设置和临时设置"
tags: ["集群管理", "配置管理", "集群设置"]
summary: "更新集群的设置配置，支持持久化设置和临时设置两种类型。
API #  PUT /_cluster/settings GET /_cluster/settings API 的作用 #  该 API 用于更新或获取集群的设置配置。Easysearch 支持两种类型的设置：
   设置类型 描述 持久性     persistent（持久化设置） 在集群重启后仍然保持设置的值 持久   transient（临时设置） 只在当前集群会话中有效，集群重启后恢复默认值 临时    常见集群设置 #     设置路径 描述     cluster.routing.allocation.enable 控制分片分配   cluster.routing.allocation.include._attr 包含具有特定属性的节点   cluster.routing.allocation.exclude._attr 排除具有特定属性的节点   cluster.routing.allocation.awareness.attributes 分片感知属性   cluster.max_shards_per_node 每个节点的最大分片数   indices.memory.index_buffer_size 索引缓冲区大小   cluster."
---


更新集群的设置配置，支持持久化设置和临时设置两种类型。

## API

```
PUT /_cluster/settings
GET /_cluster/settings
```

## API 的作用

该 API 用于更新或获取集群的设置配置。Easysearch 支持两种类型的设置：

| 设置类型 | 描述 | 持久性 |
|----------|------|--------|
| `persistent`（持久化设置） | 在集群重启后仍然保持设置的值 | 持久 |
| `transient`（临时设置） | 只在当前集群会话中有效，集群重启后恢复默认值 | 临时 |

### 常见集群设置

| 设置路径 | 描述 |
|----------|------|
| `cluster.routing.allocation.enable` | 控制分片分配 |
| `cluster.routing.allocation.include._attr` | 包含具有特定属性的节点 |
| `cluster.routing.allocation.exclude._attr` | 排除具有特定属性的节点 |
| `cluster.routing.allocation.awareness.attributes` | 分片感知属性 |
| `cluster.max_shards_per_node` | 每个节点的最大分片数 |
| `indices.memory.index_buffer_size` | 索引缓冲区大小 |
| `cluster.routing.rebalance.enable` | 控制分片重平衡 |
| `cluster.blocks.read_only` | 将集群设为只读 |

## API 的参数

### Query String 参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `timeout` | 时间值 | 否 | 默认超时 | 操作超时时间 |
| `master_timeout` | 时间值 | 否 | 默认超时 | 连接到主节点的超时时间 |
| `flat_settings` | 布尔值 | 否 | false | 是否以扁平格式返回设置（仅对 GET 有效） |

### 请求体参数（PUT/POST 请求时使用）

| 参数 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `persistent` | 对象 | 否 | 包含要更新的持久化设置，集群重启后仍然保持 |
| `transient` | 对象 | 否 | 包含要更新的临时设置，集群重启后恢复默认值 |

> **注意**：请求体必须至少包含 `persistent` 或 `transient` 中的一个，否则会返回错误。

## 示例

### 更新持久化设置

```bash
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "all",
    "cluster.max_shards_per_node": 1000
  }
}
```

### 更新临时设置

```bash
PUT /_cluster/settings
{
  "transient": {
    "cluster.routing.allocation.enable": "primaries_only"
  }
}
```

### 同时更新两种设置

```bash
PUT /_cluster/settings
{
  "persistent": {
    "indices.memory.index_buffer_size": "30%"
  },
  "transient": {
    "cluster.routing.allocation.enable": "all"
  }
}
```

**响应示例：**

```json
{
  "acknowledged": true,
  "persistent": {
    "indices.memory.index_buffer_size": "30%"
  },
  "transient": {
    "cluster.routing.allocation.enable": "all"
  }
}
```

### 禁用分片分配（维护模式）

```bash
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "none"
  }
}
```

### 重新启用分片分配

```bash
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.enable": "all"
  }
}
```

### 排除特定节点不分配新分片

```bash
PUT /_cluster/settings
{
  "persistent": {
    "cluster.routing.allocation.exclude._host": "maintenance-server"
  }
}
```

### 设置集群为只读模式

```bash
PUT /_cluster/settings
{
  "persistent": {
    "cluster.blocks.read_only": true
  }
}
```

### 解除只读模式

```bash
PUT /_cluster/settings
{
  "persistent": {
    "cluster.blocks.read_only": false
  }
}
```

### 设置超时时间

```bash
PUT /_cluster/settings?master_timeout=10s
{
  "transient": {
    "cluster.routing.rebalance.enable": "all"
  }
}
```

### 删除设置（设置为 null）

```bash
PUT /_cluster/settings
{
  "transient": {
    "cluster.routing.allocation.enable": null
  }
}
```

### 获取集群设置（GET）

```bash
GET /_cluster/settings
```

**响应示例：**

```json
{
  "persistent": {
    "cluster.routing.allocation.enable": "all",
    "cluster.max_shards_per_node": "1000"
  },
  "transient": {}
}
```

### 以扁平格式获取设置

```bash
GET /_cluster/settings?flat_settings=true
```

**响应示例：**

```json
{
  "persistent": {
    "cluster.routing.allocation.enable": "all",
    "cluster.max_shards_per_node": "1000"
  }
}
```

## 分片分配控制选项

| 值 | 描述 |
|----|------|
| `all` | 允许所有分片分配 |
| `primaries` | 只允许主分片分配 |
| `new_primaries` | 只允许新创建的主分片分配 |
| `none` | 禁止所有分片分配 |
| `replicas` | 只允许副本分片分配 |