---
title: "投票配置排除"
date: 2026-03-05
lastmod: 2026-03-05
description: "管理集群投票配置排除列表，用于控制节点参与集群投票和领导选举"
tags: ["集群管理", "节点管理", "集群维护"]
summary: "管理集群投票配置排除列表，用于添加或清除被排除的节点，使其不再参与集群的投票和领导选举。
API #  POST /_cluster/voting_config_exclusions DELETE /_cluster/voting_config_exclusions API 的作用 #  POST /_cluster/voting_config_exclusions #  添加节点到集群投票配置排除列表。当某个节点被排除后，该节点将不再参与集群的投票和领导选举。
主要用于处理有问题的节点，使其不影响集群的正常运行。
DELETE /_cluster/voting_config_exclusions #  清除集群投票配置排除列表。可以清除所有排除或等待被排除的节点从集群中移除后再清除。
API 的参数 #  POST /_cluster/voting_config_exclusions #  Query String 参数 #     参数 类型 是否必填 默认值 描述     node_ids 字符串 是* - 逗号分隔的节点 ID 列表   node_names 字符串 是* - 逗号分隔的节点名称列表   timeout 时间值 否 30s 操作超时时间     注意：node_ids 和 node_names 必须指定其中一个，但不能同时指定。"
---


管理集群投票配置排除列表，用于添加或清除被排除的节点，使其不再参与集群的投票和领导选举。

## API

```
POST /_cluster/voting_config_exclusions
DELETE /_cluster/voting_config_exclusions
```

## API 的作用

### POST /_cluster/voting_config_exclusions
添加节点到集群投票配置排除列表。当某个节点被排除后，该节点将不再参与集群的投票和领导选举。

主要用于处理有问题的节点，使其不影响集群的正常运行。

### DELETE /_cluster/voting_config_exclusions
清除集群投票配置排除列表。可以清除所有排除或等待被排除的节点从集群中移除后再清除。

## API 的参数

### POST /_cluster/voting_config_exclusions

#### Query String 参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `node_ids` | 字符串 | 是* | - | 逗号分隔的节点 ID 列表 |
| `node_names` | 字符串 | 是* | - | 逗号分隔的节点名称列表 |
| `timeout` | 时间值 | 否 | 30s | 操作超时时间 |

> **注意**：`node_ids` 和 `node_names` 必须指定其中一个，但不能同时指定。

### DELETE /_cluster/voting_config_exclusions

#### Query String 参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `wait_for_removal` | 布尔值 | 否 | true | 是否等待所有被排除的节点从集群中移除后再清除排除列表 |
| `timeout` | 时间值 | 否 | 30s | 操作超时时间 |

## 限制和验证

| 限制 | 描述 |
|------|------|
| 最大排除数量 | 系统配置 `cluster.max_voting_config_exclusions` 控制最大允许的排除数量，默认为 10 |
| 互斥检查 | 不能同时指定 `node_ids` 和 `node_names` |
| 主节点限制 | 只有有主节点资格（master-eligible）的节点才能被添加到排除列表 |

## 示例

### 添加节点到排除列表（通过节点 ID）

```bash
POST /_cluster/voting_config_exclusions?node_ids=node1,node2
```

**响应示例：**

```json
{
  "acknowledged": true
}
```

### 添加节点到排除列表（通过节点名称）

```bash
POST /_cluster/voting_config_exclusions?node_names=node-1,node-2
```

### 设置超时时间

```bash
POST /_cluster/voting_config_exclusions?node_ids=node1&timeout=1m
```

### 清除排除列表（等待节点移除）

```bash
DELETE /_cluster/voting_config_exclusions
```

### 清除排除列表（不等待节点移除）

```bash
DELETE /_cluster/voting_config_exclusions?wait_for_removal=false
```

### 使用已弃用的路由（单个节点）

```bash
POST /_cluster/voting_config_exclusions/node-1
```

> **注意**：使用路径参数 `/{node_name}` 的方式已被弃用，建议使用 query 参数 `node_ids` 或 `node_names`。

## 使用场景

### 场景 1：移除故障节点
当某个节点出现故障但不希望它影响集群的投票和领导选举时：

```bash
# 1. 将故障节点添加到排除列表
POST /_cluster/voting_config_exclusions?node_names=faulty-node

# 2. 安全地关闭或移除故障节点

# 3. 清除排除列表
DELETE /_cluster/voting_config_exclusions
```

### 场景 2：集群维护
在进行集群维护前，将某些节点从投票配置中排除：

```bash
# 排除需要维护的节点
POST /_cluster/voting_config_exclusions?node_names=maintenance-node

# 执行维护操作

# 维护完成后清除排除
DELETE /_cluster/voting_config_exclusions?wait_for_removal=true
```

## 重要注意事项

1. **向后兼容性**：
   - `POST /_cluster/voting_config_exclusions/{node_name}` 是已弃用的路由
   - 建议使用 query 参数 `node_ids` 或 `node_names` 替代路径参数

2. **安全性**：
   - 这些 API 需要集群元数据写入权限
   - 在元数据全局阻塞时会拒绝请求

3. **工作原理**：
   - POST 操作会将节点标记为排除，并等待节点从投票配置中移除
   - DELETE 操作会清除排除列表，可以选择等待被排除的节点实际离开集群

4. **节点标识**：
   - 使用 `node_ids`：通过节点 ID 标识节点
   - 使用 `node_names`：通过节点名称标识节点