---
title: "跟随者元数据同步间隔配置"
date: 2026-01-31
lastmod: 2026-01-31
description: "replication.follower.metadata_sync_interval 配置项用于控制跟随者轮询元数据同步的间隔时间。"
tags: ["Replication", "跨集群复制", "元数据", "同步间隔"]
summary: "配置项作用 #  replication.follower.metadata_sync_interval 配置项用于控制跟随者节点从 Leader 集群轮询元数据同步的间隔时间。
元数据包括索引的设置（settings）、映射（mappings）和别名（aliases）。此配置决定了 Follower 检查 Leader 元数据变更的频率。
配置项属性 #   配置路径: replication.follower.metadata_sync_interval 数据类型: TimeValue（时间值，如 5s, 30s, 1m） 默认值: 5s（新版本）或 60s（旧版本） 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（可以动态更新，无需重启）  配置项详解 #  工作机制 #  元数据同步机制 同步循环: 1. 轮询 Leader 元数据 ├── 索引设置 ├── 索引映射 └── 索引别名 2. 比较元数据 ├── 检查是否有变更 ├── 检查版本号 └── 检测差异 3. 应用变更 ├── 更新本地设置 ├── 更新本地映射 └── 更新本地别名 4. 等待间隔 delay(metadata_sync_interval) ↓ 5."
---


## 配置项作用

`replication.follower.metadata_sync_interval` 配置项用于控制**跟随者节点从 Leader 集群轮询元数据同步的间隔时间**。

元数据包括索引的设置（settings）、映射（mappings）和别名（aliases）。此配置决定了 Follower 检查 Leader 元数据变更的频率。

## 配置项属性

- **配置路径**: `replication.follower.metadata_sync_interval`
- **数据类型**: `TimeValue`（时间值，如 `5s`, `30s`, `1m`）
- **默认值**: `5s`（新版本）或 `60s`（旧版本）
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: **是**（可以动态更新，无需重启）

## 配置项详解

## 工作机制

```
元数据同步机制

同步循环:
1. 轮询 Leader 元数据
   ├── 索引设置
   ├── 索引映射
   └── 索引别名


2. 比较元数据
   ├── 检查是否有变更
   ├── 检查版本号
   └── 检测差异


3. 应用变更
   ├── 更新本地设置
   ├── 更新本地映射
   └── 更新本地别名


4. 等待间隔
   delay(metadata_sync_interval)
   ↓
5. 返回步骤 1


metadata_sync_interval = 5s (新版本默认):
├── 每 5 秒检查一次
├── 快速响应变更
└── 适合大多数场景 ✅


metadata_sync_interval = 60s (旧版本默认):
├── 每 60 秒检查一次
├── 减少 Leader 负载
└── 变更响应慢
```

## 元数据类型

```
同步的元数据类型

1. 索引设置 (Index Settings)
   ├── number_of_shards
   ├── number_of_replicas
   ├── refresh_interval
   ├── analysis 配置
   └── 其他索引设置


2. 索引映射 (Index Mappings)
   ├── 字段定义
   ├── 字段类型
   ├── 分析器配置
   └── 映射结构


3. 索引别名 (Index Aliases)
   ├── 别名名称
   ├── 过滤器
   ├── 路由值
   └── 别名配置


同步时机:
├── 定期轮询 (polling)
├── 版本变更检测
└── 差异同步
```

## 同步流程

```
完整的同步流程

时间线:
0s  ─── 初始同步
       └── 获取 Leader 元数据
       └── 应用到 Follower


5s  ─── 第一次轮询
       └── 检查元数据版本
       └── 无变更 → 跳过


10s ─── 第二次轮询
       └── 检查元数据版本
       └── 发现变更! ✅
       └── 应用新元数据


15s ─── 第三次轮询
        └── 继续检查
        └── 周期性同步


效果:
├── 最终一致性
├── 最小延迟: 5s
├── 平均延迟: 10s
└── 自动同步 ✅
```

## 配置建议

## 生产环境（默认）

```yaml
replication:
  follower:
    metadata_sync_interval: 5s  # 新版本默认
```

**建议**: 保持默认值 `5s`。适合大多数场景。

## 快速响应场景

```yaml
replication:
  follower:
    metadata_sync_interval: 1s  # 快速同步
```

**建议**: 元数据变更频繁且需要快速响应时使用。

## 低负载场景

```yaml
replication:
  follower:
    metadata_sync_interval: 30s  # 减少轮询频率
```

**建议**: 元数据变更很少且希望减少 Leader 负载时使用。

## 大规模集群

```yaml
replication:
  follower:
    metadata_sync_interval: 60s  # 减少集群负载
```

**建议**: 大规模集群且元数据变更极少时使用。

## 代码示例

## easysearch.yml 基础配置

```yaml
replication:
  follower:
    metadata_sync_interval: 5s
```

## 快速响应配置

```yaml
replication:
  follower:
    metadata_sync_interval: 1s
    poll_interval: 1ms
```

## 低负载配置

```yaml
replication:
  follower:
    metadata_sync_interval: 30s
```

## 动态更新配置

```json
// 运行时更新
PUT /_cluster/settings
{
  "persistent": {
    "replication.follower.metadata_sync_interval": "10s"
  }
}
```

## 查看复制状态

```json
// 查看元数据同步状态
GET /_replication/leader_cluster/follower-index/_status

// 响应包含元数据信息
{
  "leader_index": "follower-index",
  "follower_index": "follower-index",
  "metadata_syncing": true
}
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `metadata_sync_interval` | 元数据同步间隔 | 5s |
| `poll_interval` | 操作轮询间隔 | 1ms |
| `concurrent_readers_per_shard` | 并发读取数 | 1 |

## 性能影响分析

| metadata_sync_interval 设置 | 优点 | 缺点 |
|----------------------------|------|------|
| 1s | 快速响应变更 | Leader 负载高 |
| 5s（默认） | 平衡响应和负载 | - |
| 60s | Leader 负载低 | 响应慢 |

## 负载影响

```
负载影响分析

频繁轮询 (1s):
每个复制:
├── 每秒 1 次元数据请求
├── 100 个复制 = 100 请求/秒
├── Leader CPU: 高 ❌
└── 网络: 高


标准轮询 (5s, 默认):
每个复制:
├── 每 5 秒 1 次元数据请求
├── 100 个复制 = 20 请求/秒
├── Leader CPU: 适中 ✅
└── 网络: 适中


稀疏轮询 (60s):
每个复制:
├── 每 60 秒 1 次元数据请求
├── 100 个复制 = 1.7 请求/秒
├── Leader CPU: 低 ✅
└── 网络: 低


计算:
总请求/秒 = 复制数 / metadata_sync_interval
```

## 使用场景

## 推荐使用默认值的场景

- **标准部署**: 大多数生产环境
- **中等变更频率**: 元数据偶尔变更
- **平衡要求**: 平衡响应速度和负载

## 推荐减少间隔的场景

- **频繁元数据变更**: 设置、映射经常变更
- **快速响应要求**: 需要尽快应用元数据变更
- **小规模集群**: Leader 负载不是问题

## 推荐增加间隔的场景

- **元数据稳定**: 设置、映射很少变更
- **大规模集群**: 大量复制增加 Leader 负载
- **负载优化**: 减少 Leader 集群压力

## 注意事项

1. **默认值**: 新版本默认 `5s`，旧版本默认 `60s`。

2. **动态更新**: 可以动态更新，立即生效。

3. **最终一致性**: 元数据是最终一致的，有延迟。

4. **变更检测**: 只在有变更时才会应用。

5. **Leader 负载**: 减少间隔会增加 Leader 负载。

6. **网络开销**: 频繁同步会增加网络流量。

7. **与 poll_interval 区别**: poll_interval 用于操作，metadata_sync_interval 用于元数据。

8. **监控建议**: 监控元数据同步延迟。

9. **测试验证**: 调整后应验证同步效果。

10. **规模考虑**: 大规模集群应使用较长间隔。

## 最佳实践

```
元数据同步最佳实践

1. 标准部署
   metadata_sync_interval: 5s

   ├── 默认值
   ├── 快速响应
   └── 推荐 ✅


2. 频繁变更环境
   metadata_sync_interval: 1s

   ├── 实时响应
   ├── 元数据经常变更
   └── 小规模集群


3. 大规模集群
   metadata_sync_interval: 30s

   ├── 减少 Leader 负载
   ├── 大量复制
   └── 元数据稳定


4. 极低变更频率
   metadata_sync_interval: 60s

   ├── 稳定环境
   ├── 元数据几乎不变
   └── 最小负载


5. 配合其他配置
   ├── poll_interval: 操作轮询
   ├── metadata_sync_interval: 元数据轮询
   ├── 两者独立配置
   └── 综合优化
```

## 故障排查

```
常见问题排查

问题 1: 元数据变更未同步

检查:
├── metadata_sync_interval 设置
├── Leader 元数据版本
├── 同步日志
└── 复制状态


解决:
├── 减少 metadata_sync_interval
├── 检查网络连接
├── 查看 Leader 状态
└── 手动触发同步


问题 2: Leader 负载过高

检查:
├── metadata_sync_interval 设置
├── 复制数量
├── 请求频率
└── Leader CPU 使用


计算:
总请求/秒 = 复制数 / interval


解决:
├── 增加 metadata_sync_interval
├── 减少复制数量
├── 增加 Leader 节点
└── 优化配置


问题 3: 同步延迟过高

检查:
├── interval 设置
├── 网络延迟
├── 处理时间
└── 队列长度


解决:
├── 减少 metadata_sync_interval
├── 优化网络
├── 增加处理能力
└── 检查瓶颈
```