---
title: "磁盘高水位线配置"
date: 2026-01-09
lastmod: 2026-01-09
description: "cluster.routing.allocation.disk.watermark.high 配置项用于设置磁盘使用率的高水位线，超过此阈值时将阻止新分片分配并迁移现有分片。"
tags: ["磁盘分配", "水位线", "分片迁移", "磁盘管理"]
summary: "配置项作用 #  cluster.routing.allocation.disk.watermark.high 配置项用于设置磁盘使用率的高水位线。
当一个节点的磁盘使用率超过此阈值时：
 不允许在该节点上分配新的分片 现有的分片会被迁移到其他节点  这是防止磁盘空间被完全占用的关键保护机制。
配置项属性 #   配置路径: cluster.routing.allocation.disk.watermark.high 数据类型: string（百分比或字节值） 默认值: 90% 是否可选: 是 是否动态: 是（支持动态更新）  配置项详解 #  工作机制 #  磁盘使用率监控 0% ─────────────────────────────────── 100% │ │ │ │ │ │ 低水位线 │ │ (默认 85%) │ │ │ │ │ │ 高水位线 │ │ │ (默认 90%) │ │ │ │ │ ├──────────────┼────┼───────────────────┤ 安全区 警告区 危险区 │ │ │ │ └──────────────┴────┴───────────────────┘ ↓ ↓ ↓ 正常分配 不分配 迁移分片 新分片 决策逻辑 #  场景 1：节点已超过高水位线 #  节点磁盘使用率: 92% (> 90%) 新分片分配请求 ↓ ❌ 拒绝分配 现有分片 ↓ 触发迁移到其他节点 场景 2：分配会导致超过高水位线 #  节点当前使用率: 88% 新分片大小: 3GB 节点可用空间: 2."
---


## 配置项作用

`cluster.routing.allocation.disk.watermark.high` 配置项用于设置磁盘使用率的**高水位线**。

当一个节点的磁盘使用率超过此阈值时：
- 不允许在该节点上分配新的分片
- 现有的分片会被迁移到其他节点

这是防止磁盘空间被完全占用的关键保护机制。

## 配置项属性

- **配置路径**: `cluster.routing.allocation.disk.watermark.high`
- **数据类型**: `string`（百分比或字节值）
- **默认值**: `90%`
- **是否可选**: 是
- **是否动态**: 是（支持动态更新）

## 配置项详解

## 工作机制

```
磁盘使用率监控

    0% ─────────────────────────────────── 100%
    │                                        │
    │              │                        │
    │           低水位线                     │
    │          (默认 85%)                   │
    │              │                        │
    │              │    高水位线            │
    │              │   (默认 90%)           │
    │              │    │                   │
    ├──────────────┼────┼───────────────────┤
    安全区        警告区  危险区
    │              │    │                   │
    └──────────────┴────┴───────────────────┘

    ↓              ↓    ↓
    正常分配      不分配  迁移分片
                      新分片
```

## 决策逻辑

### 场景 1：节点已超过高水位线

```
节点磁盘使用率: 92% (> 90%)

新分片分配请求
    ↓
❌ 拒绝分配

现有分片
    ↓
触发迁移到其他节点
```

### 场景 2：分配会导致超过高水位线

```
节点当前使用率: 88%
新分片大小: 3GB
节点可用空间: 2.4GB

分配后预期使用率: 91% (> 90%)

新分片分配请求
    ↓
❌ 拒绝分配（会导致超过高水位线）
```

### 场景 3：节点在高水位线以下

```
节点磁盘使用率: 87% (< 90%)

新分片分配请求
    ↓
✅ 允许分配
```

## 配置建议

## 生产环境（标准）

```yaml
cluster.routing.allocation.disk.watermark.high: 90%
```

**建议**: 保持默认值 `90%`。这是经过验证的标准配置，平衡了磁盘利用率和安全性。

## 高磁盘利用率需求

```yaml
cluster.routing.allocation.disk.watermark.high: 95%
```

**建议**: 可以提高到 `93%-95%`。当需要最大化磁盘利用率时使用，但需要更密切的监控。

## 保守策略

```yaml
cluster.routing.allocation.disk.watermark.high: 85%
```

**建议**: 降低到 `82%-85%`。当磁盘空间充裕且更关注安全时使用。

## 配合低水位线

```yaml
cluster:
  routing:
    allocation:
      disk:
        watermark:
          low: 85%    # 低水位线
          high: 90%   # 高水位线（必须高于低水位线）
```

## 代码示例

## easysearch.yml 配置

```yaml
cluster:
  routing:
    allocation:
      disk:
        watermark:
          high: 90%
          low: 85%
          flood_stage: 95%
```

## 使用字节值配置

```yaml
cluster:
  routing:
    allocation:
      disk:
        watermark:
          high: 100gb   # 当剩余空间小于100GB时触发
          low: 150gb
```

## 混合配置

```yaml
cluster:
  routing:
    allocation:
      disk:
        watermark:
          high: 90%     # 使用百分比
          low: 500mb    # 使用字节值（不推荐混合使用）
```

## 动态更新

```bash
# 通过 API 动态更新高水位线
PUT _cluster/settings
{
  "transient": {
    "cluster.routing.allocation.disk.watermark.high": "92%"
  }
}
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `cluster.routing.allocation.disk.watermark.low` | 磁盘低水位线 | 85% |
| `cluster.routing.allocation.disk.watermark.flood_stage` | 磁盘洪水阶段水位线 | 95% |
| `cluster.routing.allocation.disk.threshold_enabled` | 是否启用磁盘阈值检查 | true |

## 水位线关系

```
低水位线 < 高水位线 < 洪水水位线
   85%   <    90%     <     95%

配置时必须满足这个顺序，否则会报错
```

## 支持的格式

| 格式类型 | 示例 | 说明 |
|----------|------|------|
| 百分比 | `90%`, `85.5%` | 基于磁盘总量的百分比 |
| 字节值 | `100gb`, `500mb` | 绝对字节数 |
| 字节值 | `50GB`, `20TB` | 大小写均可 |

## 行为对比

| 磁盘使用率 | 低于低水位线 | 低水位线到高水位线 | 超过高水位线 |
|-----------|-------------|------------------|-------------|
| 新分片分配 | ✅ 允许 | ❌ 不允许 | ❌ 不允许 |
| 现有分片 | ✅ 保留 | ✅ 保留 | ❌ 迁移 |

## 注意事项

1. **必须高于低水位线**: 配置的高水位线必须高于低水位线，否则无法生效。

2. **动态更新**: 此配置支持动态更新，修改后立即生效。

3. **字节值限制**: 使用字节值时，确保各节点磁盘大小相近，否则行为不一致。

4. **分片迁移成本**: 超过高水位线后触发分片迁移会消耗网络和IO资源。

5. **监控建议**: 建议设置监控，在接近高水位线时提前告警。

6. **洪水阶段**: 当超过洪水阶段水位线（默认95%）时，所有索引的写入操作将被阻止。

7. **单节点集群**: 在单节点集群中，如果 `enable_for_single_data_node` 为 false，此配置可能不生效。