版本：1.2

定时 Compaction

定时 Compaction 是 GreptimeDB 企业版功能，用于周期性地为集群中所有存在 leader 的物理 Region 提交 regular Compaction 请求。该功能运行在 leader Metasrv 上，根据 cron 表达式和 IANA 时区执行任务，并将最近的任务报告保存在 Metasrv KV backend 中。

该功能是 GreptimeDB 自动 Compaction 和手动 Compaction的补充。当你希望在固定的维护时间窗口内定期 Compaction 所有 Region 时，可以使用该功能。

配置 plugin

在 Metasrv 配置文件中添加 compaction_cronjob plugin：

[[plugins]]
[plugins.compaction_cronjob]
enable = true
timezone = "Asia/Shanghai"
cron = "0 0 0 * * *"
max_concurrent_regions = 4
compact_parallelism = 1
manual_trigger_cooldown_secs = 3600
max_history_jobs = 100

cron 表达式包含秒字段。例如，0 0 0 * * * 表示每天在所配置时区的午夜执行。

配置项	默认值	说明
`enable`	`false`	是否启用定时 Compaction。
`timezone`	本地 IANA 时区；无法检测时使用 `UTC`	计算 `cron` 时使用的时区，例如 `Asia/Shanghai`。
`cron`	`0 0 0 * * *`	Compaction 执行计划。
`max_concurrent_regions`	`4`	单个任务并发提交 Region Compaction 请求的最大数量，必须大于 `0`。
`compact_parallelism`	`1`	传递给每个 Region Compaction 请求的并行度，必须大于 `0`。
`manual_trigger_cooldown_secs`	`3600`	人工触发与最近一次任务之间的最小间隔。最近的任务可以是定时触发或人工触发。设置为 `0` 可禁用冷却时间；该配置不会延迟定时任务。
`max_history_jobs`	`100`	后续任务完成并执行历史清理后，Metasrv KV backend 中最多保留的终态任务报告数量，必须大于 `0`。

只有 leader Metasrv 会运行 scheduler。leader 发生切换后，新的 leader 会继续根据所配置的 cron 表达式调度后续任务。

新的 leader 会在启动 scheduler 前，将遗留在 running 状态的任务标记为 cancelled，并输出 warning 日志。该状态变更不会取消前一个 leader 已经提交的 Region 请求。cancelled 是终态，会在后续任务完成时按照 max_history_jobs 参与历史清理。

HTTP endpoints

该 plugin 会在 Metasrv HTTP server 上增加以下 endpoints。请将 <metasrv-http-address> 替换为 Metasrv 配置的 HTTP 地址。

触发任务

curl -X POST \
  "http://<metasrv-http-address>/admin/compaction_cronjob/trigger"

该请求必须发送到 leader Metasrv。请求会等待任务完成 Region Compaction 请求的提交，并返回任务报告。

请求发送到 follower Metasrv 时返回 409 Conflict。
人工触发距离最近一次定时或人工任务不足 manual_trigger_cooldown_secs 时返回 429 Too Many Requests。
其他错误返回 500 Internal Server Error。

查询指定任务

curl --get \
  --data-urlencode "job_id=2026-06-16T00:00:00+00:00" \
  "http://<metasrv-http-address>/admin/compaction_cronjob/job"

job_id 由触发任务和任务列表 endpoints 返回。它是 RFC 3339 时间戳，在请求中应进行 URL 编码。任务不存在时，该 endpoint 返回 404 Not Found。

查询最近任务

curl --get \
  --data-urlencode "limit=20" \
  "http://<metasrv-http-address>/admin/compaction_cronjob/jobs"

任务按计划执行时间倒序排列。可选参数 limit 的默认值为 20。

任务报告

触发和查询 endpoints 返回 JSON 格式的任务报告。以下是一个执行成功的任务报告：

{
  "job_id": "2026-06-16T00:00:00+00:00",
  "scheduled_at": "2026-06-16T00:00:00Z",
  "started_at": "2026-06-16T00:00:00.010Z",
  "finished_at": "2026-06-16T00:00:01.010Z",
  "status": "succeeded",
  "execution_result": {
    "total_regions": 8,
    "submitted_regions": 8,
    "failed_regions": []
  }
}

status 字段的取值可以是 "running"、"succeeded"、"partial_failed" 或 "cancelled"。失败任务的 status 值为 {"failed": "<reason>"}。execution_result 记录尝试提交和成功提交的 Region 请求数量，以及各 Region 的提交失败信息。

定时 Compaction

配置 plugin​

HTTP endpoints​

触发任务​

查询指定任务​

查询最近任务​

任务报告​