企业官网建设流程全解析

• 数据集成
• ETL
• 大数据
• 批处理
• 流处理
• 变更数据捕获

SeaTunnel 是一个多模态、高性能、分布式的海量数据集成工具，通过声明式配置即可完成 Source（数据来源）、Transform（数据变换）与 Sink（数据目标）之间的数据流转。本指南以官方文档的"本地快速开始"路径为主线，带你用最短路径在本机完成 SeaTunnel 部署、插件安装、首个任务运行，并系统讲解作业配置结构与 Flink/Spark 引擎的可选路径。读完本文，你将掌握本地跑通 SeaTunnel 任务的全流程能力，并能从内置示例平滑迁移到 MySQL、Doris、Kafka、Iceberg 等真实业务链路。

先选一条本地起步路径

SeaTunnel 支持多种引擎运行方式，不同情况对应不同的推荐入口：

对大多数第一次接触 SeaTunnel 的用户来说，SeaTunnel 引擎（Zeta）是最推荐的起步路径：它由 SeaTunnel 内置，无需额外部署第三方计算集群，部署最短、反馈最快、最适合作为首跑路径。只有当团队已经维护 Flink 集群或现有作业体系围绕 Spark 时，才优先考虑 Flink/Spark 路径。

推荐首跑顺序如下：

1. 先完成部署章节的安装与插件准备；
2. 安装示例任务所需的插件；
3. 通过跑第一个任务或SeaTunnel 引擎快速开始跑通首个本地作业；
4. 示例成功后，再进入作业配置指南编写真实作业。

更稳妥的顺序仍然是先把本地链路跑通，再进入集群部署或远程提交（可参考 submit-job-to-remote-zeta-cluster.md）。

准备工作：环境依赖

在开始本地运行前，需要确保已安装 SeaTunnel 所依赖的软件：

• Java：需要 Java 8 或 11（其他高于 Java 8 的版本理论上也可以工作），并正确设置JAVA_HOME环境变量。

下载 SeaTunnel 发行包

下载二进制包

从 SeaTunnel 下载页面获取最新版本的二进制安装包seatunnel-<version>-bin.tar.gz，也可以通过终端直接下载：

export version="3.0.0" wget "https://archive.apache.org/dist/seatunnel/${version}/apache-seatunnel-${version}-bin.tar.gz" tar -xzvf "apache-seatunnel-${version}-bin.tar.gz"

解压后得到的apache-seatunnel-${version}目录即${SEATUNNEL_HOME}，后续命令均在该目录下执行。

下载连接器插件

从 2.2.0-beta 版本开始，二进制包不再默认提供连接器依赖，因此在第一次使用时需要执行以下命令安装连接器：

sh bin/install-plugin.sh

如果需要指定连接器版本（以 3.0.0 为例）：

sh bin/install-plugin.sh 3.0.0

关于install-plugin.sh的下载机制，官方文档给出了明确的版本差异说明：

• 正式发布的连接器版本：脚本通过 HTTPS 直接下载 JAR 及其校验文件，因此 Linux 和 macOS 不需要 Maven。该方式需要curl、mktemp，以及sha512sum、sha1sum、shasum或openssl中的任意一个用于校验。
• Windows 环境：install-plugin.cmd仍使用发行包内置的 Maven Wrapper。
• 自定义 Maven 镜像：如果需要为install-plugin.sh使用 Maven 兼容的 HTTPS 镜像，可通过SEATUNNEL_MAVEN_REPOSITORY指定仓库根地址：

SEATUNNEL_MAVEN_REPOSITORY=https://repo.example.com/maven2 \ sh bin/install-plugin.sh 3.0.0

• 快照与版本范围：直接下载仅支持提供.sha512或.sha1校验文件的不可变正式版本。SNAPSHOT、LATEST、RELEASE和版本范围需要解析 Maven 元数据，此时脚本会自动使用发行包内置的 Maven Wrapper。如果需要继续使用 Mavensettings.xml中的镜像、认证仓库、代理或自定义 TLS 策略，也可以设置SEATUNNEL_PLUGIN_DOWNLOAD_METHOD=maven。

（也可以从 Apache Maven Repository 手动下载连接器 JAR，放入connectors/目录下；如果是 2.3.5 之前的版本，则需要放入connectors/seatunnel目录。）

按需精简插件列表

通常情况下，你不需要安装全部连接器插件，可以通过配置 config/plugin_config 来指定所需插件。以让示例应用正常工作为例，只需要connector-console和connector-fake，可将plugin_config精简为：

--seatunnel-connectors-- connector-fake connector-console --end--

仓库根目录的 plugin-mapping.properties 列出了所有受支持的连接器及其对应的 plugin_config 配置名称，可作为按需选择插件的参考清单。

提示：手动下载方式下，只需下载需要的连接器插件，并放入${SEATUNNEL_HOME}/connectors/目录即可。

开发者说明：本地部署指南默认面向使用官方二进制发行包的用户。如果需要验证未发布代码、调试 SeaTunnel 源码或构建自定义发行包，请参考 搭建开发环境。

跑第一个任务：最短路径验证本地链路

这一节只解决一件事：用最短路径把 SeaTunnel 真正跑起来。该示例完全本地运行，不依赖 MySQL、Kafka 或对象存储，适合先确认安装、配置解析和执行引擎都正常。

步骤 1：先完成本地部署。完成部署章节，并确认 SeaTunnel 目录下已经有bin/seatunnel.sh。

步骤 2：只安装示例真正需要的插件。将 config/plugin_config 收敛为connector-fake与connector-console两个插件，然后执行安装命令并确认插件已下载到${SEATUNNEL_HOME}/connectors：

cd "${SEATUNNEL_HOME}" sh bin/install-plugin.sh ls connectors | rg 'connector-(fake|console)'

步骤 3：使用最小可运行配置。仓库中的 config/v2.batch.config.template 即官方提供的批量任务模板，可将下面的配置保存为该文件或你自己的本地配置文件：

env { parallelism = 1 job.mode = "BATCH" } source { FakeSource { plugin_output = "fake" row.num = 16 schema = { fields { name = "string" age = "int" } } } } transform { FieldMapper { plugin_input = "fake" plugin_output = "fake1" field_mapper = { age = age name = new_name } } } sink { Console { plugin_input = "fake1" } }

步骤 4：用本地模式运行：

cd "apache-seatunnel-${version}" ./bin/seatunnel.sh --config ./config/v2.batch.config.template -m local

验证结果：

• 任务可以正常启动，没有 connector 加载错误；
• 控制台会打印映射后字段的output rowType行；
• 控制台会打印 16 行ConsoleSinkWriter输出；
• 批任务在写完全部数据后正常退出。

如果这里已经跑通，说明本地基础链路正常，后面就可以切换到真实数据源和真实目标端。

SeaTunnel 引擎（Zeta）快速开始

SeaTunnel Engine 既可以用于单机快速体验，也可以部署为多节点集群。使用方式对照如下：

单机快速开始（Local 模式）适合在单台机器上快速验证安装、连接器和作业配置，下面的命令都使用-m local启动 SeaTunnel Engine。

运行示例作业

步骤 1：部署 SeaTunnel 及连接器。按照部署下载并部署 SeaTunnel，确保connector-fake与connector-console已安装（sh bin/install-plugin.sh）。

步骤 2：添加作业配置文件。编辑config/v2.batch.config.template定义作业，它决定了 SeaTunnel 启动后数据输入、处理和输出的方式及逻辑，内容与上文的最小可运行配置一致。

步骤 3：运行 SeaTunnel 应用程序：

cd "apache-seatunnel-${version}" ./bin/seatunnel.sh --config ./config/v2.batch.config.template -m local

提示：从 2.3.1 版本开始，seatunnel.sh中的-e参数已被废弃，请改用-m参数。-m local表示以本地模式启动 SeaTunnel Engine。

查看输出：运行命令后，SeaTunnel 控制台会打印类似下面的日志信息，可据此判断命令运行成功或失败：

2022-12-19 11:01:45,417 INFO org.apache.seatunnel.connectors.seatunnel.console.sink.ConsoleSinkWriter - output rowType: new_name<STRING>, age<INT> 2022-12-19 11:01:46,489 INFO org.apache.seatunnel.connectors.seatunnel.console.sink.ConsoleSinkWriter - subtaskIndex=0 rowIndex=1: SeaTunnelRow#tableId=-1 SeaTunnelRow#kind=INSERT: CpiOd, 8520946 2022-12-19 11:01:46,490 INFO org.apache.seatunnel.connectors.seatunnel.console.sink.ConsoleSinkWriter - subtaskIndex=0 rowIndex=2: SeaTunnelRow#tableId=-1 SeaTunnelRow#kind=INSERT: eQqTs, 1256802974 2022-12-19 11:01:46,490 INFO org.apache.seatunnel.connectors.seatunnel.console.sink.ConsoleSinkWriter - subtaskIndex=0 rowIndex=3: SeaTunnelRow#tableId=-1 SeaTunnelRow#kind=INSERT: UsRgO, 2053193072 ...

日志中的关键信息有两类：第一行output rowType展示经过FieldMapper变换后的字段类型（new_name<STRING>, age<INT>），印证了 transform 的字段重命名与类型推导生效；随后的每行ConsoleSinkWriter输出对应一条 FakeSource 生成的模拟数据。从源码结构看，这两类日志分别来自 connector-console 的 ConsoleSinkWriter 在写入前的 rowType 打印与逐行写入打印，row.num = 16决定了打印行数为 16 行，与 connector-fake 的 FakeSource 的模拟数据生成逻辑相对应。

扩展示例：从 MySQL 到 Doris 批处理模式

当示例链路跑通后，可以将 Source 与 Sink 替换为真实连接器。下面是从 MySQL 批量同步到 Doris 的完整过程。

步骤 1：下载连接器。在${SEATUNNEL_HOME}/config/plugin_config中加入连接器名称，然后执行安装命令，最后确认connector-jdbc、connector-doris已在${SEATUNNEL_HOME}/connectors/目录下：

# 配置连接器名称 --seatunnel-connectors-- connector-jdbc connector-doris --end--

# 安装连接器 sh bin/install-plugin.sh

步骤 2：放入 MySQL 驱动。下载mysql-connector-java驱动 JAR，并放置在${SEATUNNEL_HOME}/lib/目录下。

步骤 3：添加作业配置文件：

cd seatunnel/job/ vim st.conf

env { parallelism = 2 job.mode = "BATCH" } source { Jdbc { url = "jdbc:mysql://localhost:3306/test" driver = "com.mysql.cj.jdbc.Driver" connection_check_timeout_sec = 100 user = "user" password = "pwd" table_path = "test.table_name" query = "select * from test.table_name" } } sink { Doris { fenodes = "doris_ip:8030" username = "user" password = "pwd" database = "test_db" table = "table_name" sink.enable-2pc = "true" sink.label-prefix = "test-cdc" doris.config = { format = "json" read_json_by_line="true" } } }

其中JdbcSource 通过url、driver、user、password建立数据库连接，query指定读取 SQL，connection_check_timeout_sec控制连接检查超时；DorisSink 通过fenodes指向 Doris FE 地址，sink.enable-2pc = "true"开启两阶段提交以保证写入一致性，sink.label-prefix设置流式导入 label 前缀，doris.config指定 JSON 格式导入参数。

步骤 4：运行 SeaTunnel 应用程序：

cd seatunnel/ ./bin/seatunnel.sh --config ./job/st.conf -m local

运行成功后控制台会打印作业统计信息，例如：

*********************************************** Job Statistic Information *********************************************** Start Time : 2024-08-13 10:21:49 End Time : 2024-08-13 10:21:53 Total Time(s) : 4 Total Read Count : 1000 Total Write Count : 1000 Total Failed Count : 0 ***********************************************

Total Read Count与Total Write Count一致且Total Failed Count为 0，说明 1000 条数据全部从 MySQL 读入并成功写入 Doris。如果需要优化作业，请参照对应连接器的使用文档调整参数。

集群部署

如果已经完成单机验证，并希望在多节点环境中运行 SeaTunnel Engine，请继续阅读 SeaTunnel Engine(Zeta) 安装部署。集群部署文档集中说明了：

• 不同部署模式的适用场景，包括 Local 模式、混合集群模式和分离集群模式；
• 混合集群模式与分离集群模式的部署步骤；
• 选择部署模式时的建议。

建议：如果只是想在一台机器上快速验证配置和任务链路，使用 Local 模式即可；如果需要多节点运行、资源隔离或更贴近测试和生产环境的部署方式，请进入集群部署文档继续操作。集群相关配置示例可参考 config/hazelcast-master.yaml、config/hazelcast-worker.yaml 与 config/seatunnel.yaml。

其他引擎路径：Flink 与 Spark

Flink 引擎快速开始

这一页适合已经明确要把 SeaTunnel 跑在 Flink 上的团队。如果你只是第一次评估 SeaTunnel，且没有必须使用 Flink 的前提，建议先从 SeaTunnel 引擎快速开始入手。

步骤 1：按部署完成 SeaTunnel 及连接器部署。

步骤 2：部署并配置 Flink。下载 Flink（需要版本 >= 1.12.0），然后修改 config/seatunnel-env.sh 中的设置，将FLINK_HOME配置为 Flink 的部署目录（仓库中该文件默认值为${FLINK_HOME:-/opt/flink}）。

步骤 3：添加作业配置文件。编辑 config/v2.streaming.conf.template，内容与示例作业一致（env、FakeSource、FieldMapper、Console）。

步骤 4：运行 SeaTunnel 应用程序。根据 Flink 版本选择对应启动脚本：

Flink 版本1.12.x到1.14.x：

cd "apache-seatunnel-${version}" ./bin/start-seatunnel-flink-13-connector-v2.sh --config ./config/v2.streaming.conf.template

Flink 版本1.15.x到1.18.x：

cd "apache-seatunnel-${version}" ./bin/start-seatunnel-flink-15-connector-v2.sh --config ./config/v2.streaming.conf.template

运行成功后控制台会打印fields : name, age、types : STRING, INT以及row=1 : elWaB, 1984352560形式的 16 行数据输出。

Spark 引擎快速开始

适合已经明确要把 SeaTunnel 跑在 Spark 上的团队。前置阅读可参考引擎概览与SeaTunnel 运行在 Spark 上。

步骤 1：按部署完成 SeaTunnel 及连接器部署。

步骤 2：部署并配置 Spark。下载 Spark（需要版本 >= 2.4.0），然后修改 config/seatunnel-env.sh，将SPARK_HOME修改为 Spark 的部署目录（仓库中默认值为${SPARK_HOME:-/opt/spark}）。

步骤 3：添加作业配置文件。编辑 config/v2.streaming.conf.template。

步骤 4：运行 SeaTunnel 应用程序。根据 Spark 版本选择对应启动脚本：

Spark 2.4.x：

cd "apache-seatunnel-${version}" ./bin/start-seatunnel-spark-2-connector-v2.sh \ --master local[4] \ --deploy-mode client \ --config ./config/v2.streaming.conf.template

Spark 3.x.x：

cd "apache-seatunnel-${version}" ./bin/start-seatunnel-spark-3-connector-v2.sh \ --master local[4] \ --deploy-mode client \ --config ./config/v2.streaming.conf.template

--master local[4]指定本地模式与 4 个执行线程，--deploy-mode client指定客户端部署模式。运行成功后的输出格式与 Flink 路径一致（fields/types/row=N的 16 行数据）。

作业配置指南：从示例到真实链路

SeaTunnel 的大多数作业都通过声明式配置完成，无需先写代码，而是通过配置文件描述执行环境、数据来源、可选转换以及写入目标。

配置结构总览

大多数 SeaTunnel 作业遵循相同的顶层结构：

env { parallelism = 1 job.mode = "BATCH" } source { FakeSource { plugin_output = "fake" row.num = 16 schema = { fields { name = "string" age = "int" } } } } transform { FieldMapper { plugin_input = "fake" plugin_output = "renamed" field_mapper = { name = user_name age = age } } } sink { Console { plugin_input = "renamed" } }

从职责上看：

• env控制作业如何执行；
• source定义数据从哪里来；
• transform负责链路中的数据变换（可选）；
• sink定义数据最终写到哪里。

各配置块详解

env配置块用于配置作业级别的执行参数，常见参数如下：

如果使用 Flink 或 Spark，引擎特定参数也放在env中。仓库中的 config/v2.batch.config.template 同时展示了parallelism = 2、job.mode = "BATCH"、checkpoint.interval = 10000的写法。

source配置块描述 SeaTunnel 如何从外部系统读取数据，通常包括：连接器名称、连接参数、读取范围（表、topic、路径或查询）、schema 或 format 相关参数，以及用于给下游插件显式引用当前输出的plugin_output。如果一个作业里有多个 source，建议显式命名每个 source 的输出。

transform配置块是可选的，当数据写入目标之前需要过滤、改名、映射、增强或校验时可以在这里完成。常见场景包括：字段重命名或字段映射、行过滤、RowKind 处理、SQL 转换、写入前的数据校验。如果业务链路不需要中间转换，可以完全省略这一段，直接从source到sink。

sink配置块定义 SeaTunnel 如何把数据写入目标系统，通常包括：连接器名称、连接参数、目标表/topic/路径、写入语义或批处理相关参数，以及用于声明消费哪个上游输出的plugin_input。不同 sink 的可选项不一样，具体参数、默认值和样例以对应连接器文档为准（可参考数据来源连接器总览与数据写入连接器总览）。

plugin_input 与 plugin_output

这两个字段是理解 SeaTunnel 数据流向的关键约定：

• plugin_output用来给 source 或 transform 的输出命名；
• plugin_input用来让 transform 或 sink 指向某个上游输出。

在以下场景中它们尤其重要：一个作业中存在多个 source；一个 transform 的输出要写入多个 sink；任务链路较复杂需要保证配置可读性。如果链路只有一个上游，SeaTunnel 往往可以依赖默认约定继续向下流转，但从可维护性角度仍然建议显式命名。

支持的配置格式

SeaTunnel 支持多种配置方式：HOCON（默认也是最常用的格式）、JSON（适合由其他系统自动生成配置）、SQL（适合 SQL 导向的作业表达方式）。格式细节可继续阅读配置文件简介与SQL 配置。

如何从示例迁移到真实作业

推荐按下面顺序逐步替换：

1. 保留示例中的env基本结构；
2. 用真实 Source 替换FakeSource；
3. 用真实 Sink 替换Console；
4. 只有在源表结构和目标结构不直接匹配时，再补充 transform；
5. 按连接器要求补充驱动 JAR 或额外依赖。

例如：MySQL -> Doris、Kafka -> Iceberg、S3File -> StarRocks、PostgreSQL CDC -> Kafka。这些端到端场景在 场景教程 recipes 中有完整可运行示例，如 MySQL CDC 到 Kafka、MySQL CDC 到 Doris、JDBC 到 S3、Kafka 到 Iceberg、Http 到 JDBC、File 到 StarRocks 与多表 CDC。

运行前检查清单

在真正启动作业之前，建议确认以下事项：

• Java 和JAVA_HOME已正确配置；
• 所需插件已经安装；
• 第三方驱动 JAR 已就位（例如 MySQL 驱动放入${SEATUNNEL_HOME}/lib/）；
• Source 凭据与网络访问正确；
• 目标表、topic 或路径在需要时已提前创建；
• job.mode与连接器能力相匹配。

源码级印证：本指南涉及的核心组件

本指南涉及的示例链路（FakeSource→FieldMapper→Console）在仓库中均有对应实现：

• FakeSource 模拟数据源：位于 seatunnel-connectors-v2/connector-fake/src，负责按schema.fields声明的字段结构生成指定row.num条随机模拟数据，是本地验证链路最常用的无外部依赖 Source；
• Console Sink 输出：位于 seatunnel-connectors-v2/connector-console/src，其中ConsoleSinkWriter在写入前打印output rowType，逐行打印SeaTunnelRow#kind=INSERT: <name>, <age>形式的数据，与快速开始文档中的控制台输出一一对应；
• JDBC 连接器：位于 seatunnel-connectors-v2/connector-jdbc/src，用于 MySQL 等关系型数据库的读取与写入，共 405 个 Java 源文件，是扩展示例中读取 MySQL 的核心；
• Doris 连接器：位于 seatunnel-connectors-v2/connector-doris/src，支持通过sink.enable-2pc等参数控制写入语义。

从源码结构看，seatunnel.sh的-m local参数对应 SeaTunnel Engine 的本地运行模式，而-e参数从 2.3.1 版本起废弃，这与官方文档的说明一致。如需理解 SeaTunnel API 如何被适配到 Flink/Spark，可继续阅读 Flink 转换层 与 Spark 转换层。

下一步

• 需要先跑通一个可执行示例：查看 SeaTunnel 引擎快速开始；
• 需要看一条更接近真实业务的完整链路：查看 场景教程；
• 需要具体参数说明：查看数据来源连接器总览和数据写入连接器总览；
• 需要了解转换能力：查看数据转换总览；
• 需要理解引擎差异：查看执行引擎概览；
• 需要部署多节点 SeaTunnel Engine 集群：继续阅读 SeaTunnel Engine(Zeta) 安装部署；
• 需要进一步了解 SeaTunnel Engine 本身：参阅 SeaTunnel 引擎。

只要本地链路跑通，后续无论是切换真实数据源、扩展到流式处理，还是部署多节点集群，都可以在此基础上平滑进行。

• 数据集成
• ETL
• 大数据
• 批处理
• 流处理
• 变更数据捕获