Apache SeaTunnel 配置参数详解

目标：详解 Apache SeaTunnel 2.3.12 Zeta 引擎的核心配置——config/seatunnel.yaml（引擎槽位、检查点、遥测、REST）、config/hazelcast*.yaml（集群发现与客户端接入）、config/jvm_*_options（各角色 JVM 堆 256-512MB）与作业配置的 env/source/sink 段，并给出可直接套用的生产模板。默认值与生效验证均基于真实环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Apache SeaTunnel：2.3.12（Zeta 引擎，官方二进制包）
• 安装目录：/opt/seatunnel
• 配置文件目录：/opt/seatunnel/config
• 端口：5801（集群通信）、8080（REST/HTTP API）
• JVM 堆：-Xms256m -Xmx512m（config/jvm_options 修改后 ps -ef 实测生效）

二、前置条件

• 已按《Apache SeaTunnel 安装指南》完成 2.3.12 安装，配置目录为 /opt/seatunnel/config。
• 配置修改后需重启引擎（systemctl restart seatunnel-cluster.service 或重启进程）才生效；作业级配置（env 段）在每次提交时生效，无需重启。

三、参数查看与修改方式

配置文件全部位于 /opt/seatunnel/config/，角色划分如下（2.3.12 实测 ls 回显）：

hazelcast-client.yaml  hazelcast-master.yaml  hazelcast-worker.yaml  hazelcast.yaml
jvm_client_options  jvm_master_options  jvm_options  jvm_worker_options
log4j2.properties  log4j2_client.properties  plugin_config
seatunnel-env.cmd  seatunnel-env.sh  seatunnel.yaml
v2.batch.config.template  v2.streaming.conf.template

查看当前生效参数的推荐方法：

# 引擎配置（去注释）
grep -v '^#' /opt/seatunnel/config/seatunnel.yaml | grep -v '^$'
# JVM 实际生效堆
ps -ef | grep [S]eaTunnelServer | grep -o 'Xmx[0-9]*m'
# 引擎版本与集群概况（REST）
curl -s http://localhost:8080/overview/

/overview/ 实测回显：

{"projectVersion":"2.3.12","gitCommitAbbrev":"aa70e2d","totalSlot":"0","unassignedSlot":"0","runningJobs":"0","finishedJobs":"1","failedJobs":"0","cancelledJobs":"0","workers":"1"}

四、参数总览

五、核心参数分类详解

5.1 seatunnel.yaml 引擎参数

2.3.12 发行版默认值（实测，去 license 头）：

seatunnel:
  engine:
    classloader-cache-mode: true
    history-job-expire-minutes: 1440
    backup-count: 1
    queue-type: blockingqueue
    print-execution-info-interval: 60
    print-job-metrics-info-interval: 60
    slot-service:
      dynamic-slot: true
    checkpoint:
      interval: 10000
      timeout: 60000
      storage:
        type: hdfs
        max-retained: 3
        plugin-config:
          namespace: /tmp/seatunnel/checkpoint_snapshot
          storage.type: hdfs
          fs.defaultFS: file:///tmp/ # Ensure that the directory has written permission
    telemetry:
      metric:
        enabled: false
      logs:
        scheduled-deletion-enable: true
    http:
      enable-http: true
      port: 8080
      enable-dynamic-port: false
      # enable-basic-auth: true
      # basic-auth-username: admin
      # basic-auth-password: admin

5.1.1 classloader-cache-mode

类加载器缓存开关，true 时复用已加载的连接器类加载器，降低大作业的内存与启动开销。单机小内存环境保持默认 true 即可。

5.1.2 history-job-expire-minutes

已完成作业的历史信息保留时长（分钟），默认 1440（24 小时）。过期后 -l、--get-job-info 查不到该作业。

5.1.3 backup-count

集群内每个检查点/作业元数据的备份数。单节点固定为 1；三节点生产集群建议 2（允许坏一个节点）。

5.1.4 queue-type

内部阻塞队列实现，默认 blockingqueue。一般无需修改。

5.1.5 print-execution-info-interval / print-job-metrics-info-interval

执行信息与作业指标的周期性打印间隔（秒），默认均为 60。仅影响日志输出频率，不影响性能。

5.1.6 slot-service.dynamic-slot

true 为动态槽位（按需分配，不设总数）；设为 false 时用 slot-num 固定每节点槽位数。动态槽位配合 /overview/ 的 totalSlot/unassignedSlot 观察（实测默认输出 totalSlot: 0）。

5.1.7 checkpoint.interval / timeout

检查点间隔与超时（毫秒），默认 10000/60000。流作业调大 interval 可降低快照压力；timeout 需大于 interval。

5.1.8 checkpoint.storage

• type: hdfs：使用 Hadoop FS 兼容存储插件（本地文件系统也算，fs.defaultFS: file:/// 前缀）。
• max-retained: 3：每作业最多保留 3 份快照，配合 savepoint/恢复使用。
• plugin-config.namespace：快照根目录，默认 /tmp/seatunnel/checkpoint_snapshot。
• fs.defaultFS: file:///tmp/：默认本地 /tmp，重启即丢。生产改为真实 HDFS（hdfs://namenode:8020）或持久盘本地路径（file:///data/seatunnel/checkpoint）。

5.1.9 telemetry

metric.enabled 开启内部指标采集（配合 Prometheus 遥测），默认 false；logs.scheduled-deletion-enable: true 定期清理过期日志。

5.1.10 http（REST 服务）

开启 Basic 认证的生产示例（示例账号 admin，密码 q1w2e3r4）：

    http:
      enable-http: true
      port: 8080
      enable-basic-auth: true
      basic-auth-username: admin
      basic-auth-password: q1w2e3r4

5.2 hazelcast 集群发现参数

config/hazelcast.yaml 默认有效段（实测，去注释）：

hazelcast:
  cluster-name: seatunnel
  network:
    rest-api:
      enabled: false
      endpoint-groups:
        CLUSTER_WRITE:
          enabled: true
        DATA:
          enabled: true
    join:
      tcp-ip:
        enabled: true
        member-list:
          - localhost
    port:
      auto-increment: false
      port: 5801
  properties:
    hazelcast.invocation.max.retry.count: 20
    hazelcast.tcp.join.port.try.count: 30
    hazelcast.logging.type: log4j2
    hazelcast.operation.generic.thread.count: 50
    hazelcast.heartbeat.failuredetector.type: phi-accrual
    hazelcast.heartbeat.interval.seconds: 2
    hazelcast.max.no.heartbeat.seconds: 180
    hazelcast.heartbeat.phiaccrual.failuredetector.threshold: 10
    hazelcast.heartbeat.phiaccrual.failuredetector.sample.size: 200
    hazelcast.heartbeat.phiaccrual.failuredetector.min.std.dev.millis: 100

• cluster-name: seatunnel：集群名，必须与 hazelcast-client.yaml 一致，否则客户端报集群找不到。
• network.join.tcp-ip.member-list：节点发现列表，多节点时逐个写入对端主机名。
• network.port.port: 5801 + auto-increment: false：固定端口；同一台机器跑多节点时改 auto-increment: true 并加 port-count。
• 心跳组参数（interval 2s、180s 无心跳判死、phi-accrual 阈值 10）：网络抖动大的机房可调大 max.no.heartbeat.seconds，避免误踢节点。

客户端 config/hazelcast-client.yaml 默认有效段（实测）：

hazelcast-client:
  cluster-name: seatunnel
  properties:
    hazelcast.logging.type: log4j2
  connection-strategy:
    connection-retry:
      cluster-connect-timeout-millis: 3000
  network:
    cluster-members:
      - localhost:5801

远程提交作业时把 cluster-members 改为集群节点地址列表，例如 - 192.168.10.11:5801 与 - 192.168.10.12:5801 逐行列出。

5.3 JVM 参数（jvm_*_options）

四个文件按角色读取：默认 -r master_and_worker（即不带 -r 参数启动）读 jvm_options；-r master 读 jvm_master_options；-r worker 读 jvm_worker_options；客户端读 jvm_client_options。

默认值（实测）：

把服务端堆收紧到 256-512MB（实测改法与验证）：

sed -i "s/^-XX:MaxMetaspaceSize=2g$/-Xms256m\n-Xmx512m\n-XX:MaxMetaspaceSize=256m/" /opt/seatunnel/config/jvm_options
systemctl restart seatunnel-cluster.service
ps -ef | grep [S]eaTunnelServer | grep -o 'Xmx512m'

实测回显：

Xmx512m

⚠️ 每行一个参数、# 开头为注释；文件不支持 export 前缀。堆建议 256-512MB 起步，按连接器实际负载上调。

5.4 作业配置（env/source/transform/sink）

批量作业模板 config/v2.batch.config.template 有效段（实测）：

env {
  parallelism = 2
  job.mode = "BATCH"
  checkpoint.interval = 10000
}

source {
  FakeSource {
    parallelism = 2
    plugin_output = "fake"
    row.num = 16
    schema = {
      fields {
        name = "string"
        age = "int"
      }
    }
  }
}

sink {
  Console {
  }
}

• env.parallelism：作业全局并行度，实测 row.num=16、source parallelism=2 时统计 Read Count=32（16×2）。
• env.job.mode：BATCH 跑完即 FINISHED；改 STREAMING 后作业常驻 RUNNING，可用 savepoint/cancel 管理（实测）。
• source.plugin_output / sink.plugin_input：上下游数据链路命名。上游配了 plugin_output 而下游未配 plugin_input 时引擎打 WARN：A source/transform(FakeSource) is configured with 'plugin_output' option value of 'fake', but subsequent transform/sink(Console) is not configured with 'plugin_input' option.（2.3.12 实测，链路命名提示不影响执行，详见《Apache SeaTunnel 安装指南》常见问题）。
• source.row.num、schema.fields：FakeSource 生成行数与字段类型（name=string、age=int，实测 Console 输出 output rowType: name<STRING>, age<INT>）。

六、生产配置模板

适用场景：3 节点 Zeta 集群、每节点 16GB 内存、NVMe SSD、日均数百个中大型批/流作业。要点：固定槽位便于容量规划、检查点落共享存储、REST 开启 Basic 认证（示例账号 admin，密码 q1w2e3r4）、JVM 堆 4GB。

seatunnel:
  engine:
    classloader-cache-mode: true
    history-job-expire-minutes: 1440
    backup-count: 2
    queue-type: blockingqueue
    print-execution-info-interval: 60
    print-job-metrics-info-interval: 60
    slot-service:
      dynamic-slot: false
      slot-num: 8
    checkpoint:
      interval: 30000
      timeout: 120000
      storage:
        type: hdfs
        max-retained: 5
        plugin-config:
          namespace: /data/seatunnel/checkpoint_snapshot
          storage.type: hdfs
          fs.defaultFS: file:///data/seatunnel/checkpoint
    telemetry:
      metric:
        enabled: true
      logs:
        scheduled-deletion-enable: true
    http:
      enable-http: true
      port: 8080
      enable-dynamic-port: false
      enable-basic-auth: true
      basic-auth-username: admin
      basic-auth-password: q1w2e3r4

配套 JVM（config/jvm_options）：

-Xms4g
-Xmx4g
-XX:MaxMetaspaceSize=1g
-XX:+UseG1GC
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/data/seatunnel/dump

配套发现（config/hazelcast.yaml 的 member-list，逐个列出）：

    join:
      tcp-ip:
        enabled: true
        member-list:
          - node1
          - node2
          - node3

⚠️ 单机 2GB 内存场景请沿用安装指南的 256-512MB 堆；上表 4GB 堆模板需 16GB 内存节点。fs.defaultFS 指向的目录必须预先创建并保证写权限。

七、常见问题

Q1：改了 seatunnel.yaml 不生效？ 引擎参数随进程启动加载，必须重启：systemctl restart seatunnel-cluster.service。作业级 env 参数每次提交时读取，无需重启。

Q2：客户端报集群连接失败？ 检查三点：hazelcast-client.yaml 的 cluster-members 地址与端口能否 telnet 通；cluster-name 是否与服务端一致；服务端 5801 是否监听（netstat -tlnp | grep 5801）。实测正常监听形态：tcp6 0 0 :::5801 :::* LISTEN <pid>/java。

Q3：堆参数改了但 ps 看到的还是旧值？ 确认修改的文件与启动角色匹配（默认角色读 jvm_options 而非 jvm_master_options），并确认引擎真的重启过（ps -ef | grep [S]eaTunnelServer 的启动时间）。

Q4：REST 8080 想换端口或加认证？ seatunnel.engine.http.port 改端口；enable-basic-auth: true 加认证后，curl 需带 curl -u admin:q1w2e3r4 访问。

Q5：检查点目录写满或重启后作业恢复失败？ 默认 fs.defaultFS: file:///tmp/ 重启即丢。生产把 namespace 与 fs.defaultFS 指到持久盘或 HDFS（见第六节模板），并确认目录写权限。

八、参考链接

• 引擎配置官方文档：https://seatunnel.apache.org/docs/2.3.12/seatunnel-engine
• Zeta 引擎检查点：https://seatunnel.apache.org/docs/2.3.12/seatunnel-engine/checkpoint-storage
• REST API v2：https://seatunnel.apache.org/docs/2.3.12/seatunnel-engine/rest-api-v2
• 作业配置规范：https://seatunnel.apache.org/docs/2.3.12/configuration/config-file