---
title: "主节点故障检测超时配置"
date: 2026-01-18
lastmod: 2026-01-18
description: "控制主节点故障检测超时时间的配置项说明"
tags: ["集群配置", "故障检测", "高可用"]
summary: "配置项作用 #  cluster.fault_detection.leader_check.timeout 配置项控制从节点向主节点发送健康检查请求后的等待响应超时时间。如果在指定时间内未收到响应，则认为本次检查失败。连续多次失败后会判定主节点故障，触发重新选举。
配置项类型 #  该配置项为静态配置，需要在启动时设置，修改后需要重启节点才能生效。
默认值 #  10s 是否必需 #  可选配置项（有默认值）
取值范围 #  1ms ~ 正无穷 配置格式 #  # 默认配置 cluster.fault_detection.leader_check.timeout: 10s # 快速检测（高可用要求） cluster.fault_detection.leader_check.timeout: 3s # 容忍延迟（跨地域部署） cluster.fault_detection.leader_check.timeout: 30s # 网络不稳定环境 cluster.fault_detection.leader_check.timeout: 15s 相关配置项 #     配置项 默认值 说明     cluster.fault_detection.leader_check.interval 1s 检查间隔   cluster.fault_detection.leader_check.timeout 10s 检查超时时间   cluster.fault_detection.leader_check.retry_count 3 失败重试次数    工作原理 #  故障检测超时机制："
---


## 配置项作用

`cluster.fault_detection.leader_check.timeout` 配置项控制从节点向主节点发送健康检查请求后的等待响应超时时间。如果在指定时间内未收到响应，则认为本次检查失败。连续多次失败后会判定主节点故障，触发重新选举。

## 配置项类型

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

## 默认值

```
10s
```

## 是否必需

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

## 取值范围

```
1ms ~ 正无穷
```

## 配置格式

```yaml
# 默认配置
cluster.fault_detection.leader_check.timeout: 10s

# 快速检测（高可用要求）
cluster.fault_detection.leader_check.timeout: 3s

# 容忍延迟（跨地域部署）
cluster.fault_detection.leader_check.timeout: 30s

# 网络不稳定环境
cluster.fault_detection.leader_check.timeout: 15s
```

## 相关配置项

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `cluster.fault_detection.leader_check.interval` | 1s | 检查间隔 |
| `cluster.fault_detection.leader_check.timeout` | 10s | 检查超时时间 |
| `cluster.fault_detection.leader_check.retry_count` | 3 | 失败重试次数 |

## 工作原理

故障检测超时机制：

```
┌─────────────────────────────────────────────────────────────────┐
│                    主节点故障检测流程                            │
└─────────────────────────────────────────────────────────────────┘

从节点定时发送健康检查
    │
    ├── 发送请求（leader_check.interval）
    │   └── 等待响应...
    │
    ├── 收到响应
    │   │
    │   ├── 重置失败计数
    │   └── 继续下次检查
    │
    └── 未收到响应（超时）
        │
        ├── 失败计数 +1
        │
        ├── 失败计数 < retry_count
        │   │
        │   └── 继续下次检查
        │
        └── 失败计数 >= retry_count
            │
            └── 判定主节点故障
                │
                └── 触发选举
```

## 超时计算

```
故障检测总耗时 = interval × retry_count

示例 1: 使用默认值
interval = 1s, timeout = 10s, retry_count = 3
单次检查: 发送请求 → 等待最多10秒 → 收到响应或超时
故障检测时间 = 1s × 3 = 3秒 (不含超时等待)

示例 2: 快速检测
interval = 300ms, timeout = 3s, retry_count = 3
故障检测时间 = 300ms × 3 = 900ms

示例 3: 高容错
interval = 2s, timeout = 15s, retry_count = 5
故障检测时间 = 2s × 5 = 10秒
```

## 使用场景

### 1. 默认配置（推荐）

```yaml
cluster.fault_detection.leader_check.timeout: 10s
```

适用于大多数集群配置。

### 2. 高可用要求

```yaml
cluster.fault_detection.leader_check.interval: 300ms
cluster.fault_detection.leader_check.timeout: 3s
cluster.fault_detection.leader_check.retry_count: 3
```

**适用场景：**
- 金融交易系统
- 关键业务系统
- 需要快速故障转移

### 3. 跨地域部署

```yaml
cluster.fault_detection.leader_check.interval: 3s
cluster.fault_detection.leader_check.timeout: 30s
cluster.fault_detection.leader_check.retry_count: 3
```

**适用场景：**
- 跨地域集群
- 高延迟网络
- 避免误判

### 4. 网络不稳定

```yaml
cluster.fault_detection.leader_check.interval: 2s
cluster.fault_detection.leader_check.timeout: 15s
cluster.fault_detection.leader_check.retry_count: 5
```

**适用场景：**
- 网络波动大
- 避免频繁选举
- 提高容错性

## 推荐设置建议

| 集群类型 | interval | timeout | retry_count | 说明 |
|---------|----------|---------|-------------|------|
| 本地集群 | 500ms-1s | 3-10s | 3 | 快速检测 |
| 同地域 | 1s | 10s | 3 | 默认配置 |
| 跨地域 | 2-5s | 15-30s | 3-5 | 考虑延迟 |
| 不稳定网络 | 2-3s | 15-20s | 5 | 高容错 |

## 故障检测时间分析

```
配置 A: interval=1s, timeout=10s, retry_count=3
├─ 第1次检查: 0s发送, 10s内响应 → 成功
└─ 如果全部超时: 最多需要 3次检查 × 1s = 3秒触发故障

配置 B: interval=300ms, timeout=3s, retry_count=3
├─ 第1次检查: 0s发送, 3s内响应 → 成功
└─ 如果全部超时: 最多需要 3次检查 × 300ms = 900ms触发故障

配置 C: interval=3s, timeout=30s, retry_count=5
├─ 第1次检查: 0s发送, 30s内响应 → 成功
└─ 如果全部超时: 最多需要 5次检查 × 3s = 15秒触发故障
```

## 监控建议

```bash
# 查看当前配置
GET /_cluster/settings?filter_path=*.cluster.fault_detection.leader_check.*

# 查看主节点状态
GET /_cat/master?v

# 查看节点连接状态
GET /_cat/nodes?v&h=name,ip,master

# 查看集群健康
GET /_cluster/health
```

## 注意事项

1. **静态配置**：修改需要重启节点
2. **与 interval 配合**：timeout 应该大于 interval
3. **网络延迟**：跨地域部署需要考虑网络延迟
4. **误判风险**：timeout 过小可能导致误判
5. **故障恢复时间**：timeout 和 retry_count 决定故障恢复时间
6. **负载影响**：timeout 过大会延长故障检测时间