SeaTunnel Zeta 引擎 Hybrid 模式单机部署指南

概述

本文档介绍如何在 单台 Ubuntu 24.04 虚拟机上以 Zeta 引擎 Hybrid 模式 部署 Apache SeaTunnel，单节点同时承担 Master 调度和 Worker 执行职责。

架构说明

┌─────────────────────────────────────────┐
│         Ubuntu 24.04 虚拟机              │
│          192.168.192.131                │
├─────────────────────────────────────────┤
│                                         │
│   ┌─────────────────────────────────┐   │
│   │   SeaTunnel Zeta 引擎            │   │
│   │   Hybrid 模式                    │   │
│   │                                 │   │
│   │   ┌──────────┐ ┌───────────┐   │   │
│   │   │  Master  │ │  Worker   │   │   │
│   │   │ (调度)   │ │  (执行)   │   │   │
│   │   └──────────┘ └───────────┘   │   │
│   │                                 │   │
│   │   端口: 5801 (Engine)           │   │
│   │   端口: 8080 (Web UI)           │   │
│   └─────────────────────────────────┘   │
│                                         │
│   /opt/seatunnel/     安装目录           │
│   /data/seatunnel/    数据目录           │
│   /var/log/seatunnel/ 日志目录           │
└─────────────────────────────────────────┘

单节点对等架构：一台机器同时扮演 Master 和 Worker 角色
Zeta 引擎：SeaTunnel 自研引擎，Hybrid 模式下调度和执行在同一进程内完成
操作系统：Ubuntu 24.04 LTS
部署模式：Zeta 引擎 Hybrid (混合) 单机模式

Hybrid 模式 vs 传统分离模式（单机场景）

特性	Hybrid 单机模式	传统分离单机模式
部署复杂度	⭐⭐⭐⭐⭐ 一条命令启动	⭐⭐⭐ 需分别启动 Master 和 Worker
配置复杂度	⭐⭐⭐⭐⭐ 一份配置文件搞定	⭐⭐ 两份配置，需区分角色
资源利用率	⭐⭐⭐⭐⭐ 单进程复用资源	⭐⭐⭐ 两个进程，存在开销
运维简便	⭐⭐⭐⭐⭐ 一个 service 管理	⭐⭐ 两个 service 分别管理
适用场景	开发/测试/小型生产环境	仅需 Worker 执行时

一、环境准备

步骤 1：更新系统软件源

# 更新软件包列表
sudo apt update

# 升级已安装的软件包（可选但推荐）
sudo apt upgrade -y

步骤 2：配置主机名

# 设置主机名（多环境部署时请区分，如 seatunnel-sit、seatunnel-uat）
sudo hostnamectl set-hostname seatunnel-node1

# 验证
hostname
# 应输出：seatunnel-node1

步骤 3：配置防火墙

# 开放 SeaTunnel 所需端口
sudo ufw allow 8080/tcp   # Web UI 和 REST API
sudo ufw allow 5801/tcp   # Hazelcast 集群通信（扩展多节点时需要）

# 验证配置
sudo ufw status
# 预期输出：
# Status: active
# To     Action  From
# 22/tcp  ALLOW   Anywhere
# 5801/tcp ALLOW  Anywhere
# 8080/tcp ALLOW  Anywhere

步骤 4：安装 OpenJDK 17

# 安装 OpenJDK 17
sudo apt install -y openjdk-17-jdk

# 验证安装
java -version
# 应输出类似：openjdk version "17.0.x" ...

# 配置 JAVA_HOME 环境变量（tee 会自动创建 /etc/profile.d/seatunnel.sh）
cat <<'EOF' | sudo tee /etc/profile.d/seatunnel.sh
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH
EOF

# 使配置生效
source /etc/profile.d/seatunnel.sh

# 验证
env | grep JAVA_HOME

步骤 5：创建必要的目录结构

# 1. 创建安装目录（存放 SeaTunnel 程序）
sudo mkdir -p /opt/seatunnel

# 2. 创建数据目录（存放 Checkpoint 和 Savepoint）
sudo mkdir -p /data/seatunnel/{checkpoint,savepoint,tmp}

# 3. 创建日志目录（存放运行日志）
sudo mkdir -p /var/log/seatunnel

# 4. 设置目录权限
sudo chown -R $USER:$USER /opt/seatunnel /data/seatunnel /var/log/seatunnel

# 5. 验证目录结构
ls -lh /opt/seatunnel
ls -lh /data/seatunnel/
ls -lh /var/log/seatunnel

目录用途说明：

目录路径	用途	空间建议
`/opt/seatunnel/`	SeaTunnel 程序安装目录	10GB
`/data/seatunnel/checkpoint/`	Checkpoint 数据存储	50-100GB
`/data/seatunnel/savepoint/`	Savepoint 数据存储	20-50GB
`/data/seatunnel/tmp/`	临时文件和缓存	20GB
`/var/log/seatunnel/`	日志文件	20GB

磁盘空间参考：

目录	建议空间	说明
`/opt/seatunnel/`	10 GB	程序文件 + 插件 + 临时文件
`/data/seatunnel/`	50-100 GB	Checkpoint + Savepoint
`/var/log/seatunnel/`	20 GB	日志文件
总计	80-130 GB	建议使用 SSD 硬盘

二、下载并安装 SeaTunnel

# 下载安装包
cd /tmp
wget https://dlcdn.apache.org/seatunnel/2.3.13/apache-seatunnel-2.3.13-bin.tar.gz

# 解压到安装目录（文件在当前目录 /tmp 下）
sudo tar -xzf apache-seatunnel-2.3.13-bin.tar.gz -C /opt/seatunnel --strip-components=1

# 验证安装
ls -lh /opt/seatunnel/
# 应看到 bin/, config/, lib/, connectors/ 等目录

安装 Connector 插件

SeaTunnel 的 Connector 需要单独下载，安装包只包含少量基础插件。

方式 1：安装全部插件（简单）

# 编辑插件配置，列出需要的 Connector
vim /opt/seatunnel/config/plugin_config

文件内容示例（根据实际需求增删）：

# Source Connectors
connector-fake
connector-jdbc
connector-kafka
connector-mongodb
connector-hbase

# Sink Connectors
connector-console
connector-jdbc
connector-clickhouse
connector-doris
connector-elasticsearch

# Transform
connector-copy
connector-sql

默认的 plugin_config 已经列出了常见 Connector，可直接使用，无需修改。

配置 Maven 国内镜像（加速下载）

install-plugin.sh 底层用 Maven 从 repo.maven.apache.org 下载 jar 包，国内下载慢容易超时。先配置阿里云镜像：

mkdir -p ~/.m2

cat > ~/.m2/settings.xml <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <mirrors>
    <mirror>
      <id>aliyun</id>
      <mirrorOf>central</mirrorOf>
      <name>Aliyun Maven</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>
EOF

# 验证
cat ~/.m2/settings.xml

注意：maven-wrapper.properties 中的阿里云镜像地址只控制 Maven 工具本身的下载，不管 jar 包依赖。配置 ~/.m2/settings.xml 才是正确方式。

执行安装：

# 安装插件
/opt/seatunnel/bin/install-plugin.sh

# 验证已安装的插件
ls /opt/seatunnel/connectors/

方式 2：安装指定插件

# 安装单个 Connector
/opt/seatunnel/bin/install-plugin.sh connector-fake

# 安装多个 Connector
/opt/seatunnel/bin/install-plugin.sh \
  connector-fake \
  connector-console \
  connector-jdbc \
  connector-kafka \
  connector-doris

注意：首次安装插件需要联网，耗时取决于网络速度。如果服务器无法访问外网，需要在有网的机器上下载后上传到 plugins/ 目录。不同版本 SeaTunnel 对应的 Connector 版本不同，切勿混用。

三、Hybrid 模式配置

单机 Hybrid 模式下，Master 和 Worker 运行在同一进程内，只需一份配置文件。

步骤 1：配置 Hazelcast 集群通信

Hazelcast 配置在独立文件 config/hazelcast.yaml 中。DolphinScheduler 在另一台机器，需要把 localhost 改成服务器实际 IP：

vim /opt/seatunnel/config/hazelcast.yaml

找到 member-list 行，将 localhost 改为服务器 IP：

hazelcast:
  cluster-name: seatunnel
  network:
    rest-api:
      enabled: false
      endpoint-groups:
        CLUSTER_WRITE:
          enabled: true
        DATA:
          enabled: true
    join:
      tcp-ip:
        enabled: true
        # 改为服务器实际 IP，否则 DolphinScheduler 连不上
        member-list:
          - 192.168.192.131
    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

步骤 2：修改引擎配置

vim /opt/seatunnel/config/seatunnel.yaml

在默认配置基础上，只改以下 3 处：

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: 300000            # 改：10s → 5min，降低 I/O
      timeout: 60000
      storage:
        type: hdfs                # 不用改，hdfs + file:// 等价于本地存储
        max-retained: 3
        plugin-config:
          namespace: /data/seatunnel/checkpoint       # 改：/tmp → /data，持久化
          storage.type: hdfs
          fs.defaultFS: file:///data/seatunnel/      # 改：/tmp → /data
    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: "admin123"       # 取消注释

改动说明：

改了什么	默认值	原因
`checkpoint.interval`	`10000`	10 秒太频繁，5 分钟够用
`namespace` / `fs.defaultFS`	`/tmp/`	`/tmp` 重启就没了，换 `/data`
`http.enable-basic-auth`	注释掉	取消注释，启用认证

配置修改总结

文件	配置项	默认值	改什么
`hazelcast.yaml`	`member-list`	`localhost`	改为服务器 IP，DS 才能跨机器连接
`seatunnel.yaml`	`checkpoint.interval`	`10000`	`300000`，降低磁盘 I/O
`seatunnel.yaml`	`namespace` + `fs.defaultFS`	`/tmp/`	`/data/seatunnel/`，重启不丢失
`seatunnel.yaml`	`enable-basic-auth`	注释掉	取消注释，启用认证

其余配置保持不变。

在 vim 中操作

按 i 进入插入模式，编辑内容
按 Esc 退出插入模式
输入 :wq 保存并退出

可选：使用 S3 存储 Checkpoint

如果后续需要扩展为多节点集群，可以将 Checkpoint 切换到 S3：

# seatunnel.yaml 中 checkpoint 部分改为：
checkpoint:
  storage:
    type: s3
    max-retained: 3
    plugin-config:
      storage.type: s3
      namespace: "/seatunnel/checkpoint"
      s3.bucket: "s3a://your-checkpoint-bucket"
      fs.defaultFS: "s3a://your-checkpoint-bucket"
      fs.s3a.endpoint: "http://192.168.192.111:9000"
      fs.s3a.path.style.access: true
      fs.s3a.access.key: "your-access-key"
      fs.s3a.secret.key: "your-secret-key"
      fs.s3a.aws.credentials.provider: org.apache.hadoop.fs.s3a.SimpleAWSCredentialsProvider

四、启动服务

方式 1：前台启动（适合调试）

cd /opt/seatunnel
./bin/seatunnel.sh

按 Ctrl + C 可停止。

方式 2：后台启动（简单实用）

cd /opt/seatunnel
nohup ./bin/seatunnel.sh > /var/log/seatunnel/startup.log 2>&1 &

# 查看进程
ps aux | grep seatunnel

方式 3：Systemd 管理（推荐，开机自启）

创建服务文件 /etc/systemd/system/seatunnel.service：

[Unit]
Description=SeaTunnel Zeta Engine (Hybrid Mode)
After=network.target

[Service]
Type=simple
User=root
Environment="JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64"
ExecStart=/opt/seatunnel/bin/seatunnel-cluster.sh
ExecStop=/opt/seatunnel/bin/stop-seatunnel-cluster.sh
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

启动并设置开机自启：

# 重载 systemd
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start seatunnel

# 设置开机自启
sudo systemctl enable seatunnel

# 查看状态
sudo systemctl status seatunnel

五、验证部署

1. 检查服务状态

# systemd 状态
sudo systemctl status seatunnel

# 检查端口是否在监听
ss -tlnp | grep -E "5801|8080"
# 预期看到 5801 和 8080 端口

2. 查看日志

# 实时查看日志
tail -f /opt/seatunnel/logs/seatunnel-engine.log

# 查看启动日志
tail -100 /opt/seatunnel/logs/seatunnel-engine.log

# 搜索启动成功标志
grep -i "started\|ready\|master\|hybrid" /opt/seatunnel/logs/seatunnel-engine.log

3. 访问 Web UI

浏览器访问：http://192.168.192.131:8080

用户名：admin
密码：admin123

4. 验证 API 可用

# 检查集群状态（单节点，成员数为 1）
curl http://192.168.192.131:8080/hazelcast/cluster-members

# 预期输出类似：
# Members [1] {
#   Member [192.168.192.131]:5801 - this
# }

# 检查运行中的作业（初始为空）
curl http://192.168.192.131:8080/running-jobs

六、提交测试作业

创建测试作业文件

mkdir -p /opt/seatunnel/jobs

cat > /opt/seatunnel/jobs/test.conf <<EOF
env {
  parallelism = 1
  job.mode = "BATCH"
  job.name = "hybrid-test-job"
}

source {
  FakeSource {
    result_table_name = "fake"
    row.num = 1000
    schema = {
      fields {
        id = int
        name = string
      }
    }
  }
}

sink {
  Console {
    source_table_name = "fake"
  }
}
EOF

提交并监控作业

# CLI 方式提交
/opt/seatunnel/bin/seatunnel.sh --config /opt/seatunnel/jobs/test.conf

Web UI：浏览器访问 http://192.168.192.131:8080（用户名 admin，密码 admin123），可查看作业状态。

从远程客户端提交作业（如 DolphinScheduler）

当 DS 等调度系统部署在另一台机器上，需要通过 SeaTunnel 客户端向本集群提交作业时，必须确保 SeaTunnel 的安装路径在客户端和集群所有节点上完全一致。

原因：SeaTunnel Zeta 引擎提交作业时，客户端会将 connector jar 的绝对路径写入 Job DAG，集群节点按此绝对路径加载 jar 包。如果路径不一致，会报错：

The jar file file:/opt/soft/seatunnel/connectors/connector-jdbc-2.3.13.jar
can not be found in node 192.168.192.131

方案 A：统一路径（推荐）

DS 节点把 SeaTunnel 也装到 /opt/seatunnel/：

# DS 节点执行
sudo mkdir -p /opt/seatunnel
cd /tmp
wget https://dlcdn.apache.org/seatunnel/2.3.13/apache-seatunnel-2.3.13-bin.tar.gz
sudo tar -xzf apache-seatunnel-2.3.13-bin.tar.gz -C /opt/seatunnel --strip-components=1

# 客户端也要装 connector（解析 DAG 用）
/opt/seatunnel/bin/install-plugin.sh connector-jdbc connector-doris

# 配置 hazelcast-client.yaml 指向集群
cat > /opt/seatunnel/config/hazelcast-client.yaml <<'EOF'
hazelcast-client:
  cluster-name: seatunnel
  network:
    cluster-members:
      - 192.168.192.131:5801
EOF

# 提交命令
/opt/seatunnel/bin/seatunnel.sh --config /path/to/job.conf --deploy-mode cluster

方案 B：软链接（路径不一致时的 workaround）

如果 DS 节点上 SeaTunnel 已装在 /opt/soft/seatunnel/，在集群所有节点创建软链接：

# 集群所有节点执行
ln -s /opt/seatunnel /opt/soft/seatunnel

这个限制是 SeaTunnel 的设计缺陷（GitHub Issue #8267），2.3.x 版本未修复。

七、日常运维

1. 启停服务

# systemd 方式（推荐）
sudo systemctl start seatunnel      # 启动
sudo systemctl stop seatunnel       # 停止
sudo systemctl restart seatunnel    # 重启
sudo systemctl status seatunnel     # 查看状态

# 脚本方式
/opt/seatunnel/bin/seatunnel.sh     # 启动
/opt/seatunnel/bin/stop.sh          # 停止

2. 查看状态

# 检查服务是否运行
curl http://192.168.192.131:8080/hazelcast/cluster-members

# 查看运行中的作业
curl http://192.168.192.131:8080/running-jobs

# 查看系统资源
free -h
df -h /opt/seatunnel /data/seatunnel /var/log/seatunnel

3. 查看日志

# 实时日志
tail -f /opt/seatunnel/logs/seatunnel-engine.log

# 最近 100 行
tail -100 /opt/seatunnel/logs/seatunnel-engine.log

# 搜索错误日志
grep -i "error\|exception\|fail" /opt/seatunnel/logs/seatunnel-engine.log | tail -20

4. 配置修改后重启

# 修改 seatunnel.yaml 后重启服务
sudo systemctl restart seatunnel

# 确认重启成功
sudo systemctl status seatunnel
tail -20 /opt/seatunnel/logs/seatunnel-engine.log

八、常见问题

问题 1：端口被占用

# 检查端口占用
ss -tlnp | grep -E "5801|8080"

# 如果被占用，修改 seatunnel.yaml 中的端口号
# 或停止占用进程
sudo kill -9 <PID>

问题 2：启动失败，日志无内容

# 检查 Java 版本
java -version

# 前台启动查看详细错误
cd /opt/seatunnel
./bin/seatunnel.sh

# 检查配置文件语法
cat /opt/seatunnel/config/seatunnel.yaml

问题 3：Web UI 无法访问

# 检查服务是否运行
sudo systemctl status seatunnel

# 检查端口是否监听
ss -tlnp | grep 8080

# 检查防火墙
sudo ufw status

# 尝试本地访问
curl http://localhost:8080

问题 4：作业提交后一直等待

# 检查 Worker 是否正常（Hybrid 模式下 Master 和 Worker 在一起）
curl http://192.168.192.131:8080/hazelcast/cluster-members
# 应看到 1 个成员

# 检查日志
grep -i "submit\|job\|task" /opt/seatunnel/logs/seatunnel-engine.log | tail -20

问题 5：磁盘空间不足

# 查看磁盘使用
df -h /data/seatunnel

# 检查 Checkpoint 目录大小
du -sh /data/seatunnel/checkpoint/*

# 手动清理旧 Checkpoint
rm -rf /data/seatunnel/checkpoint/*

# 或减小 max-retained 值

问题 6：内存不足

# 查看内存使用
free -h

# 修改 JVM 参数，减小堆内存
# 编辑 /opt/seatunnel/config/seatunnel-env.sh
export JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC"

九、JVM 参数优化

编辑 /opt/seatunnel/config/seatunnel-env.sh：

# === 小内存机器（4-8GB 内存）===
export JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

# === 标准配置（16GB 内存）===
export JAVA_OPTS="-Xms4g -Xmx8g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

# === 大内存机器（32GB+ 内存）===
export JAVA_OPTS="-Xms8g -Xmx16g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

建议：Xmx 不要超过物理内存的 50%，给操作系统和文件缓存留足空间。

十、扩展为多节点集群

单机部署完成后，如果需要扩展为多节点集群：

准备新节点

在新节点上执行相同的安装步骤（一、二章），然后：

修改配置

所有节点的 seatunnel.yaml 中 member-list 添加所有节点：

member-list: |
168.192.131:5801
168.192.132:5801   # 新增
168.192.133:5801   # 新增

切换到共享存储

Checkpoint 需要改为所有节点都能访问的存储：

checkpoint:
  storage:
    type: s3              # 改为 S3 共享存储
    # ... S3 配置

滚动重启

# 依次重启每个节点
sudo systemctl restart seatunnel

十一、自动清理脚本

创建磁盘清理脚本，定期清理过期文件：

# 创建脚本
cat > /opt/scripts/cleanup-seatunnel.sh <<'EOF'
#!/bin/bash

# 删除 7 天前的日志
find /var/log/seatunnel -name "*.log" -mtime +7 -delete

# 删除已完成的旧作业临时文件
find /data/seatunnel/tmp -type f -mtime +3 -delete

# 输出清理信息
echo "[$(date)] Cleanup completed"
EOF

chmod +x /opt/scripts/cleanup-seatunnel.sh

# 配置定时任务（每天凌晨 2 点执行）
(crontab -l 2>/dev/null; echo "0 2 * * * /opt/scripts/cleanup-seatunnel.sh >> /var/log/seatunnel/cleanup.log 2>&1") | crontab -

概述​

架构说明​

Hybrid 模式 vs 传统分离模式（单机场景）​

一、环境准备​

步骤 1：更新系统软件源​

步骤 2：配置主机名​

步骤 3：配置防火墙​

步骤 4：安装 OpenJDK 17​

步骤 5：创建必要的目录结构​

二、下载并安装 SeaTunnel​

安装 Connector 插件​

配置 Maven 国内镜像（加速下载）​

三、Hybrid 模式配置​

步骤 1：配置 Hazelcast 集群通信​

步骤 2：修改引擎配置​

配置修改总结​

在 vim 中操作​

可选：使用 S3 存储 Checkpoint​

四、启动服务​

方式 1：前台启动（适合调试）​

方式 2：后台启动（简单实用）​

方式 3：Systemd 管理（推荐，开机自启）​

五、验证部署​

1. 检查服务状态​

2. 查看日志​

3. 访问 Web UI​

4. 验证 API 可用​

六、提交测试作业​

创建测试作业文件​

提交并监控作业​

从远程客户端提交作业（如 DolphinScheduler）​

七、日常运维​

1. 启停服务​

2. 查看状态​

3. 查看日志​

4. 配置修改后重启​

八、常见问题​

问题 1：端口被占用​

问题 2：启动失败，日志无内容​

问题 3：Web UI 无法访问​

问题 4：作业提交后一直等待​

问题 5：磁盘空间不足​

问题 6：内存不足​

九、JVM 参数优化​

十、扩展为多节点集群​

准备新节点​

修改配置​

切换到共享存储​

滚动重启​

十一、自动清理脚本​

参考资源​

概述