Apache SeaTunnel 常用 CLI 命令与工具详解

目标：系统梳理 Apache SeaTunnel 2.3.12 的命令行工具——seatunnel.sh（作业提交/查询/取消/恢复）、seatunnel-cluster.sh（引擎节点启动与角色）、install-plugin.sh（连接器安装）以及 REST API 与排障命令，按场景给出可直接复制的命令与实测回显。全部命令均在 Ubuntu 22.04 的 2.3.12 环境实测。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Apache SeaTunnel：2.3.12（Zeta 引擎）
安装目录：/opt/seatunnel（下文命令均在此目录执行，即先 cd /opt/seatunnel）
端口：5801（集群）、8080（REST）
JVM 堆：服务端 -Xmx512m、客户端 -Xmx512m（jvm_options 与 jvm_client_options 实测生效）
运行用户：root

二、前置条件

已完成安装并启动集群（bash bin/seatunnel-cluster.sh -d 或 systemd 托管），netstat -tlnp | grep 5801 可见 LISTEN。
全部脚本用 bash 执行（Ubuntu 22.04 的 /bin/sh 是 dash，sh bin/seatunnel.sh 会报 [[: not found，实测见 FAQ）。
作业配置可用发行版自带 config/v2.batch.config.template（FakeSource 到 Console，无需额外连接器）。

三、命令速查表

命令	用途	语法
`seatunnel.sh -c <file>`	提交作业（同步）	`bash bin/seatunnel.sh --config <file> [-n 名称]`
`seatunnel.sh --async`	异步提交流作业	`bash bin/seatunnel.sh --config <file> --async`
`seatunnel.sh -e local`	本地模式单次运行	`bash bin/seatunnel.sh --config <file> -e local`
`seatunnel.sh -l`	列出全部作业	`bash bin/seatunnel.sh -l`
`seatunnel.sh --get-job-info`	查询作业详情	`bash bin/seatunnel.sh --get-job-info -j <jobId>`
`seatunnel.sh --metrics`	查询作业指标	`bash bin/seatunnel.sh --metrics <jobId>`
`seatunnel.sh --cancel-job`	取消作业	`bash bin/seatunnel.sh --cancel-job <jobId>`
`seatunnel.sh --savepoint`	保存点并停止	`bash bin/seatunnel.sh --savepoint <jobId>`
`seatunnel.sh --restore`	从保存点恢复（需配 `--config`）	`bash bin/seatunnel.sh --config <file> --restore <jobId>`
`seatunnel.sh --check`	仅校验配置	`bash bin/seatunnel.sh --config <file> --check`
`seatunnel-cluster.sh -d`	后台启动引擎节点	`bash bin/seatunnel-cluster.sh -d`
`seatunnel-cluster.sh -r`	指定节点角色	`-r master
`seatunnel-cluster.sh -m`	显示集群成员	`bash bin/seatunnel-cluster.sh -m`
`install-plugin.sh`	安装连接器	`bash bin/install-plugin.sh [版本号]`
REST API	HTTP 查询/管理	`curl http://localhost:8080/overview/`

四、seatunnel.sh 详解（客户端）

4.1 完整帮助与参数表

bash bin/seatunnel.sh --help

实测回显（参数表部分）：

Usage: seatunnel.sh [options]
  Options:
    --async                         Run the job asynchronously, when the job
                                    is submitted, the client will exit
                                    (default: false)
    -can, --cancel-job              Cancel job by JobId
    --check                         Whether check config (default: false)
    -cj, --close-job                Close client the task will also be closed
                                    (default: true)
    -cn, --cluster                  The name of cluster
    -c, --config                    Config file
    --decrypt                       Decrypt config file, When both --decrypt
                                    and --encrypt are specified, only
                                    --encrypt will take effect (default:
                                    false)
    -m, --master, -e, --deploy-mode SeaTunnel job submit master, support
                                    [local, cluster] (default: cluster)
    --encrypt                       Encrypt config file, when both --decrypt
                                    and --encrypt are specified, only
                                    --encrypt will take effect (default:
                                    false)
    --get_running_job_metrics       Gets metrics for running jobs (default:
                                    false)
    -h, --help                      Show the usage message
    -j, --job-id                    Get job status by JobId
    -l, --list                      list job status (default: false)
    --metrics                       Get job metrics by JobId
    -n, --name                      SeaTunnel job name (default: SeaTunnel)
    -r, --restore                   restore with savepoint by jobId
    -s, --savepoint                 savepoint job by jobId
    --set-job-id                    Set custom job id for job
    -i, --variable                  Variable substitution, such as -i
                                    city=beijing, or -i date=20190318.We use
                                    ',' as separator, when inside "", ',' are
                                    treated as normal characters instead of
                                    delimiters. For example, -i
                                    city="beijing,shanghai". If you want to
                                    use dynamic parameters, you can use the
                                    following format: -i date=$(date
                                    +"%Y%m%d"). (default: [])

常用参数组合：

参数	说明	示例
`--config/-c`	作业配置文件路径	`--config config/v2.batch.config.template`
`--name/-n`	作业名（默认 SeaTunnel）	`-n my-batch-job`
`--master/-m`、`--deploy-mode/-e`	提交目标，`local` 或 `cluster`（默认）	`-e local`
`--async`	异步提交，客户端提交后即退出	流作业必配
`--set-job-id`	指定自定义 JobId	`--set-job-id 12345678`
`-i/--variable`	变量替换	`-i date=$(date +%Y%m%d)`
`-cn/--cluster`	指定集群名	`-cn seatunnel`
`--check`	只校验配置不提交	排查配置语法
`--encrypt/--decrypt`	配置文件加密/解密	密码脱敏场景

4.2 本地模式运行示例作业

-e local 不经过集群，单进程跑完即退出，适合快速验证连接器与配置：

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
***********************************************

4.3 提交作业到集群（同步）

bash bin/seatunnel.sh --config config/v2.batch.config.template --name fake2console-test -m cluster

实测回显（节选）：

Submit job finished, job id: 1161855405924548609, job name: fake2console-test
Job (1161855405924548609) end with state FINISHED
           Job Statistic Information
Total Read Count          :                  32
Total Write Count         :                  32
Total Failed Count        :                   0

同步模式会一直挂住客户端直到作业结束；长作业请用 --async。

4.4 异步提交流作业

把模板改为 STREAMING（实测 sed）：

sed "s/job.mode = \"BATCH\"/job.mode = \"STREAMING\"/" config/v2.batch.config.template > /tmp/stream-test.conf
bash bin/seatunnel.sh --config /tmp/stream-test.conf --name stream-fake-test --async

异步提交即返回；随后 -l 实测可见 RUNNING：

Job ID               Job Name           Job Status  Submit Time              Start Time               Finished Time
-------------------  -----------------  ----------  -----------------------  -----------------------  -----------------------
1161855771885961217  stream-fake-test   RUNNING     2026-10-12 02:40:02.539  2026-10-12 02:40:02.611
1161855405924548609  fake2console-test  FINISHED    2026-10-12 02:38:35.273  2026-10-12 02:38:35.535  2026-10-12 02:38:37.939

4.5 查询作业列表与详情

列作业：

bash bin/seatunnel.sh -l

实测回显（表头与成员块）：

Members [1] {
        Member [localhost]:5801 - be7b2e48-9b3a-4b11-928b-fe69ea95f509 [master node]
}

Job ID               Job Name           Job Status  Submit Time              Start Time               Finished Time
-------------------  -----------------  ----------  -----------------------  -----------------------  -----------------------
1161855405924548609  fake2console-test  FINISHED    2026-10-12 02:38:35.273  2026-10-12 02:38:35.535  2026-10-12 02:38:37.939

按 JobId 查详情：

bash bin/seatunnel.sh --get-job-info -j 1161855405924548609

实测回显（JSON）：

{"jobId":1161855405924548609,"jobName":"fake2console-test","jobStatus":"FINISHED","submitTime":1791772715273,"startTime":1791772715535,"finishTime":1791772717939,"pipelineStateMapperMap":{"PipelineLocation(jobId=1161855405924548609, pipelineId=1)":{"pipelineStatus":"FINISHED","executionStateMap":{"TaskGroupLocation{jobId=1161855405924548609, pipelineId=1, taskGroupId=2}":"FINISHED","TaskGroupLocation{jobId=1161855405924548609, pipelineId=1, taskGroupId=3}":"FINISHED","TaskGroupLocation{jobId=1161855405924548609, pipelineId=1, taskGroupId=1}":"FINISHED"}}},"errorMessage":null}

4.6 查询作业指标

bash bin/seatunnel.sh --metrics 1161855771885961217

实测回显（JSON 数组节选）：

  }, {
    "tags" : {
      "jobId" : "1161855771885961217",
      "taskGroupId" : "3",
      "address" : "[localhost]:5801",
      "service" : "TaskExecutionService",
      "taskGroupLocation" : "TaskGroupLocation{jobId=1161855771885961217, pipelineId=1, taskGroupId=3}",
      "member" : "be7b2e48-9b3a-4b11-928b-fe69ea95f509",
      "taskName" : "TransformSeaTunnelTask",
      "taskID" : "1000300010001",
      "pipelineId" : "1"
    },
    "metric" : "SinkWriteBytes",
    "value" : 144,
    "timestamp" : 1791773000511
  } ]
}

⚠️ 注意写法：--metrics <jobId> 值直接跟在选项后。实测 --metrics -j <jobId> 会把 -j 当作 --metrics 的值解析，报 Caused by: java.lang.NumberFormatException: For input string: "-j"。

4.7 取消作业

bash bin/seatunnel.sh --cancel-job 1161855771885961217

取消后 -l 实测回显（状态转 CANCELED）：

1161855771885961217  stream-fake-test   CANCELED    2026-10-12 02:40:02.539  2026-10-12 02:40:02.611  2026-10-12 02:43:20.525

4.8 保存点与恢复

保存点用于流作业的有状态停止与恢复，依赖 seatunnel.yaml 的 checkpoint.storage（默认本地 /tmp 存储重启即丢，生产按《Apache SeaTunnel 配置参数详解》改为持久存储）。

先异步提交一个流作业（实测）：

sed "s/job.mode = \"BATCH\"/job.mode = \"STREAMING\"/" config/v2.batch.config.template > /tmp/save-test.conf
bash bin/seatunnel.sh --config /tmp/save-test.conf --name stream-sp2-test --async

2026-10-12 04:01:04,702 INFO  [o.a.s.e.c.j.ClientJobProxy    ] [main] - Submit job finished, job id: 1161876165124685825, job name: stream-sp2-test

对运行中的作业触发保存点（值直接跟在选项后）。保存点成功时客户端不打印成功提示语（仅连接与关闭日志），用 -l 确认状态转 SAVEPOINT_DONE（实测行）：

bash bin/seatunnel.sh --savepoint 1161876165124685825

1161876165124685825  stream-sp2-test    SAVEPOINT_DONE  2026-10-12 04:01:04.643  2026-10-12 04:01:04.702  2026-10-12 04:01:06.946

恢复必须带 --config，裸调 --restore <jobId> 实测按缺配置的提交路径报 NPE：

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

带配置从最近保存点恢复（实测：沿用原 JobId 续跑，作业名取默认 SeaTunnel_Job；流作业客户端会同步附着持续输出，验证后可按 4.7 取消）：

bash bin/seatunnel.sh --config /tmp/save-test.conf --restore 1161876165124685825

2026-10-12 04:01:58,284 INFO  [o.a.s.e.c.j.ClientJobProxy    ] [main] - Start submit job, job id: 1161876165124685825, with plugin jar [file:/opt/seatunnel/connectors/connector-fake-2.3.12.jar, file:/opt/seatunnel/connectors/connector-console-2.3.12.jar]
2026-10-12 04:01:58,305 INFO  [o.a.s.e.c.j.ClientJobProxy    ] [main] - Submit job finished, job id: 1161876165124685825, job name: SeaTunnel_Job

4.9 变量替换与配置校验

配置中可用占位变量，提交时用 -i 注入（帮助原文示例）：

bash bin/seatunnel.sh --config job.conf -i date=$(date +%Y%m%d) -i city=beijing

仅校验不提交：

bash bin/seatunnel.sh --config config/v2.batch.config.template --check

五、seatunnel-cluster.sh 详解（引擎节点）

5.1 启动与角色参数

bash bin/seatunnel-cluster.sh --help

实测回显：

start master_and_worker node
Usage: seatunnel.sh [options]
  Options:
    -cn, --cluster The name of cluster
    -d, --daemon   The cluster daemon mode (default: false)
    -h, --help     Show the usage message
    -m, --member   Show cluster members information (default: false)
    -r, --role     The cluster node role, default is master_and_worker,
                   support master, worker, master_and_worker

启动实测：

bash bin/seatunnel-cluster.sh -d

start master_and_worker node

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

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

角色说明：单机学习/演示用默认 master_and_worker；生产集群节点分开启动 -r master 与 -r worker（JVM 参数分别读 jvm_master_options/jvm_worker_options）。

5.2 查看集群成员

bash bin/seatunnel-cluster.sh -m

⚠️ 该命令读取发现配置并列出成员；单节点实测输出与 seatunnel.sh -l 顶部成员块一致：Member [localhost]:5801 - be7b2e48-9b3a-4b11-928b-fe69ea95f509 [master node]。

5.3 systemd 托管场景

生产建议用 systemd 托管（单元写法与实测见《Apache SeaTunnel 安装指南》4.8）：

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

实测回显：

active

systemd 托管节点上提交作业（实测）：

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

六、install-plugin.sh 详解（连接器安装）

6.1 基本用法

bash bin/install-plugin.sh -h

脚本头注释（实测）：

# connector default version is 2.3.12, you can also choose a custom version. eg: 2.3.12: sh install-plugin.sh 2.3.12

即标准用法为（版本参数可选，默认 2.3.12）：

bash bin/install-plugin.sh
bash bin/install-plugin.sh 2.3.12

实测启动回显：

Install SeaTunnel connectors plugins, usage version is 2.3.12

6.2 只安装指定连接器

脚本按 config/plugin_config 清单逐条下载未注释的连接器（实测 Maven 拉取样例）：

[INFO] --- maven-dependency-plugin:2.8:get (default-cli) @ standalone-pom ---
[INFO] Resolving org.apache.seatunnel:connector-cdc-tidb:jar:2.3.12

要只装一个连接器（如 connector-jdbc），编辑 config/plugin_config 把其余 --connectors-v2-- 段的行注释掉，只留：

--connectors-v2--
connector-jdbc

再执行 bash bin/install-plugin.sh。装完 jar 落在 /opt/seatunnel/connectors/，JDBC 驱动（如 mysql-connector-j）需手动复制到 /opt/seatunnel/lib/。

⚠️ 实测 2.3.12 该脚本不支持 --install connector-jdbc 写法：传参会被当作版本号解析（回显 Resolving org.apache.seatunnel:connector-cdc-tidb:jar:--install 失败）。发行版自带的 connector-fake、connector-console 无需安装即可用。

七、REST API 与排障命令

7.1 常用 REST 接口

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/

实测回显：

[]

常用端点速查：/overview/（集群概况）、/running-jobs/、/finished-jobs/、/running-job/<jobId>/metrics（以官方文档为准）。开启 Basic 认证后统一加 curl -u admin:q1w2e3r4 前缀（示例账号，见配置篇）。

7.2 排障命令组合

# 进程与堆
ps -ef | grep [S]eaTunnelServer | grep -o 'Xmx512m'
# 端口监听
netstat -tlnp | grep -E '5801|8080'
# 日志（滚动）
tail -f /opt/seatunnel/logs/seatunnel-engine-server.log
tail -f /opt/seatunnel/logs/seatunnel-server.out

八、常见问题

Q1：用 sh bin/seatunnel.sh 报错？ Ubuntu 22.04 /bin/sh 是 dash，实测开头连续输出：

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

一律改用 bash bin/seatunnel.sh。

Q2：--list-jobs 不是合法选项？ 实测按缺 --config 的提交路径报 NPE：

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

列作业用 -l。

Q3：--metrics -j <id> 报 NumberFormatException？ --metrics 的 JobId 值直接跟在选项后：bash bin/seatunnel.sh --metrics 1161855771885961217。带 -j 时 -j 被当成 --metrics 的值解析，实测报：

Caused by: java.lang.NumberFormatException: For input string: "-j"

Q4：提交时报找不到连接器 jar？ 仅发行版自带 connector-fake/connector-console/cdc-base；其他连接器需 install-plugin.sh 安装（第六节），或检查 plugin-mapping.properties 与连接器名大小写。

Q5：systemd 启动后一直 activating？ 常见为 5801 被残留进程占用（实测排障过程：netstat -tlnp | grep 5801 找到旧 java 进程，kill 后 systemctl restart 恢复 active）。

九、参考链接

CLI 官方文档：https://seatunnel.apache.org/docs/2.3.12/seatunnel-engine/cli
REST API v2：https://seatunnel.apache.org/docs/2.3.12/seatunnel-engine/rest-api-v2
连接器列表：https://seatunnel.apache.org/docs/2.3.12/category/source-v2
安装指南（本专栏）