---
title: "集群只读块配置"
date: 2026-01-05
lastmod: 2026-01-05
description: "控制集群只读块状态的配置项说明"
tags: ["集群配置", "访问控制", "数据保护"]
summary: "配置项作用 #  cluster.blocks.read_only 配置项控制整个集群的只读状态。当启用此配置后，集群中的所有索引将禁止写入操作和元数据修改操作，仅允许读取操作。此配置通常用于磁盘空间不足时自动保护数据，或手动设置以防止数据修改。
配置项类型 #  该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。
默认值 #  false（不启用只读块） 是否必需 #  可选配置项（有默认值）
取值范围 #  true - 启用集群只读块 false - 禁用集群只读块 配置格式 #  # 默认配置（正常读写） cluster.blocks.read_only: false # 启用只读模式 cluster.blocks.read_only: true # 恢复正常读写 cluster.blocks.read_only: false 相关配置项 #     配置项 默认值 说明     cluster.blocks.read_only false 集群只读块   cluster.blocks.read_only_allow_delete false 只读允许删除块   cluster.routing.allocation.disk.watermark 85%/90%/95% 磁盘水位线    工作原理 #  集群只读块机制："
---


## 配置项作用

`cluster.blocks.read_only` 配置项控制整个集群的只读状态。当启用此配置后，集群中的所有索引将禁止写入操作和元数据修改操作，仅允许读取操作。此配置通常用于磁盘空间不足时自动保护数据，或手动设置以防止数据修改。

## 配置项类型

该配置项为**动态配置**，可以在运行时通过集群设置 API 进行修改。

## 默认值

```
false（不启用只读块）
```

## 是否必需

**可选配置项**（有默认值）

## 取值范围

```
true  - 启用集群只读块
false - 禁用集群只读块
```

## 配置格式

```yaml
# 默认配置（正常读写）
cluster.blocks.read_only: false

# 启用只读模式
cluster.blocks.read_only: true

# 恢复正常读写
cluster.blocks.read_only: false
```

## 相关配置项

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `cluster.blocks.read_only` | false | 集群只读块 |
| `cluster.blocks.read_only_allow_delete` | false | 只读允许删除块 |
| `cluster.routing.allocation.disk.watermark` | 85%/90%/95% | 磁盘水位线 |

## 工作原理

集群只读块机制：

```
┌─────────────────────────────────────────────────────────────────┐
│                    集群只读块控制                                 │
└─────────────────────────────────────────────────────────────────┘

请求到达
    │
    ▼
检查 read_only 状态
    │
    ├── false（正常模式）
    │   │
    │   ├── 允许所有操作
    │   │   - 读取操作 ✓
    │   │   - 写入操作 ✓
    │   │   - 删除操作 ✓
    │   │   - 元数据修改 ✓
    │   │
    │   └── 正常处理
    │
    └── true（只读模式）
        │
        ├── 允许的操作
        │   - 读取操作 ✓
        │   - 查询请求 ✓
        │
        └── 拒绝的操作
            - 写入操作 ✗
            - 删除操作 ✗
            - 索引创建 ✗
            - 元数据修改 ✗
            │
            └── 返回 FORBIDDEN 错误
```

## 触发场景

```
自动触发场景:

1. 磁盘水位线触发
   - 磁盘使用率超过 flood_stage 水位线
   - 默认 95%
   - 自动设置 read_only = true
   - 防止磁盘填满导致数据损坏

2. 磁盘空间恢复
   - 磁盘使用率低于高水位线
   - 默认 90%
   - 需要手动设置 read_only = false

手动设置场景:

1. 维护模式
   - 防止数据修改
   - 执行只读查询

2. 数据迁移
   - 保护源数据
   - 防止意外写入

3. 安全保护
   - 临时禁用写入
   - 保护关键数据
```

## 使用场景

### 1. 默认配置（正常模式）

```yaml
cluster.blocks.read_only: false
```

**适用场景：**
- 所有正常运行的集群
- 需要读写操作

### 2. 只读模式

```yaml
cluster.blocks.read_only: true
```

**适用场景：**
- 磁盘空间不足自动触发
- 手动设置维护模式
- 数据保护场景

### 3. 恢复正常模式

```yaml
cluster.blocks.read_only: false
```

**适用场景：**
- 磁盘空间清理后
- 维护完成
- 需要恢复写入

## 推荐设置建议

| 场景 | 推荐值 | 说明 |
|-----|-------|------|
| 正常运行 | false | 允许读写 |
| 磁盘空间不足 | true（自动） | 自动触发 |
| 维护模式 | true（手动） | 临时保护 |
| 数据迁移 | true（手动） | 保护数据 |

## 磁盘水位线与只读块

```
磁盘水位线配置:

cluster.routing.allocation.disk.watermark.low: 85%
    - 新分片不再分配到此节点
    - 集群仍可写入

cluster.routing.allocation.disk.watermark.high: 90%
    - 尝试将分片移到其他节点
    - 集群仍可写入

cluster.routing.allocation.disk.watermark.flood_stage: 95%
    - 自动设置 read_only = true
    - 集群进入只读模式
    - 需要手动恢复
```

## 操作流程示例

```bash
# 1. 手动启用只读模式
PUT /_cluster/settings
{
  "persistent": {
    "cluster.blocks.read_only": true
  }
}

# 2. 查看当前状态
GET /_cluster/health

# 3. 尝试写入（会被拒绝）
POST /test_index/_doc/1
{
  "message": "test"
}
# 返回: cluster_block_exception

# 4. 磁盘空间清理后，手动恢复
PUT /_cluster/settings
{
  "persistent": {
    "cluster.blocks.read_only": false
  }
}
```

## 动态配置示例

```bash
# 启用只读模式（临时）
PUT /_cluster/settings
{
  "transient": {
    "cluster.blocks.read_only": true
  }
}

# 启用只读模式（永久）
PUT /_cluster/settings
{
  "persistent": {
    "cluster.blocks.read_only": true
  }
}

# 恢复正常模式
PUT /_cluster/settings
{
  "persistent": {
    "cluster.blocks.read_only": false
  }
}
```

## 监控建议

```bash
# 查看当前只读状态
GET /_cluster/settings?filter_path=*.cluster.blocks.read_only

# 查看集群块信息
GET /_cluster/state/blocks

# 查看磁盘使用情况
GET /_cat/allocation?v&h=node,disk.used_percent

# 查看集群健康状态
GET /_cluster/health
```

## 错误处理

```
错误信息示例:

cluster_block_exception:
    blocked by: [FORBIDDEN/12/cluster read-only (api)];

解决步骤:

1. 检查磁盘使用情况
   GET /_cat/allocation?v

2. 清理磁盘空间
   - 删除不需要的索引
   - 清理旧日志
   - 扩容磁盘

3. 磁盘空间足够后，手动恢复
   PUT /_cluster/settings
   {
     "persistent": {
       "cluster.blocks.read_only": false
     }
   }
```

## 与其他配置的配合

```
只读模式相关配置:

1. cluster.blocks.read_only
   - 完全只读，不允许任何写入

2. cluster.blocks.read_only_allow_delete
   - 只读但允许删除
   - 可用于清理数据

3. index.blocks.read_only
   - 单个索引级别的只读

4. index.blocks.write
   - 禁止写入但允许删除

选择建议:
- 集群级别保护: 使用 cluster.blocks.read_only
- 需要清理数据: 使用 cluster.blocks.read_only_allow_delete
- 单个索引保护: 使用 index.blocks.read_only
```

## 注意事项

1. **动态更新**：此配置为动态配置，可在线修改
2. **全局影响**：影响整个集群的所有索引
3. **自动触发**：磁盘水位线达到 flood_stage 时自动触发
4. **手动恢复**：磁盘空间恢复后需要手动设置为 false
5. **写入保护**：保护数据不被意外修改
6. **查询可用**：只读模式下查询仍可正常执行