---
title: "客户端传输节点采样间隔配置"
date: 2026-02-19
lastmod: 2026-02-19
description: "client.transport.nodes_sampler_interval 配置项用于控制 TransportClient 节点采样器的执行间隔，决定客户端多久检查一次节点状态和发现新节点。"
tags: ["客户端", "传输", "节点采样", "TransportClient", "心跳检测"]
summary: "配置项作用 #  client.transport.nodes_sampler_interval 配置项定义了 TransportClient 节点采样器的执行间隔时间。
节点采样器是 TransportClient 的核心组件，负责：
 节点状态监控：定期检查已配置的节点是否存活和可用 节点发现：在嗅探模式下，从集群中发现其他节点 连接管理：自动连接到新增节点，断开不可用的节点连接 集群验证：验证节点是否属于预期的集群  配置项属性 #   配置路径: client.transport.nodes_sampler_interval 数据类型: TimeValue（时间值） 默认值: 5s（5秒） 是否可选: 是  配置项详解 #  采样器工作原理 #  TransportClient 会在启动时创建一个定时任务，按照配置的间隔时间周期性地执行节点采样：
启动 → 等待间隔时间 → 执行采样 → 等待间隔时间 → 执行采样 → ... 每次采样执行以下操作：
 节点存活检查：向配置的节点发送 ping 请求 集群名称验证：检查节点是否属于正确的集群（除非 ignore_cluster_name=true） 节点列表更新：根据采样结果更新可用节点列表  两种采样模式 #  1. 简单采样模式（SimpleNodeSampler） #  当 client.transport.sniff=false（默认）时启用：
 只检查客户端配置的节点列表 验证这些节点是否存活和可用 适用于节点固定的场景  2."
---


## 配置项作用

`client.transport.nodes_sampler_interval` 配置项定义了 **TransportClient** 节点采样器的执行间隔时间。

节点采样器是 TransportClient 的核心组件，负责：
- **节点状态监控**：定期检查已配置的节点是否存活和可用
- **节点发现**：在嗅探模式下，从集群中发现其他节点
- **连接管理**：自动连接到新增节点，断开不可用的节点连接
- **集群验证**：验证节点是否属于预期的集群

## 配置项属性

- **配置路径**: `client.transport.nodes_sampler_interval`
- **数据类型**: `TimeValue`（时间值）
- **默认值**: `5s`（5秒）
- **是否可选**: 是

## 配置项详解

## 采样器工作原理

TransportClient 会在启动时创建一个定时任务，按照配置的间隔时间周期性地执行节点采样：

```
启动 → 等待间隔时间 → 执行采样 → 等待间隔时间 → 执行采样 → ...
```

每次采样执行以下操作：

1. **节点存活检查**：向配置的节点发送 ping 请求
2. **集群名称验证**：检查节点是否属于正确的集群（除非 `ignore_cluster_name=true`）
3. **节点列表更新**：根据采样结果更新可用节点列表

## 两种采样模式

### 1. 简单采样模式（SimpleNodeSampler）

当 `client.transport.sniff=false`（默认）时启用：

- 只检查客户端配置的节点列表
- 验证这些节点是否存活和可用
- 适用于节点固定的场景

### 2. 嗅探采样模式（SniffNodesSampler）

当 `client.transport.sniff=true` 时启用：

- 除了检查配置的节点，还会从集群中发现其他节点
- 自动将新发现的节点加入客户端节点列表
- 适用于动态集群环境

## 配置建议

## 生产环境

```yaml
client.transport.nodes_sampler_interval: 5s
```

**建议**: 保持默认值 `5s`。这个间隔在实时性和性能之间取得了良好的平衡。

## 测试环境

```yaml
client.transport.nodes_sampler_interval: 1s
```

**建议**: 可以设置为 `1s`。测试环境需要快速发现节点状态变化，加速测试执行。

## 高延迟网络环境

```yaml
client.transport.nodes_sampler_interval: 10s
```

**建议**: 适当增加到 `10s-30s`。网络延迟较高时，频繁采样会增加不必要的开销。

## 需要快速故障检测

```yaml
client.transport.nodes_sampler_interval: 2s
```

**建议**: 减少到 `1s-3s`。当业务对节点故障敏感，需要快速切换时使用。

## 代码示例

## Java 客户端配置

```java
Settings settings = Settings.builder()
    .put("cluster.name", "my-production-cluster")
    .put("client.transport.nodes_sampler_interval", "5s")  // 生产环境使用默认值
    .build();

TransportClient client = new PreBuiltTransportClient(settings)
    .addTransportAddress(new TransportAddress(InetAddress.getByName("node1.example.com"), 9300))
    .addTransportAddress(new TransportAddress(InetAddress.getByName("node2.example.com"), 9300));
```

## 启用嗅探模式的配置

```java
Settings settings = Settings.builder()
    .put("client.transport.sniff", true)  // 启用节点嗅探
    .put("client.transport.nodes_sampler_interval", "5s")  // 配合嗅探使用
    .build();
```

## 测试环境配置

```java
Settings settings = Settings.builder()
    .put("client.transport.nodes_sampler_interval", "1s")  // 测试环境使用较短间隔
    .build();
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `client.transport.ping_timeout` | 节点检查超时时间 | 5s |
| `client.transport.sniff` | 是否启用节点嗅探 | false |
| `client.transport.ignore_cluster_name` | 是否忽略集群名称检查 | false |

## 性能影响

采样间隔的设置会影响以下方面：

| 间隔设置 | 优点 | 缺点 |
|----------|------|------|
| 较短（1-2s） | 快速发现节点故障，快速发现新节点 | 增加网络开销和 CPU 使用 |
| 中等（5s） | 平衡实时性和性能 | 故障检测有一定延迟 |
| 较长（10-30s） | 减少网络开销，节省资源 | 节点故障检测延迟较大 |

## 注意事项

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

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

3. **间隔过短的影响**: 如果将间隔设置得过短（如毫秒级），会产生大量网络请求，可能影响集群性能。

4. **与 ping_timeout 的关系**: `nodes_sampler_interval` 控制采样频率，`ping_timeout` 控制单次采样等待响应的超时时间。两者配合确保节点状态检测的准确性。