状态存储与恢复
概述
SeaTunnel Engine(Zeta)在作业执行过程中会持久化多类状态数据。了解每类数据的存储内容、存储位置和管理方式, 是在生产环境中稳定运行 CDC 或长期流处理作业的关键。
| 存储类别 | 用途 | 默认位置 |
|---|---|---|
| Checkpoint(检查点) | 流水线算子状态的容错快照 | seatunnel.yaml checkpoint.storage 配置路径 |
| Savepoint(保存点) | 用户手动触发的命名检查点,用于计划性停止或重启 | 与 Checkpoint 同一存储,位于所属作业自身的目录下 |
| IMap / MapStore | 分布式内存状态(作业元数据、作业状态、历史记录) | 默认仅存于内存;可通过 hazelcast.yaml 中的 Hazelcast MapStore 配置持久化 |
1. Checkpoint 存储
存储内容
Checkpoint 在某一时间点捕获所有流水线算子状态的一致性快照。对于 CDC 作业,包括:
- Binlog / WAL 偏移量(MySQL binlog 位置、PostgreSQL LSN、Oracle SCN)
- 并行 Reader 的 Split 级进度
- 2PC 写入事务状态(Doris、StarRocks、Kafka 事务 ID)
- 正在经过 Transform 的 SeaTunnelRow 缓冲区
存储路径结构
<namespace>/ # 配置的 namespace,默认 /seatunnel/checkpoint/
<job-id>/
<pipeline-id>/
<checkpoint-id>/
<task-location>/state-data
配置参考
seatunnel:
engine:
checkpoint:
interval: 300000 # 两次 Checkpoint 间隔(毫秒)
timeout: 60000 # Checkpoint 完成超时(毫秒)
storage:
type: hdfs # hdfs(通过 HDFS API 同时支持 S3、本地文件)| localfile(已废弃)
plugin-config:
namespace: /seatunnel/checkpoint/ # 必须以 / 结尾
# S3 示例:
# fs.s3a.endpoint: https://s3.amazonaws.com
# fs.s3a.access.key: <your-access-key>
# fs.s3a.secret.key: <your-secret-key>
# 环境变量凭据:
# fs.s3a.aws.credentials.provider: com.amazonaws.auth.EnvironmentVariableCredentialsProvider
Checkpoint 保留与清理
- Checkpoint 不受
history-job-expire-minutes管理,必须手动清理或配置独立保留策略。 - 每条流水线只保留最新 N 个 Checkpoint 的 Hazelcast 内存引用;作业异常终止时,旧目录可能残留在磁盘上。
- 默认情况下,被取消的作业仍会清理 Checkpoint 数据。如果希望取消后的作业还能从最新成功完成的 Checkpoint 恢复,需要在历史作业取消前将
作业
env中的checkpoint.retain-after-job-cancelled或seatunnel.yaml中的seatunnel.engine.checkpoint.retain-after-job-cancelled设置为true。 - 安全清理规则:只有在作业已取消且确认不会从该 Checkpoint 恢复时,才可删除对应 job-id 目录。
2. Savepoint(保存点)
Savepoint 与 Checkpoint 的区别
| 维度 | Checkpoint | Savepoint |
|---|---|---|
| 触发方式 | 周期性 / 自动 | 手动($SEATUNNEL_HOME/bin/seatunnel.sh --savepoint <jobId>) |
| 用途 | 容错恢复 | 计划性停止、升级、迁移 |
| 生命周期 | 引擎管理 | 操作人员管理 |
| 保留策略 | 自动轮转 | 手动删除前永久保留 |
触发 Savepoint
# 停止运行中的作业并创建 Savepoint
$SEATUNNEL_HOME/bin/seatunnel.sh --savepoint <job-id>
# 或通过 REST API v2
curl -X POST http://<master>:8080/stop-job \
-H 'Content-Type: application/json' \
-d '{
"jobId": <job-id>,
"isStopWithSavePoint": true,
"force": false
}'
从 Savepoint 恢复
# 提交时携带 --restore 从最新 Savepoint 恢复
$SEATUNNEL_HOME/bin/seatunnel.sh --config job.conf --restore <job-id>
从最新成功完成的 Checkpoint 恢复
# 提交时携带 --restore-with-checkpoint,从历史作业的最新成功完成 Checkpoint 恢复。
# 新一次运行会生成新的运行时 jobId。
$SEATUNNEL_HOME/bin/seatunnel.sh --config job.conf --restore-with-checkpoint <job-id>
Savepoint 路径结构
Savepoint 是保存点类型的 Checkpoint:它写入上文配置的同一个 Checkpoint 存储中,位于所属作业的目录下
(<namespace>/<job-id>/)。不存在独立的 savepoint 根目录。
安全清理
只有在确认永不从该 Savepoint 恢复作业时,才可删除。恢复过程中删除 Savepoint 会导致作业以"状态未找到"错误失败。
3. IMap 与 MapStore(Hazelcast 分布式状态)
IMap 存储的内容
SeaTunnel Engine 使用 Hazelcast IMap 作为分布式内存键值存储。引擎使用的主要逻辑映射包括:
| IMap 名称 | 内容 |
|---|---|
engine_runningJobInfo | 已提交作业的信息与初始化元数据(作业 ID、作业名称等;指标在作业完成后存于 engine_finishedJobMetrics) |
engine_runningJobState | 运行中作业和流水线的状态机当前状态 |
engine_stateTimestamps | 作业 / 流水线状态流转的时间戳 |
engine_finishedJobState | 已完成、已取消或失败作业的终态 |
engine_finishedJobMetrics | 作业终止后的最终指标快照 |
engine_finishedJobVertexInfo | 已完成作业的执行节点信息 |
MapStore(磁盘持久化)
默认情况下 IMap 数据仅存储在内存中(并按备份份数在节点间复制)。如果所有节点停止,数据将丢失, 除非启用了 MapStore 持久化。启用后,Hazelcast MapStore 会将 IMap 条目写入外部文件系统(HDFS、S3, 或通过 HDFS API 访问的本地文件),使数据在整个集群重启后仍然可用。这与 Checkpoint 存储相互独立。
持久化在 hazelcast.yaml 中配置(详见Zeta 集群分离式部署):
map:
engine*:
map-store:
enabled: true
initial-mode: EAGER
factory-class-name: org.apache.seatunnel.engine.server.persistence.FileMapStoreFactory
properties:
type: hdfs
namespace: /tmp/seatunnel/imap # 存储 namespace(未设置时默认 /seatunnel-imap)
clusterName: seatunnel-cluster
storage.type: hdfs
fs.defaultFS: hdfs://localhost:9000
在分离式集群模式下,只有 Master 节点存储 IMap 数据,因此该配置仅在 Master 节点生效。
IMap、MapStore 与 Checkpoint 的关系
Checkpoint 存储 <──────────────────────────────────> 算子状态(偏移量、Split)
IMap / MapStore <──────────────────────────────────> 作业 / 流水线生命周期状态
二者完全独立。删除 Checkpoint 存储不影响 IMap;反之亦然。 作业可以从 Checkpoint 恢复,即使 IMap MapStore 数据已被清除——但作业 ID 和流水线映射需要重新提交, 因为运行作业的状态已丢失。
4. MapStore 文件维护
IMap 持久化是一种追加写(append-only)的预写日志:FileMapStore 委托 IMapFileStorage,通过 WAL
写入器把每次状态变更追加到配置的 namespace 目录下的 region 文件中。所有作业的记录都追加到同一批
region 文件里,因此只要作业持续运行,这些文件就会不断增长。
缓解措施:
- 让已完成作业按期过期:
history-job-expire-minutes会将已完成作业的记录从 IMap 中移除, 使其不再被持久化。 - 在 Master 节点上监控 namespace 目录:
du -sh /tmp/seatunnel/imap/ # 替换为你在 hazelcast.yaml 中配置的 namespace(本地文件存储,即 fs.defaultFS 以 file:/// 开头时)
hadoop fs -du -s -h <fs-uri>/<namespace> # HDFS 或对象存储后端使用该命令查看
不要按作业选择性地删除 MapStore 文件:并不存在按作业划分的文件,手工删除文件可能损坏下次 Master 启动时的 IMap 重放。正确做法是为 namespace 卷规划足够的容量;只有当集群停止、且可以接受 丢失所有运行中作业的 IMap 状态时,才整体清空 namespace。
5. 历史作业过期
history-job-expire-minutes 的作用范围
seatunnel:
engine:
history-job-expire-minutes: 1440 # 24 小时
| 操作 | 是否受过期影响 |
|---|---|
从 engine_finishedJobState IMap 中移除 | 是 |
从 engine_finishedJobMetrics IMap 中移除 | 是 |
| 集群重启后作业仍保持已移除(启用 IMap 持久化时) | 是(过期时间随条目一起持久化,已过期的作业不会被重新加载,尚未过期的作业保留剩余时间) |
| 删除该作业的 MapStore 持久化文件 | 否(过期记录仍保留在 IMap 存储文件中) |
| 删除 Checkpoint 存储目录 | 否 |
| 删除 Savepoint 数据 | 否 |
核心结论:history-job-expire-minutes 仅清理已完成作业 IMap 中的作业元数据。
HDFS / S3 / 本地的 Checkpoint 和 Savepoint 目录不受此配置影响,必须独立管理。
6. 长期运行 CDC 作业的容量规划
Checkpoint 大小估算
| 来源 | 单次 Checkpoint 典型大小 |
|---|---|
| MySQL CDC(1 张表,低流量) | 1–10 KB(binlog 偏移量 + Split 状态) |
| MySQL CDC(多表,100 个 Split) | 100 KB – 1 MB |
| MySQL CDC(全量快照阶段) | 10–500 MB(快照 Split 状态) |
| PostgreSQL CDC(逻辑复制) | 每张表 1–50 KB |
| Oracle CDC(LogMiner) | 50 KB – 2 MB |
公式:checkpoint_size ≈ 表数量 × 平均 Split 数 × 每 Split 状态大小(同一时刻只有一个 Checkpoint 在途,因此无需乘并发系数)
存储容量经验值
每个作业至少保留 3 个 Checkpoint,建议分配:
所需存储 = checkpoint_size × 3 × 安全系数(1.5)
IMap 存储容量估算
每个运行中的 CDC 作业大约占用:
- 作业状态:每条流水线约 50–200 字节
- 指标:每次指标刷新每条流水线约 1–2 KB
对于运行 100 个 CDC 作业的集群,IMap 数据量在几 MB 量级。MapStore namespace 的磁盘占用随状态 流转历史增长,长期运行的集群建议规划数 GB 空间,并使用以下命令持续监控:
du -sh /tmp/seatunnel/imap/ # 替换为你配置的 MapStore namespace(本地文件存储场景)
hadoop fs -du -s -h <fs-uri>/<namespace> # HDFS 或对象存储后端使用该命令查看
7. 故障排查
Checkpoint 目录持续增长
现象:HDFS / S3 用量持续增加,即使作业已完成。
诊断:
# 列出各作业 ID 的 Checkpoint 目录
hadoop fs -ls /seatunnel/checkpoint/
# 或本地存储
ls -lh /tmp/seatunnel/checkpoint/
根因:SeaTunnel 没有内置 Checkpoint 目录 TTL。每次新 Checkpoint 都会新增目录;仅当作业正常完成且 状态被轮转出时,旧目录才会被清除。
修复:
- 通过 REST API v2 查询已完成作业元数据:
curl "http://<master>:8080/finished-jobs/FINISHED?page=1&rows=100"
curl "http://<master>:8080/finished-jobs/CANCELED?page=1&rows=100"
curl "http://<master>:8080/finished-jobs/FAILED?page=1&rows=100"
curl "http://<master>:8080/finished-jobs/SAVEPOINT_DONE?page=1&rows=100"
curl "http://<master>:8080/finished-jobs/UNKNOWABLE?page=1&rows=100" - 响应中不包含的 job-id,其 Checkpoint 目录为孤立目录,可安全删除。
MapStore namespace 目录增长
现象:配置的 MapStore namespace 目录占满 Master 节点磁盘。
诊断:
du -sh /tmp/seatunnel/imap/ # 替换为你在 hazelcast.yaml 中配置的 namespace(本地文件存储,即 fs.defaultFS 以 file:/// 开头时)
hadoop fs -du -s -h <fs-uri>/<namespace> # HDFS 或对象存储后端使用该命令查看
可能根因:
- 已完成作业未过期(
history-job-expire-minutes未设置或过大) - 运行中作业过多,状态和指标持续更新
修复:
在 seatunnel.yaml 中启用 / 调整 history-job-expire-minutes。MapStore 的 region 文件无法按作业
裁剪;要回收其空间需要停止集群并整体清空 namespace,这会丢弃所有作业的 IMap 状态。
重启时出现"状态未找到"错误
现象:作业重启后立即失败,提示 checkpoint state not found 或 restore pipeline state failed。
原因:Checkpoint 目录已被删除,或存储路径已变更。
修复:
- 确认
seatunnel.yaml中的 Checkpoint 路径与实际存储位置一致。 - 如果 Checkpoint 已不存在,以全新方式提交作业(不带
--restore)。对于 CDC 作业,需决定:startup.mode=initial:重新全量快照startup.mode=latest:跳过已错过的数据
安全清理检查清单
删除任何状态目录前,请确认:
- 作业已处于
FINISHED、CANCELED或FAILED终态 - 确认不会从该 Checkpoint 或 Savepoint 恢复
- 确认该作业 ID 未被任何监控或告警规则引用
- Checkpoint 存储:递归删除
<namespace>/<job-id>/ - MapStore 数据:仅支持整体清空 namespace(先停止集群),不支持按作业选择性删除
参考
- Checkpoint 存储配置
- REST API v2 — 通过 API 查询作业状态和指标