---
title: "清扫器执行周期配置"
date: 2026-01-22
lastmod: 2026-01-22
description: "jobscheduler.sweeper.period 配置项用于控制作业清扫器后台任务的执行周期。"
tags: ["作业调度", "后台任务", "定期扫描", "状态同步"]
summary: "配置项作用 #  jobscheduler.sweeper.period 配置项用于控制作业清扫器（Job Sweeper）后台清理任务的执行间隔。
清扫器负责定期扫描所有作业索引，同步作业状态，确保作业调度的准确性。当集群状态发生变化时，清扫任务会重新同步作业信息，保证调度器与实际作业文档状态一致。
配置项属性 #   配置路径: jobscheduler.sweeper.period 旧版路径: org.easysearch.jobscheduler.sweeper.period（已废弃） 数据类型: TimeValue（时间值） 默认值: 5m（5分钟） 最小值: 必须大于 0 是否可选: 是 作用域: NodeScope（节点级别） 动态更新: 是（支持动态更新）  配置项详解 #  工作机制 #  清扫器定时任务 period = 5m (默认): 00:00 ──→ 触发清扫 1 ├── 扫描作业索引 ├── 同步作业状态 ├── 重新调度作业 └── 完成清理 00:05 ──→ 触发清扫 2 00:10 ──→ 触发清扫 3 00:15 ──→ 触发清扫 4 ... 每个周期结束时触发下一次清扫 清扫器职责 #  Job Sweeper 的主要功能 1."
---


## 配置项作用

`jobscheduler.sweeper.period` 配置项用于控制**作业清扫器（Job Sweeper）后台清理任务的执行间隔**。

清扫器负责定期扫描所有作业索引，同步作业状态，确保作业调度的准确性。当集群状态发生变化时，清扫任务会重新同步作业信息，保证调度器与实际作业文档状态一致。

## 配置项属性

- **配置路径**: `jobscheduler.sweeper.period`
- **旧版路径**: `org.easysearch.jobscheduler.sweeper.period`（已废弃）
- **数据类型**: `TimeValue`（时间值）
- **默认值**: `5m`（5分钟）
- **最小值**: 必须大于 0
- **是否可选**: 是
- **作用域**: NodeScope（节点级别）
- **动态更新**: 是（支持动态更新）

## 配置项详解

## 工作机制

```
清扫器定时任务

period = 5m (默认):

00:00 ──→ 触发清扫 1
         ├── 扫描作业索引
         ├── 同步作业状态
         ├── 重新调度作业
         └── 完成清理
00:05 ──→ 触发清扫 2
00:10 ──→ 触发清扫 3
00:15 ──→ 触发清扫 4
...

每个周期结束时触发下一次清扫
```

## 清扫器职责

```
Job Sweeper 的主要功能

1. 全量扫描
   ├── 扫描所有作业索引
   ├── 获取所有作业文档
   └── 分页处理（使用 page_size）

2. 状态同步
   ├── 对比调度器状态和索引状态
   ├── 发现新增作业
   ├── 发现已删除作业
   └── 发现已修改作业

3. 重新调度
   ├── 新增作业 → 添加到调度队列
   ├── 修改作业 → 更新调度计划
   └── 删除作业 → 从调度队列移除

4. 集群变化响应
   ├── 监听集群状态变化
   ├── 触发增量清扫
   └── 确保调度一致性
```

## 定时任务创建

```
后台任务初始化

scheduledWithFixedDelay:
├── initialDelay: period
├── delay: period
├── task: sweepTask
└── threadPool: SAME

执行逻辑:
上一次清扫完成 ──→ 等待 period ──→ 下一次清扫开始
                           ↑
                           │
                    固定延迟执行
```

## 配置建议

## 生产环境（默认）

```yaml
jobscheduler:
  sweeper:
    period: 5m  # 默认值
```

**建议**: 保持默认值 `5m`。平衡及时性和资源消耗。

## 高负载环境

```yaml
jobscheduler:
  sweeper:
    period: 10m  # 增加周期
```

**建议**: 增加到 `10-15m`。集群负载高时使用，减少清扫频率。

## 快速同步需求

```yaml
jobscheduler:
  sweeper:
    period: 1m  # 减少周期
```

**建议**: 减少到 `1-2m`。需要快速同步作业状态时使用。

## 大规模集群

```yaml
jobscheduler:
  sweeper:
    period: 10m
    page_size: 500
```

**建议**: 增加周期到 `10m`，同时增加分页大小。

## 代码示例

## easysearch.yml 基础配置

```yaml
jobscheduler:
  sweeper:
    period: 5m
```

## 高负载配置

```yaml
jobscheduler:
  sweeper:
    period: 10m
    page_size: 200
  request_timeout: 30s
```

## 快速同步配置

```yaml
jobscheduler:
  sweeper:
    period: 1m
    page_size: 50
  request_timeout: 10s
```

## 动态更新配置

```json
PUT /_cluster/settings
{
  "transient": {
    "jobscheduler.sweeper.period": "10m"
  }
}
```

## 相关配置

| 配置项 | 作用 | 默认值 |
|--------|------|--------|
| `jobscheduler.sweeper.period` | 清扫周期 | 5m |
| `jobscheduler.sweeper.page_size` | 分页大小 | 100 |
| `jobscheduler.request_timeout` | 请求超时时间 | 10s |
| `jobscheduler.sweeper.backoff_millis` | 退避延迟时间 | 50ms |

## 性能影响分析

| period 设置 | 优点 | 缺点 |
|-------------|------|------|
| 1m | 快速同步 | CPU 使用率高 |
| 2-3m | 较快同步 | 中等 CPU 使用 |
| 5m（默认） | 平衡及时性和资源 | 标准设置 |
| 10m+ | CPU 使用率低 | 同步延迟大 |

## 资源消耗对比

```
假设每次清扫耗时 30 秒

period = 1m:
每小时清扫次数: 60 / 1 = 60 次
每小时清扫耗时: 60 × 30s = 30 分钟
CPU 使用率: 50% ❌


period = 5m (默认):
每小时清扫次数: 60 / 5 = 12 次
每小时清扫耗时: 12 × 30s = 6 分钟
CPU 使用率: 10% ✅


period = 10m:
每小时清扫次数: 60 / 10 = 6 次
每小时清扫耗时: 6 × 30s = 3 分钟
CPU 使用率: 5% ✅
```

## 使用场景

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

- **标准环境**: 集群规模适中，作业数量中等
- **平衡需求**: 平衡及时性和资源消耗
- **常规业务**: 作业变化频率不高

## 推荐增加周期的场景

- **高负载环境**: 集群 CPU 使用率高
- **大规模集群**: 作业数量很多（数万）
- **稳定业务**: 作业变化频率低
- **资源受限**: 节点资源紧张

## 推荐减少周期的场景

- **快速同步**: 需要快速同步作业状态
- **频繁变更**: 作业频繁创建/修改/删除
- **低负载环境**: 集群负载很低
- **关键任务**: 作业调度非常关键

## 与分页大小的配合

```
period 和 page_size 的协同

配置 1: 标准配置
period: 5m
page_size: 100
└── 每 5 分钟扫描一次，每次 100 条


配置 2: 大规模优化
period: 10m
page_size: 500
└── 减少扫描频率，增加每次扫描量


配置 3: 快速同步
period: 1m
page_size: 50
└── 增加扫描频率，减少每次扫描量
```

## 集群状态变化响应

```
清扫器的响应机制

正常清扫:
├── 按照周期定期执行
├── 全量扫描作业索引
└── 同步所有作业状态


集群状态变化:
├── 检测到集群变化
├── 立即触发增量清扫
├── 只扫描受影响的分片
└── 快速恢复调度一致性


周期清扫 + 增量清扫:
├── 周期清扫保证最终一致性
└── 增量清扫保证快速响应
```

## 动态更新影响

```
配置更新的影响

period: 5m → 10m

当前正在进行的清扫:
└── 继续执行，完成后等待 10m


已计划的清扫:
└── 取消原计划，按新周期执行


下一次清扫:
└── 等待 10m 后执行 ✅
```

## 注意事项

1. **默认值**: 默认值为 `5m`，适用于大多数场景。

2. **时间格式**: 支持 `1m`、`5m`、`1h` 等时间格式。

3. **动态更新**: 支持动态更新，修改后立即生效。

4. **固定延迟**: 使用 `scheduleWithFixedDelay`，上一次完成后等待固定时间。

5. **资源消耗**: 周期越短，CPU 和内存消耗越大。

6. **同步延迟**: 周期越长，作业状态同步延迟越大。

7. **与规模配合**: 大规模集群应增加周期。

8. **与分页配合**: 增加周期可同时增加分页大小。

9. **监控建议**: 监控清扫耗时和资源使用。

10. **测试验证**: 配置变更后应验证清扫效果。

## 索引管理模块的类似配置

```
其他模块的类似配置

索引生命周期管理 (ILM):
index_lifecycle_management.coordinator.sweep_period: 5m


索引状态管理 (ISM):
index_state_management.coordinator.sweep_period: 5m


作业调度器:
jobscheduler.sweeper.period: 5m


这些配置的作用类似，
都是控制后台清扫任务的执行周期。
```