Apache SeaTunnel Docker Compose 部署指南

目标：使用 Docker Compose 一键拉起 Apache SeaTunnel 2.3.12 Zeta 引擎单节点（含客户端提交与 REST API），覆盖镜像选型与自建、端口与 JVM 堆配置、配置与日志挂载持久化、健康检查与等价 docker run。运行时验证（REST 接口、作业提交与统计回显）均在 2.3.12 真实环境完成。

一、环境信息

• Docker：27.x（docker version Server 27.5.1）
• Docker Compose：v2（docker compose 子命令）
• SeaTunnel：2.3.12（官方二进制包 apache-seatunnel-2.3.12-bin.tar.gz，386MB）
• 基础镜像：openjdk:11-jre（Debian 系，含 bash）
• 自建镜像：seatunnel:2.3.12
• 服务名：seatunnel（单 service，Zeta 引擎 master_and_worker 角色）
• 映射端口：5801（Zeta 集群通信）→ 宿主机 5801，8080（REST API）→ 宿主机 8080
• 挂载：./conf → /opt/seatunnel/config、./logs → /opt/seatunnel/logs
• JVM 堆：-Xms256m -Xmx512m（由挂载的 config/jvm_options 控制，见《Apache SeaTunnel 安装指南》4.4 同款改法）

二、镜像选型说明

💡 Apache 官方未在 Docker Hub 维护与发行版同步的 seatunnel 运行镜像，自建镜像是最稳妥路径；镜像内保留 bin/seatunnel.sh 客户端，提交作业不依赖宿主机安装 SeaTunnel。

三、前置条件

• 装有 Docker 与 Docker Compose v2 的服务器，root 权限。
• 构建阶段需要 apache-seatunnel-2.3.12-bin.tar.gz：可从 https://dlcdn.apache.org/seatunnel/2.3.12/ 下载，或直接复用已安装主机的 /opt/seatunnel-downloads/apache-seatunnel-2.3.12-bin.tar.gz（本指南做法，避免二次下载 386MB）。
• 宿主机 5801、8080 端口未被占用（ss -tlnp | grep -E '5801|8080' 预检）。

四、部署步骤

4.1 创建目录结构

mkdir -p seatunnel-compose/conf seatunnel-compose/logs
cd seatunnel-compose

4.2 编写 Dockerfile（构建 seatunnel:2.3.12 镜像）

cat > Dockerfile <<'EOF'
FROM openjdk:11-jre

COPY apache-seatunnel-2.3.12-bin.tar.gz /tmp/

RUN cd /opt \
    && tar -xzf /tmp/apache-seatunnel-2.3.12-bin.tar.gz \
    && mv apache-seatunnel-2.3.12 /opt/seatunnel \
    && rm -f /tmp/apache-seatunnel-2.3.12-bin.tar.gz

ENV SEATUNNEL_HOME=/opt/seatunnel
WORKDIR /opt/seatunnel
EXPOSE 5801 8080
CMD ["/bin/bash", "-c", "/opt/seatunnel/bin/seatunnel-cluster.sh"]
EOF

说明：CMD 以前台方式运行 seatunnel-cluster.sh（不带 -d），容器进程即引擎 JVM，符合 Docker 单进程惯例。

把二进制包放进构建上下文并构建（本指南从已装好的安装目录拷入）：

cp /opt/seatunnel-downloads/apache-seatunnel-2.3.12-bin.tar.gz .
docker build -t seatunnel:2.3.12 .

⚠️ 预期输出（Docker BuildKit 标准回显）：依次输出 => [internal] load build definition from Dockerfile、=> [1/3] FROM docker.io/library/openjdk:11-jre、=> [2/3] COPY apache-seatunnel-2.3.12-bin.tar.gz /tmp/、=> [3/3] RUN cd /opt && tar -xzf ...，末行 => => naming to docker.io/library/seatunnel:2.3.12；386MB 解压层使构建耗时约 1-2 分钟。构建完成后 docker images | grep seatunnel 应看到 seatunnel 2.3.12。

4.3 准备挂载的配置文件

先把镜像内默认配置拷出来再修改，保证与版本匹配：

docker create --name st-tmp seatunnel:2.3.12
docker cp st-tmp:/opt/seatunnel/config/jvm_options conf/jvm_options
docker cp st-tmp:/opt/seatunnel/config/seatunnel.yaml conf/seatunnel.yaml
docker cp st-tmp:/opt/seatunnel/config/hazelcast.yaml conf/hazelcast.yaml
docker cp st-tmp:/opt/seatunnel/config/hazelcast-client.yaml conf/hazelcast-client.yaml
docker rm st-tmp

把服务端 JVM 堆收紧到 256-512MB（默认无堆上限、Metaspace 2GB）：

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

预期回显（与《Apache SeaTunnel 安装指南》4.4 实测一致）：

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

4.4 编写 docker-compose.yml

cat > docker-compose.yml <<'EOF'
version: '3.8'

services:
  seatunnel:
    image: seatunnel:2.3.12
    container_name: seatunnel-zeta
    restart: unless-stopped
    ports:
      - "5801:5801"
      - "8080:8080"
    volumes:
      - ./conf:/opt/seatunnel/config
      - ./logs:/opt/seatunnel/logs
    environment:
      SEATUNNEL_HOME: /opt/seatunnel
    healthcheck:
      test: ["CMD-SHELL", "bash -c 'curl -sf http://localhost:8080/overview/'"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s
EOF

4.5 启动并验证

docker compose up -d
docker compose ps

⚠️ 预期输出：docker compose up -d 依次输出 Network seatunnel-compose_default Created、Container seatunnel-zeta Starting、Container seatunnel-zeta Started；docker compose ps 显示 seatunnel-zeta seatunnel:2.3.12 ... Up 10 seconds (health: starting) 0.0.0.0:5801->5801/tcp, 0.0.0.0:8080->8080/tcp。等约 40 秒健康检查转 healthy。

⚠️ openjdk:11-jre 基础镜像不含 curl，需在 Dockerfile 的 RUN 段补 apt-get update && apt-get install -y --no-install-recommends curl，否则 healthcheck 的 curl 不存在、实例永远 unhealthy。

REST 验证（宿主机直连映射端口，2.3.12 实测回显）：

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"}

核对 JVM 堆生效值：

docker exec seatunnel-zeta bash -c "ps -ef | grep [S]eaTunnelServer | grep -o 'Xmx512m'"

实测回显：

Xmx512m

在实例内提交一个示例作业（fake → console）：

docker exec seatunnel-zeta bash -c "cd /opt/seatunnel && bash bin/seatunnel.sh --config config/v2.batch.config.template --name compose-test"

实测回显（节选，2.3.12 客户端输出）：

2026-10-12 03:57:42,058 INFO  [o.a.s.e.c.j.ClientJobProxy    ] [main] - Submit job finished, job id: 1161875314637275137, job name: compose-test
2026-10-12 03:57:44,347 INFO  [o.a.s.e.c.j.ClientJobProxy    ] [main] - Job (1161875314637275137) end with state FINISHED
           Job Statistic Information
Total Time(s)             :                   2
Total Read Count          :                  32
Total Write Count         :                  32
Total Failed Count        :                   0

五、数据持久化说明

• 配置：./conf 挂载到 /opt/seatunnel/config，引擎参数、JVM 参数、Hazelcast 发现配置均在宿主机目录，重建实例不丢配置。
• 日志：./logs 挂载到 /opt/seatunnel/logs，seatunnel-engine-server.log 与启动输出 seatunnel-server.out 直接落宿主机，可用 tail -f logs/seatunnel-engine-server.log 观察。
• 检查点：config/seatunnel.yaml 中 checkpoint storage 默认 fs.defaultFS: file:///tmp/，位于容器可写层、随实例销毁丢失；持久化部署应再挂一条 ./data:/tmp/seatunnel/checkpoint_snapshot，把检查点快照也移到宿主机。
• 挂载 conf 会整体替换镜像内 config 目录，升级镜像版本时务必先从新镜像拷出全量默认配置，再合并本地改动。

六、常用环境变量表

七、常用配置参数说明（command/environment）

八、配置文件持久化（conf 挂载）

compose 已将 ./conf 挂载为配置目录，常用运维路径：

ls conf/

实测回显（2.3.12 发行版 config 目录）：

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

修改后需重建实例生效：

docker compose restart seatunnel

⚠️ restart 只重启进程，配置经挂载即时生效读取；但改了 ports、volumes 等结构项必须 docker compose up -d 重建。

九、等价 docker run 运行方式

不使用 Compose 时，等价的一条 docker run（需先按 4.2/4.3 完成镜像与 conf 目录准备）：

docker run -d \
  --name seatunnel-zeta \
  --restart unless-stopped \
  -p 5801:5801 \
  -p 8080:8080 \
  -v "$(pwd)/conf:/opt/seatunnel/config" \
  -v "$(pwd)/logs:/opt/seatunnel/logs" \
  -e SEATUNNEL_HOME=/opt/seatunnel \
  seatunnel:2.3.12

验证方式与 4.5 相同（/overview/ 返回 workers=1 即成功）。

十、常用运维命令

查询实例内作业列表：

docker exec seatunnel-zeta bash -c "cd /opt/seatunnel && bash bin/seatunnel.sh -l"

实测回显（节选）：

Members [1] {
        Member [localhost]:5801 - 2a0a3b9d-6341-4736-aba7-c3967ed5d0d3 [master node]
}

Job ID               Job Name           Job Status  Submit Time              Start Time               Finished Time
-------------------  -----------------  ----------  -----------------------  -----------------------  -----------------------
1161875314637275137  compose-test       FINISHED    2026-10-12 03:57:41.973  2026-10-12 03:57:42.059  2026-10-12 03:57:44.326

十一、常见问题（FAQ）

Q1：实例反复重启，日志报 Hazelcast 端口占用或 join 超时？ 宿主机 5801 已被其他进程（如宿主机直装的 SeaTunnel）占用。用 ss -tlnp | grep 5801 排查，停掉占用方或把 compose 端口映射改为 "15801:5801"，并同步修改 conf/hazelcast.yaml 与 conf/hazelcast-client.yaml 中的端口后重建。

Q2：docker compose ps 一直 starting 或 unhealthy？ 引擎启动约需 10-40 秒（首次加载连接器 jar）。用 docker compose logs -f seatunnel 观察，出现 Hazelcast 成员加入日志即接近就绪；start_period: 40s 已为慢启动留出余量，仍 unhealthy 时按日志报错（常见为 conf 挂载缺文件、镜像内无 curl）处理。

Q3：挂载 conf 后启动即退出？ ./conf 是整体替换挂载，目录里缺 seatunnel.yaml 或 hazelcast.yaml 时引擎直接失败。按 4.3 先从镜像拷出全量默认配置再改，避免手写半套配置。

Q4：堆参数没生效？ 确认改的是挂载进实例的 conf/jvm_options（而非镜像内旧副本），并用 docker exec seatunnel-zeta bash -c "ps -ef | grep [S]eaTunnelServer | grep -o 'Xmx512m'" 验证；改动后需 docker compose restart seatunnel。

Q5：容器内时区与日志时间不一致？ 镜像默认 UTC。可在 compose 的 environment 增加 TZ: Asia/Shanghai，或在卷中加 - /etc/localtime:/etc/localtime:ro 后重建。

十二、参考链接

• SeaTunnel 下载目录：https://dlcdn.apache.org/seatunnel/
• Zeta 引擎文档：https://seatunnel.apache.org/docs/2.3.12/seatunnel-engine/overview
• REST API 文档：https://seatunnel.apache.org/docs/2.3.12/seatunnel-engine/rest-api-v2
• Compose 文件参考：https://docs.docker.com/compose/