---
title: "Transport 客户端配置"
date: 2026-02-26
lastmod: 2026-02-26
description: "Transport 客户端连接与节点发现相关配置说明"
tags: ["客户端配置", "Transport Client", "连接管理"]
summary: "注意：Transport Client 已被弃用，推荐使用 High Level REST Client。这些配置主要用于旧版客户端或特定场景。
 配置项概述 #  client.transport.* 配置项组用于控制 Transport 客户端的行为，包括节点发现、连接验证、集群名称检查等功能。
   配置项 默认值 说明     client.transport.ignore_cluster_name false 是否忽略集群名称验证   client.transport.nodes_sampler_interval 5s 节点采样间隔   client.transport.ping_timeout 5s 节点 ping 超时时间   client.transport.sniff false 是否启用节点嗅探功能     client.transport.ignore_cluster_name #  配置项作用 #  控制 Transport 客户端是否验证远程节点的集群名称。当设置为 false 时，客户端只会连接到与配置的集群名称匹配的节点。
默认值 #  false 配置格式 #  # 默认配置：验证集群名称 client."
---


> **注意**：Transport Client 已被弃用，推荐使用 High Level REST Client。这些配置主要用于旧版客户端或特定场景。

## 配置项概述

`client.transport.*` 配置项组用于控制 Transport 客户端的行为，包括节点发现、连接验证、集群名称检查等功能。

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `client.transport.ignore_cluster_name` | false | 是否忽略集群名称验证 |
| `client.transport.nodes_sampler_interval` | 5s | 节点采样间隔 |
| `client.transport.ping_timeout` | 5s | 节点 ping 超时时间 |
| `client.transport.sniff` | false | 是否启用节点嗅探功能 |

---

## client.transport.ignore_cluster_name

## 配置项作用

控制 Transport 客户端是否验证远程节点的集群名称。当设置为 `false` 时，客户端只会连接到与配置的集群名称匹配的节点。

## 默认值

```
false
```

## 配置格式

```yaml
# 默认配置：验证集群名称
client.transport.ignore_cluster_name: false

# 忽略集群名称验证
client.transport.ignore_cluster_name: true
```

## 使用场景

**默认配置（推荐）：**
```yaml
client.transport.ignore_cluster_name: false
```

确保客户端只连接到正确的集群，避免误连接。

**跨集群访问：**
```yaml
client.transport.ignore_cluster_name: true
```

允许连接到不同名称的集群，适用于监控或多集群管理场景。

---

## client.transport.nodes_sampler_interval

## 配置项作用

控制客户端定期采样已配置节点以发现可用节点的间隔时间。客户端会按此间隔检查节点状态，更新可用节点列表。

## 默认值

```
5s
```

## 取值范围

```
正数时间值 (如 1s, 5s, 10s, 1m)
```

## 配置格式

```yaml
# 默认配置
client.transport.nodes_sampler_interval: 5s

# 更频繁的节点检测
client.transport.nodes_sampler_interval: 2s

# 减少检测频率
client.transport.nodes_sampler_interval: 30s
```

## 工作原理

```
┌─────────────────────────────────────────────────────────────────┐
│                   节点采样机制                                   │
└─────────────────────────────────────────────────────────────────┘

定时触发 (每 nodes_sampler_interval)
    │
    ▼
采样已配置的节点
    │
    ├── SimpleNodeSampler (sniff=false)
    │   │
    │   └── 只连接到用户显式添加的节点
    │
    └── SniffNodesSampler (sniff=true)
        │
        └── 从集群状态发现所有数据节点
```

## 推荐设置

| 场景 | 推荐值 | 说明 |
|------|--------|------|
| 生产环境 | 5s | 默认配置，平衡及时性和开销 |
| 稳定网络 | 10s-30s | 减少不必要的采样 |
| 不稳定网络 | 2s-5s | 更快发现节点故障 |
| 开发测试 | 5s | 默认配置即可 |

---

## client.transport.ping_timeout

## 配置项作用

控制客户端 ping 节点以检测其可用性时的等待超时时间。如果在此时间内未收到响应，节点将被视为不可用。

## 默认值

```
5s
```

## 取值范围

```
正数时间值 (如 1s, 5s, 10s)
```

## 配置格式

```yaml
# 默认配置
client.transport.ping_timeout: 5s

# 更快的超时（适用于本地网络）
client.transport.ping_timeout: 2s

# 更长的超时（适用于高延迟网络）
client.transport.ping_timeout: 10s
```

## 推荐设置

| 网络环境 | 推荐值 | 说明 |
|----------|--------|------|
| 本地网络 | 2s | 低延迟环境 |
| 局域网 | 5s | 默认配置 |
| 跨地域 | 10s | 高延迟环境 |
| 不稳定网络 | 10s-15s | 避免误判节点故障 |

---

## client.transport.sniff

## 配置项作用

控制是否启用节点嗅探功能。启用后，客户端会从已连接节点获取集群状态，自动发现并连接到集群中的所有数据节点。

## 默认值

```
false
```

## 配置格式

```yaml
# 默认配置：禁用嗅探
client.transport.sniff: false

# 启用嗅探功能
client.transport.sniff: true
```

## 工作原理

```
┌─────────────────────────────────────────────────────────────────┐
│                  嗅探模式对比                                   │
└─────────────────────────────────────────────────────────────────┘

sniff: false (SimpleNodeSampler)
    │
    ├── 用户配置: 192.168.1.10:9300
    ├── 用户配置: 192.168.1.11:9300
    └── 只连接到显式配置的节点


sniff: true (SniffNodesSampler)
    │
    ├── 用户配置: 192.168.1.10:9300
    ├── 自动发现: 192.168.1.11:9300
    ├── 自动发现: 192.168.1.12:9300
    └── 自动发现: 192.168.1.13:9300
         (从集群状态动态获取)
```

## 使用场景

**禁用嗅探（推荐用于简单场景）：**
```yaml
client.transport.sniff: false
```

- 客户端只连接到显式配置的节点
- 配置简单，行为可预测
- 适合节点数量固定的小型集群

**启用嗅探（推荐用于生产环境）：**
```yaml
client.transport.sniff: true
```

- 自动发现所有数据节点
- 节点增减时自动更新连接
- 提供更好的负载分发和故障转移

## 推荐设置指南

| 场景 | sniff 设置 | 说明 |
|------|-----------|------|
| 小型固定集群 | false | 配置简单，足够使用 |
| 大型动态集群 | true | 自动适应节点变化 |
| 生产环境 | true | 更高的可用性 |
| 测试环境 | false | 简化配置 |

---

## 完整配置示例

```yaml
# easysearch.yml

# Transport 客户端配置

# 验证集群名称（默认）
client.transport.ignore_cluster_name: false

# 节点采样间隔
client.transport.nodes_sampler_interval: 5s

# Ping 超时时间
client.transport.ping_timeout: 5s

# 启用节点嗅探
client.transport.sniff: true
```

## Java 客户端代码示例

```java
// 创建 Transport Client
Settings settings = Settings.builder()
    .put("cluster.name", "my-cluster")
    .put("client.transport.ignore_cluster_name", false)
    .put("client.transport.nodes_sampler_interval", "5s")
    .put("client.transport.ping_timeout", "5s")
    .put("client.transport.sniff", true)
    .build();

TransportClient client = new PreBuiltTransportClient(settings)
    .addTransportAddress(new InetSocketTransportAddress("192.168.1.10", 9300));
```

---

## 注意事项

1. **Transport Client 已弃用**：推荐使用 High Level REST Client 替代
2. **静态配置**：修改这些配置需要重启客户端
3. **嗅探功能**：启用嗅探会增加网络开销，但提供更好的可用性
4. **集群名称验证**：生产环境建议保持验证，避免误连接
5. **超时设置**：应根据实际网络延迟调整 ping 超时时间