---
title: "客户端传输集群名称验证配置"
date: 2026-02-15
lastmod: 2026-02-15
description: "client.transport.ignore_cluster_name 配置项用于控制 TransportClient 在连接到集群节点时是否验证集群名称，确保客户端连接到正确的集群。"
tags: ["客户端", "传输", "集群名称", "TransportClient"]
summary: "配置项作用 #  client.transport.ignore_cluster_name 配置项用于控制 TransportClient 在连接到集群节点时是否验证集群名称。
TransportClient 是 Easysearch 提供的 Java 客户端，它通过传输协议直接与集群节点通信。当客户端连接到节点时，默认情况下会验证节点的集群名称是否与客户端配置的集群名称一致，这是一种安全保护机制，防止客户端意外连接到错误的集群。
配置项属性 #   配置路径: client.transport.ignore_cluster_name 数据类型: boolean 默认值: false 是否可选: 是  配置项详解 #  当设置为 false（默认值）时 #  TransportClient 会严格验证集群名称：
 客户端会检查所连接节点的集群名称是否与客户端配置的集群名称匹配 如果集群名称不匹配，该节点会被添加到 filteredNodes 列表中，不会被使用 只有集群名称匹配的节点才会被客户端使用  适用场景: 生产环境，确保客户端连接到正确的集群，避免误操作。
当设置为 true 时 #  TransportClient 会忽略集群名称验证：
 客户端不会检查集群名称是否匹配 所有配置的节点都会被尝试连接，无论其集群名称是什么 被过滤的节点列表将为空  适用场景:
 测试环境：需要连接到不同名称的测试集群 开发调试：简化连接过程 特殊场景：需要跨集群访问  配置建议 #  生产环境 #  client.transport.ignore_cluster_name: false 建议: 保持默认值 false。这可以确保客户端只连接到预期名称的集群，防止因配置错误导致数据写入错误的集群。"
---


## 配置项作用

`client.transport.ignore_cluster_name` 配置项用于控制 **TransportClient** 在连接到集群节点时是否验证集群名称。

TransportClient 是 Easysearch 提供的 Java 客户端，它通过传输协议直接与集群节点通信。当客户端连接到节点时，默认情况下会验证节点的集群名称是否与客户端配置的集群名称一致，这是一种安全保护机制，防止客户端意外连接到错误的集群。

## 配置项属性

- **配置路径**: `client.transport.ignore_cluster_name`
- **数据类型**: `boolean`
- **默认值**: `false`
- **是否可选**: 是

## 配置项详解

## 当设置为 `false`（默认值）时

TransportClient 会严格验证集群名称：

- 客户端会检查所连接节点的集群名称是否与客户端配置的集群名称匹配
- 如果集群名称不匹配，该节点会被添加到 `filteredNodes` 列表中，不会被使用
- 只有集群名称匹配的节点才会被客户端使用

**适用场景**: 生产环境，确保客户端连接到正确的集群，避免误操作。

## 当设置为 `true` 时

TransportClient 会忽略集群名称验证：

- 客户端不会检查集群名称是否匹配
- 所有配置的节点都会被尝试连接，无论其集群名称是什么
- 被过滤的节点列表将为空

**适用场景**:
- 测试环境：需要连接到不同名称的测试集群
- 开发调试：简化连接过程
- 特殊场景：需要跨集群访问

## 配置建议

## 生产环境

```yaml
client.transport.ignore_cluster_name: false
```

**建议**: 保持默认值 `false`。这可以确保客户端只连接到预期名称的集群，防止因配置错误导致数据写入错误的集群。

## 测试环境

```yaml
client.transport.ignore_cluster_name: true
```

**建议**: 可以设置为 `true`。测试环境中经常需要连接到不同名称的测试集群，忽略集群名称验证可以简化测试配置。

## 代码示例

## Java 客户端配置

```java
Settings settings = Settings.builder()
    .put("cluster.name", "my-production-cluster")
    .put("client.transport.ignore_cluster_name", false)  // 生产环境建议保持 false
    .build();

TransportClient client = new PreBuiltTransportClient(settings)
    .addTransportAddress(new TransportAddress(InetAddress.getByName("localhost"), 9300));
```

## 测试环境配置

```java
Settings settings = Settings.builder()
    .put("client.transport.ignore_cluster_name", true)  // 测试环境忽略集群名称验证
    .build();
```

## 注意事项

1. **仅适用于 TransportClient**: 此配置项只影响基于传输协议的 Java 客户端，不影响 REST 客户端。

2. **TransportClient 已弃用**: 在 Easysearch 8.0 及更高版本中，TransportClient 已被弃用，建议迁移到 RestClient。

3. **安全性考虑**: 在生产环境中保持默认值 `false` 可以提供额外的安全保障，防止数据误写入错误的集群。

4. **调试支持**: 当集群名称不匹配且 `ignore_cluster_name=false` 时，被过滤的节点会被记录在 `filteredNodes()` 方法返回的列表中，便于调试排查问题。