---
title: "节点角色配置"
date: 2026-03-26
lastmod: 2026-03-26
description: "控制节点角色的配置项说明"
tags: ["节点配置", "集群规划", "角色分配"]
summary: "配置项作用 #  node.roles 配置项指定节点的角色，决定节点在集群中的功能。每个角色对应不同的职责，合理分配角色可以优化集群性能和资源使用。
配置项类型 #  该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。
默认值 #  [master, data, ingest, remote_cluster_client] 是否必需 #  可选配置项（有默认值）
可用角色 #     角色 缩写 说明 能否存储数据     master m 主节点候选，参与集群管理 否   data d 数据节点，存储数据并执行查询 是   ingest i 摄入节点，处理数据预处理 否   remote_cluster_client r 跨集群客户端节点 否   search s 搜索节点，执行搜索操作 是    配置格式 #  # 多角色节点（默认） node."
---


## 配置项作用

`node.roles` 配置项指定节点的角色，决定节点在集群中的功能。每个角色对应不同的职责，合理分配角色可以优化集群性能和资源使用。

## 配置项类型

该配置项为**静态配置**，需要在启动时设置，修改后需要重启节点才能生效。

## 默认值

```
[master, data, ingest, remote_cluster_client]
```

## 是否必需

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

## 可用角色

| 角色 | 缩写 | 说明 | 能否存储数据 |
|-----|------|------|-------------|
| `master` | m | 主节点候选，参与集群管理 | 否 |
| `data` | d | 数据节点，存储数据并执行查询 | 是 |
| `ingest` | i | 摄入节点，处理数据预处理 | 否 |
| `remote_cluster_client` | r | 跨集群客户端节点 | 否 |
| `search` | s | 搜索节点，执行搜索操作 | 是 |

## 配置格式

```yaml
# 多角色节点（默认）
node.roles: [master, data, ingest, remote_cluster_client]

# 包含搜索角色的多角色节点
node.roles: [master, data, ingest, remote_cluster_client, search]

# 专用数据节点
node.roles: [data]

# 专用主节点
node.roles: [master]

# 专用搜索节点
node.roles: [search]

# 协调节点（无角色）
node.roles: []
```

## 角色详解

**1. master（主节点）**

负责集群管理操作：
- 创建/删除索引
- 追踪集群中的节点
- 决定分片分配到哪个节点
- 维护集群状态

```yaml
# 专用主节点配置（推荐）
node.roles: [master]
```

**2. data（数据节点）**

存储数据并执行相关操作：
- CRUD 操作
- 聚合查询
- 分片恢复

```yaml
# 数据节点配置（推荐）
node.roles: [data]
```

**3. ingest（摄入节点）**

在索引前预处理数据：
- 数据转换
- 富文档处理
- Pipeline 执行

```yaml
# 摄入节点配置（推荐）
node.roles: [ingest]
```

**4. remote_cluster_client（跨集群客户端）**

连接到远程集群：
- 跨集群搜索
- 跨集群复制

```yaml
# 跨集群客户端配置
node.roles: [remote_cluster_client]
```

**5. search（搜索节点）**

执行搜索操作：
- 搜索请求
- 聚合查询

```yaml
# 搜索节点配置
node.roles: [search]
```

## 集群架构规划

**小型集群（3 节点）：**

```
┌─────────────────────────────────────┐
│           节点1                     │
│  [master, data, ingest]             │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│           节点2                     │
│  [master, data, ingest]             │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│           节点3                     │
│  [master, data, ingest]             │
└─────────────────────────────────────┘
```

```yaml
# 所有节点配置相同
node.roles: [master, data, ingest]
```

**中型集群（推荐架构）：**

```
┌─────────────────────────────────────┐
│       主节点 (3个)                  │
│         [master]                   │
│    管理集群，不存储数据               │
└─────────────────────────────────────┘
           │
┌─────────────────────────────────────┐
│      数据节点 (N个)                 │
│         [data]                     │
│    存储数据，执行查询                │
└─────────────────────────────────────┘
```

```yaml
# 主节点
node.roles: [master]

# 数据节点
node.roles: [data]
```

**大型集群（专用角色）：**

```
┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐
│    主节点层      │  │    数据节点层     │  │    协调节点层    │
│   [master]      │  │    [data]        │  │      []          │
│                  │  │                  │  │                  │
│  - 集群管理      │  │  - 数据存储      │  │  - 请求处理      │
│  - 状态维护      │  │  - 查询执行      │  │  - 结果聚合      │
└──────────────────┘  └──────────────────┘  └──────────────────┘
                              │
                    ┌──────────────────┐
                    │   摄入节点层     │
                    │   [ingest]       │
                    │                  │
                    │  - 数据预处理    │
                    │  - Pipeline执行  │
                    └──────────────────┘
```

## 推荐配置建议

**生产环境建议**：根据集群规模和功能需求设置

| 集群规模 | 主节点 | 数据节点 | 摄入节点 | 协调节点 |
|---------|-------|---------|---------|---------|
| < 10 节点 | 每个节点 | 每个节点 | 每个节点 | 不需要 |
| 10-50 节点 | 3 台专用 | N 台专用 | 可选 | 可选 |
| > 50 节点 | 3-5 台专用 | N 台专用 | 专用 | 专用 |

## 主节点规划

**主节点数量建议：**

```
最小主节点数 = (总主节点数 / 2) + 1

示例：
- 3 个主节点：允许 1 个故障
- 5 个主节点：允许 2 个故障
- 7 个主节点：允许 3 个故障
```

**主节点配置：**

```yaml
# 专用主节点
node.roles: [master]
node.name: master-node-1

# 硬件建议
# - CPU: 中等
# - 内存: 中等（4-8GB）
# - 磁盘: 小（仅存储集群状态）
# - 网络: 低延迟
```

## 数据节点规划

```yaml
# 数据节点
node.roles: [data]

# 硬件建议
# - CPU: 高性能
# - 内存: 大（建议 50% 堆给文件系统缓存）
# - 磁盘: 大容量 SSD
# - 网络: 高带宽

# JVM 堆内存建议
# - < 64GB RAM: 50% 给堆
# - >= 64GB RAM: 最大 30GB 给堆
```

## 协调节点规划

```yaml
# 协调节点（无角色）
node.roles: []

# 功能
# - 处理搜索请求
# - 聚合结果
# - 分发请求到数据节点

# 硬件建议
# - CPU: 高性能
# - 内存: 中等
# - 磁盘: 小（不存储数据）
# - 网络: 高带宽低延迟
```

## 摄入节点规划

```yaml
# 摄入节点
node.roles: [ingest]

# 功能
# - 执行 Pipeline
# - 数据预处理

# 硬件建议
# - CPU: 取决于处理复杂度
# - 内存: 中等
# - 磁盘: 小（不存储原始数据）
```

## 查看节点角色

```bash
# 查看所有节点及其角色
GET /_cat/node_attrs?v

# 查看节点信息
GET /_cat/nodes?v

# 查看特定节点
GET /_nodes/node-1
```

**输出示例：**

```
name      node.roles          master
node-1    master,data,ingest   *
node-2    data                -
node-3    ingest              -
```

## 常见问题

**问题 1：没有配置主节点导致集群无法形成**

**解决方案：**

```yaml
# 确保至少有 3 个主节点候选
# 节点 1
node.roles: [master]

# 节点 2
node.roles: [master]

# 节点 3
node.roles: [master]

# 设置初始主节点
cluster.initial_master_nodes: ["node-1", "node-2", "node-3"]
```

**问题 2：数据节点负载过高**

**解决方案：**

1. **增加数据节点数量**
2. **使用专用协调节点**
3. **优化查询和索引策略**

**问题 3：主节点负载过高**

**解决方案：**

```yaml
# 确保主节点不承担其他角色
node.roles: [master]

# 减少集群状态变更
# - 避免频繁创建/删除索引
# - 使用索引模板
# - 合理设置分片数
```

## 迁移指南

**从旧配置迁移到新配置：**

```yaml
# 旧配置（已弃用）
node.master: true
node.data: true
node.ingest: true

# 新配置（推荐）
node.roles: [master, data, ingest]
```

**迁移示例：**

```yaml
# 原有节点
# node.roles: [master, data, ingest]

# 新增专用主节点
node.roles: [master]

# 数据节点移除 master 角色
node.roles: [data]
```

## 相关配置项

| 配置项 | 作用 | 默认值 |
|-------|------|-------|
| `node.master` | 主节点角色（已弃用） | true |
| `node.data` | 数据节点角色（已弃用） | true |
| `node.ingest` | 摄入节点角色（已弃用） | true |
| `node.remote_cluster_client` | 跨集群客户端（已弃用） | true |
| `cluster.initial_master_nodes` | 初始主节点列表 | - |

## 注意事项

1. **静态配置**：修改角色需要重启节点
2. **主节点数量**：建议配置 3 或 5 个专用主节点
3. **资源分离**：专用角色可提高性能
4. **集群规模**：小集群可使用多角色节点
5. **逐步迁移**：从旧配置迁移时建议逐步调整