Apache SeaTunnel 安装指南

目标：在 Ubuntu 22.04 服务器上从零安装 Apache SeaTunnel 2.3.12（数据集成平台，自带 Zeta 引擎），覆盖前置依赖、官方二进制下载解压、本地模式与集群模式启动、systemd 托管与验证。以下命令与回显均在 Ubuntu 22.04.5 真实环境逐步实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Java：OpenJDK 11.0.32.1（openjdk-11-jre-headless）
Apache SeaTunnel：2.3.12（官方二进制包 apache-seatunnel-2.3.12-bin.tar.gz，386MB）
安装目录：/opt/seatunnel
端口规划：5801（Zeta 集群通信，Hazelcast）、8080（引擎 REST/HTTP API）
运行用户：root

💡 说明：SeaTunnel 2.3.x 自带 Zeta 引擎，开箱即可独立运行，不强制依赖 Spark/Flink；config/seatunnel-env.sh 中的 SPARK_HOME、FLINK_HOME 仅在以 Spark/Flink 为引擎提交时才需要配置。

二、前置条件

一台 Ubuntu 22.04 服务器，root 权限，内存建议 4GB 以上（本指南将 JVM 堆限制在 256-512MB，2GB 内存亦可运行）。
服务器可访问 dlcdn.apache.org（或 archive.apache.org）下载安装包，可访问 Ubuntu APT 软件源。
需安装 openjdk-11-jre-headless、wget、tar、net-tools、procps、curl、iproute2。

三、版本选型说明

组件	推荐版本	说明
Apache SeaTunnel	2.3.12	当前 2.3.x 最新稳定版，官方提供 `-bin.tar.gz` 二进制包
OpenJDK	11	SeaTunnel 2.3.x 支持 Java 8/11，Ubuntu 22.04 仓库内置 11
Zeta 引擎	随 2.3.12 内置	无需外置 Spark/Flink，`seatunnel-cluster.sh` 直接启动

版本号获取方式（不硬编码最新版）：浏览 https://dlcdn.apache.org/seatunnel/ 目录列表，或执行：

wget -qO- https://dlcdn.apache.org/seatunnel/ | grep -oE 'seatunnel-[0-9]+\.[0-9]+\.[0-9]+' | sort -Vu | tail -5

四、部署步骤

4.1 更新软件源并安装基础工具

apt-get update -qq
DEBIAN_FRONTEND=noninteractive apt-get install -y \
    openjdk-11-jre-headless wget tar net-tools procps curl iproute2

安装完成的收尾回显：

done.
done.

验证 Java 版本：

java -version

实测回显：

openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)

4.2 下载并解压 SeaTunnel 2.3.12

mkdir -p /opt/seatunnel-downloads
cd /opt/seatunnel-downloads
wget https://dlcdn.apache.org/seatunnel/2.3.12/apache-seatunnel-2.3.12-bin.tar.gz

wget 下载末段实测回显（约 386MB，视带宽耗时不同）：

390144K ........ ........ ........ ........ ........ ........  99% 21.2M 0s
393216K ........ ........ ........ ...                       100% 21.1M=11s

-rw-r--r-- 1 root root 386M Sep  6  2025 apache-seatunnel-2.3.12-bin.tar.gz

解压并移动到 /opt/seatunnel：

cd /opt/seatunnel-downloads
tar -xzf apache-seatunnel-2.3.12-bin.tar.gz
mv apache-seatunnel-2.3.12 /opt/seatunnel
ls /opt/seatunnel

实测回显：

LICENSE  NOTICE  README.md  bin  config  connectors  lib  licenses  mvnw  mvnw.cmd  plugins  starter

4.3 确认自带连接器与版本

发行版默认自带三个连接器 jar，足够跑通 FakeSource 到 Console 的示例作业：

ls /opt/seatunnel/connectors

实测回显：

connector-cdc-base-2.3.12.jar
connector-console-2.3.12.jar
connector-fake-2.3.12.jar
plugin-mapping.properties

版本确认：启动集群后访问 REST 接口 /overview/ 可见 projectVersion: 2.3.12（见 4.7），或查看 jar 文件名后缀 2.3.12。

💡 其余连接器（JDBC、Kafka、MySQL CDC 等）默认不在发行包内，需用 bin/install-plugin.sh 按 config/plugin_config 清单下载，详见《Apache SeaTunnel 常用 CLI 命令与工具详解》。

4.4 将 JVM 堆限制在 256-512MB

Zeta 引擎服务端 JVM 参数来自 config/jvm_options（master_and_worker 角色默认读取），默认未设堆上限并带 2GB Metaspace：

grep -v '^#' /opt/seatunnel/config/jvm_options | grep -v '^$'

实测回显（修改前）：

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/tmp/seatunnel/dump/zeta-server
-XX:MaxMetaspaceSize=2g
-XX:+UseG1GC

用 sed 将堆与 Metaspace 一并收紧：

sed -i "s/^-XX:MaxMetaspaceSize=2g$/-Xms256m\n-Xmx512m\n-XX:MaxMetaspaceSize=256m/" /opt/seatunnel/config/jvm_options
grep -v '^#' /opt/seatunnel/config/jvm_options | grep -v '^$'

实测回显（修改后）：

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/tmp/seatunnel/dump/zeta-server
-Xms256m
-Xmx512m
-XX:MaxMetaspaceSize=256m
-XX:+UseG1GC

💡 说明：jvm_master_options、jvm_worker_options 分别作用于 master、worker 独立角色节点；客户端 JVM 由 jvm_client_options 控制，默认即 -Xms256m -Xmx512m。

4.5 启动 Zeta 集群（单节点）

cd /opt/seatunnel
bash bin/seatunnel-cluster.sh -d

实测回显：

start master_and_worker node

⚠️ 务必用 bash 执行脚本。Ubuntu 22.04 的 /bin/sh 指向 dash，若写成 sh bin/seatunnel-cluster.sh 会连续报 [: unexpected operator、[[: not found 等错误（见「八、常见问题」）。

查看监听端口：

netstat -tlnp | grep -E '5801|8080'

实测回显：

tcp6       0      0 :::5801                 :::*                    LISTEN      4283/java
tcp6       0      0 :::8080                 :::*                    LISTEN      4283/java

确认堆参数已生效：

ps -ef | grep [S]eaTunnelServer | grep -o 'Xmx512m'

实测回显：

Xmx512m

4.6 跑通第一个作业（本地模式验证）

用发行版自带的批量作业模板（FakeSource 生成 16 行×2 并行度的 name/age 数据，Console 打印）：

cd /opt/seatunnel
bash bin/seatunnel.sh --config config/v2.batch.config.template -e local

作业结束后实测回显（Console sink 数据行节选）：

2026-10-12 02:36:35,140 INFO  [.a.s.c.s.c.s.ConsoleSinkWriter] [hz.main.seaTunnel.task.thread-4] - output rowType: name<STRING>, age<INT>
2026-10-12 02:36:36,361 INFO  [.a.s.c.s.c.s.ConsoleSinkWriter] [st-multi-table-sink-writer-1] - subtaskIndex=0  rowIndex=1:  SeaTunnelRow#tableId=fake SeaTunnelRow#kind=INSERT : jBcDh, 367258
2026-10-12 02:36:36,361 INFO  [.a.s.c.s.c.s.ConsoleSinkWriter] [st-multi-table-sink-writer-1] - subtaskIndex=1  rowIndex=1:  SeaTunnelRow#tableId=fake SeaTunnelRow#kind=INSERT : AxumK, 231704352

末尾统计块（实测原样）：

***********************************************
           Job Statistic Information
***********************************************
Start Time                : 2026-10-12 02:36:34
End Time                  : 2026-10-12 02:36:37
Total Time(s)             :                   2
Total Read Count          :                  32
Total Write Count         :                  32
Total Failed Count        :                   0
***********************************************

💡 Read Count 等于模板中 row.num = 16 乘以 FakeSource 的 parallelism = 2，即 32 条；两条 subtaskIndex 分别对应两个并发写线程。

4.7 验证 REST API

config/seatunnel.yaml 默认开启了 HTTP 接口（enable-http: true，端口 8080）：

curl -s http://localhost:8080/overview/

实测回显：

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

curl -s http://localhost:8080/running-jobs/

实测回显：

[]

4.8 配置 systemd 托管集群

创建 /etc/systemd/system/seatunnel-cluster.service：

cat > /etc/systemd/system/seatunnel-cluster.service <<'EOF'
[Unit]
Description=Apache SeaTunnel Zeta Engine Cluster Node
After=network.target

[Service]
Type=forking
Environment=SEATUNNEL_HOME=/opt/seatunnel
ExecStart=/opt/seatunnel/bin/seatunnel-cluster.sh -d
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
User=root

[Install]
WantedBy=multi-user.target
EOF

💡 单元内未写 ExecStop：停止时 systemd 默认向整个 cgroup 发送 SIGTERM，足以结束 JVM 进程（systemctl restart 已实测可用）。

启用并启动：

systemctl daemon-reload
systemctl enable seatunnel-cluster.service

enable 实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/seatunnel-cluster.service → /etc/systemd/system/seatunnel-cluster.service.

systemctl start seatunnel-cluster.service
systemctl is-active seatunnel-cluster.service

实测回显：

active

再次核对端口与进程（此时由 systemd 拉起）：

netstat -tlnp | grep 5801

实测回显：

tcp6       0      0 :::5801                 :::*                    LISTEN      6446/java

在 systemd 托管的节点上提交作业做端到端验证：

cd /opt/seatunnel
bash bin/seatunnel.sh --config config/v2.batch.config.template --name systemd-node-test

实测回显（节选）：

Submit job finished, job id: 1161856999927840769, job name: systemd-node-test
Job (1161856999927840769) end with state FINISHED
Total Read Count          :                  32
Total Write Count         :                  32

五、配置说明

5.1 目录与文件职责

路径	用途
`/opt/seatunnel/bin`	`seatunnel.sh`（客户端）、`seatunnel-cluster.sh`（服务端）、`install-plugin.sh`（装连接器）
`/opt/seatunnel/config`	`seatunnel.yaml`（引擎）、`hazelcast.yaml`（集群与客户端发现）、`jvm__options`（JVM）、`plugin_config`（连接器清单）
`/opt/seatunnel/connectors`	连接器 jar，默认仅 fake/console/cdc-base
`/opt/seatunnel/logs`	引擎日志 `seatunnel-engine-server.log` 与启动输出 `seatunnel-server.out`
`/tmp/seatunnel/checkpoint_snapshot`	检查点快照默认命名空间（`fs.defaultFS: file:///tmp/`）

5.2 常用环境变量

可在 /etc/profile.d/seatunnel.sh 中固化：

export SEATUNNEL_HOME=/opt/seatunnel
export PATH=$PATH:$SEATUNNEL_HOME/bin

config/seatunnel-env.sh 默认内容（Zeta 引擎部署可不改）：

SPARK_HOME=${SPARK_HOME:-/opt/spark}
FLINK_HOME=${FLINK_HOME:-/opt/flink}

5.3 集群发现与客户端地址

服务端发现配置在 config/hazelcast.yaml：network.join.tcp-ip.member-list 默认 - localhost，network.port.port 默认 5801、auto-increment: false；扩多节点时把其他节点主机名加入 member-list。
客户端发现配置在 config/hazelcast-client.yaml：network.cluster-members 默认 - localhost:5801，连接超时 cluster-connect-timeout-millis: 3000；远程提交作业时改为集群节点地址列表。

参数细节见《Apache SeaTunnel 配置参数详解》。

六、升级与多版本管理

升级：下载新版二进制包解压为 /opt/seatunnel-<新版本>，停服务后把符号链接 /opt/seatunnel 重新指向新目录（ln -sfn /opt/seatunnel-<新版本> /opt/seatunnel），沿用原 config 目录后再启动；作业配置文件与连接器 jar 需按官方升级说明核对兼容性。
多版本并存：保留多个 /opt/seatunnel-2.3.x 目录，用符号链接切换，注意 5801 端口同一时间只能被一个集群占用。
回滚：改回符号链接指向旧目录并重启即可；检查点快照目录与作业 ID 不跨版本复用。

七、注意事项

堆内存务必显式收紧（本指南 256-512MB），否则默认 Metaspace 上限 2GB、堆无上限，小规格机器易被 OOM killer 杀进程。
bash bin/seatunnel.sh、bash bin/seatunnel-cluster.sh，不要用 sh 前缀。
单机重复启动第二个节点会因 5801 端口被占用而失败，systemctl status 会显示 activating (auto-restart)，先释放端口再重启。
防火墙放行 5801（集群通信）与 8080（REST），8080 默认无鉴权，公网环境建议改用 enable-basic-auth（见配置篇）或用防火墙限制来源。

八、常见问题

Q1：执行 sh bin/seatunnel-cluster.sh -d 报大量 [: unexpected operator、[[: not found？ Ubuntu 22.04 的 /bin/sh 是 dash，不支持 bash 的 [[ 语法。实测现象为脚本开头连续输出：

bin/seatunnel.sh: 47: [: 4: unexpected operator
bin/seatunnel.sh: 87: [[: not found
bin/seatunnel.sh: 98: [[: not found

改用 bash bin/seatunnel-cluster.sh -d 即可，回显干净。

Q2：systemctl start 后服务一直 activating (auto-restart)？ 典型原因是 5801 端口已被旧进程占用（本指南实测出现：手工先启动过一次集群，再由 systemd 拉起时 Main PID 以 status=1/FAILURE 退出）。用 netstat -tlnp | grep 5801 找到占用进程，kill <pid> 后再 systemctl restart seatunnel-cluster.service，恢复 active。

Q3：提交作业报 plugin_output 相关 WARN？ 模板中 FakeSource 设置了 plugin_output = "fake" 而 Console 未配 plugin_input，实测回显：

WARN  [o.a.s.e.c.p.ConfigParserUtil  ] - This configuration is not recommended. 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.

这是链路命名提示，不影响执行；规范写法是在 Console 中显式加 plugin_input = "fake"。

Q4：--list-jobs 报 NullPointerException？ --list-jobs 不是客户端合法选项，客户端会按「缺 --config 的作业提交」处理并抛错（实测）：

Exception in thread "main" org.apache.seatunnel.core.starter.exception.CommandExecuteException: SeaTunnel job executed failed
Caused by: java.lang.NullPointerException

列作业请用 bash bin/seatunnel.sh -l。

Q5：jre-headless 环境没有 jps 命令？ openjdk-11-jre-headless 不含 jps，需要时补装 openjdk-11-jdk-headless；本指南验证堆参数用的 ps -ef | grep [S]eaTunnelServer 不依赖 jps。

九、卸载方式

systemctl stop seatunnel-cluster.service
systemctl disable seatunnel-cluster.service
rm /etc/systemd/system/seatunnel-cluster.service
systemctl daemon-reload
rm -rf /opt/seatunnel /opt/seatunnel-downloads
rm -rf /tmp/seatunnel

删除 systemd 环境变量文件（若按 5.2 配置过）：

rm /etc/profile.d/seatunnel.sh

卸载 JDK（可选，若仅为此组件安装）：

apt-get remove -y openjdk-11-jre-headless
apt-get autoremove -y

十、参考链接

官方下载目录：https://dlcdn.apache.org/seatunnel/
历史版本归档：https://archive.apache.org/dist/seatunnel/
Zeta 引擎命令行文档：https://seatunnel.apache.org/docs/2.3.12/seatunnel-engine/cli
引擎配置文档：https://seatunnel.apache.org/docs/2.3.12/seatunnel-engine