---
title: "集群名称配置"
date: 2026-03-26
lastmod: 2026-03-26
description: "定义 Easysearch 集群名称的配置项说明"
tags: ["集群配置", "基础配置", "节点发现"]
summary: "配置项作用 #  cluster.name 配置项定义 Easysearch 集群的唯一名称。只有集群名称相同的节点才能组成同一个集群。
配置项类型 #  该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。
默认值 #  easysearch 是否必需 #  可选配置项（但强烈建议为每个集群设置明确的名称）
命名规则 #   不能为空 不能包含冒号（:） 建议使用有意义的名称  工作原理 #  ┌─────────────────────────────────────────────────────────┐ │ 节点发现过程 │ └─────────────────────────────────────────────────────────┘ 节点A 节点B 节点C cluster.name: prod cluster.name: prod cluster.name: dev │ │ │ └───────────┬───────────┘ │ │ │ cluster.name 相同 cluster.name 不同 │ │ ▼ ▼ 组成同一集群 独立集群 "prod" "dev" 使用示例 #  # 开发环境 cluster.name: dev-cluster # 测试环境 cluster."
---


## 配置项作用

`cluster.name` 配置项定义 Easysearch 集群的唯一名称。只有集群名称相同的节点才能组成同一个集群。

## 配置项类型

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

## 默认值

```
easysearch
```

## 是否必需

**可选配置项**（但强烈建议为每个集群设置明确的名称）

## 命名规则

1. **不能为空**
2. **不能包含冒号（:）**
3. **建议使用有意义的名称**

## 工作原理

```
┌─────────────────────────────────────────────────────────┐
│                    节点发现过程                          │
└─────────────────────────────────────────────────────────┘
    节点A                    节点B                    节点C
cluster.name: prod      cluster.name: prod      cluster.name: dev
        │                       │                       │
        └───────────┬───────────┘                       │
                    │                                   │
            cluster.name 相同                        cluster.name 不同
                    │                                   │
                    ▼                                   ▼
              组成同一集群                          独立集群
              "prod"                                "dev"
```

## 使用示例

```yaml
# 开发环境
cluster.name: dev-cluster

# 测试环境
cluster.name: test-cluster

# 生产环境
cluster.name: prod-cluster

# 多数据中心
cluster.name: prod-dc1
cluster.name: prod-dc2
```

## 推荐设置建议

**为每个环境设置不同的集群名称：**

| 环境 | 推荐名称 | 说明 |
|-----|---------|------|
| 开发 | `dev-cluster` 或 `dev-{项目名}` | 开发环境专用 |
| 测试 | `test-cluster` 或 `test-{项目名}` | 测试环境专用 |
| 预发布 | `staging-cluster` 或 `staging-{项目名}` | 预发布环境 |
| 生产 | `prod-cluster` 或 `prod-{项目名}` | 生产环境专用 |

**多数据中心部署：**

```yaml
# 数据中心 1
cluster.name: prod-dc1

# 数据中心 2
cluster.name: prod-dc2
```

**命名最佳实践：**

1. **使用有意义的名称**：反映环境、用途或位置
2. **保持简洁**：避免过长或复杂的名称
3. **使用小写**：避免大小写混淆
4. **使用连字符**：提高可读性
5. **避免特殊字符**：只使用字母、数字和连字符

## 集群隔离

使用不同的集群名称可以隔离不同的集群：

```
网络环境：同一网段
├── 192.168.1.10 (dev-cluster)  ← 开发集群
├── 192.168.1.11 (dev-cluster)
├── 192.168.1.20 (test-cluster) ← 测试集群
├── 192.168.1.21 (test-cluster)
├── 192.168.1.30 (prod-cluster) ← 生产集群
└── 192.168.1.31 (prod-cluster)
```

即使节点在同一网络中，不同的集群名称也能确保它们组成独立的集群。

## 安全考虑

**集群名称验证：**

传输层会验证集群名称以防止节点加入错误的集群：

```yaml
# 客户端配置
cluster.name: prod-cluster

# 如果尝试连接到 cluster.name: test-cluster 的集群
# 将因集群名称不匹配而被拒绝
```

## 配置位置

**配置文件（easysearch.yml）：**

```yaml
cluster.name: my-production-cluster
```

**命令行：**

```bash
./bin/easysearch -Ecluster.name=my-cluster
```

**环境变量：**

```bash
export ES_JAVA_OPTS="-Ecluster.name=my-cluster"
```

## 查看集群名称

```bash
# 通过 API 查看当前集群名称
GET /

# 响应
{
  "name" : "node-1",
  "cluster_name" : "my-cluster",
  ...
}

# 通过 API 查看所有节点的集群信息
GET /_cat/nodes?v
```

## 常见问题

**问题 1：节点无法组成集群**

检查各节点的 `cluster.name` 是否一致：

```bash
# 查看每个节点的配置
GET /_nodes/settings?filter_path=**.cluster.name
```

**问题 2：误加入其他集群**

确保生产、测试等环境的集群名称不同，避免节点加入错误的集群。

**问题 3：集群名称包含冒号**

```
[cluster.name] must not contain ':'
```

解决方案：使用连字符或下划线替代冒号。

## 相关配置项

| 配置项 | 作用 | 默认值 |
|-------|------|-------|
| `node.name` | 节点名称 | 机器名随机部分 |
| `discovery.seed_hosts` | 种子节点地址 | - |
| `cluster.initial_master_nodes` | 初始主节点列表 | - |
| `client.transport.ignore_cluster_name` | 是否忽略集群名称验证 | false |

## 注意事项

1. **静态配置**：修改集群名称需要重启节点
2. **生产环境**：务必为生产集群设置独特且明确的名称
3. **环境隔离**：使用不同的集群名称隔离不同环境
4. **命名规范**：制定并遵守集群命名规范
5. **验证连接**：使用 `client.transport.ignore_cluster_name: false` 确保连接到正确的集群