保姆级 SeaTunnel 入门！再学不会小编当场表演倒立敲代码

欢迎来到 Apache SeaTunnel 的世界！这份文档旨在帮助新手快速了解 SeaTunnel 的核心功能、基本架构，并完成第一个数据同步任务。

1. 什么是 Apache SeaTunnel？

Apache SeaTunnel 是一个非常易于使用、高性能、支持实时流式和离线批处理的海量数据集成平台。它的目标是解决常见的数据集成问题，如数据源多样性、同步场景复杂性以及资源消耗高的问题。

核心特性

丰富的数据源支持：支持 100+ 种 Connector，涵盖主流数据库、云存储、SaaS 服务等。
批流一体：同一套 Connector 代码同时支持批处理（离线）和流处理（实时）。
高性能：支持多引擎（Zeta, Flink, Spark），提供高吞吐、低延迟的数据同步能力。
简单易用：通过简单的配置文件（Config）即可定义复杂的数据同步任务。

2. 架构与环境

2.1 架构图

SeaTunnel 采用了解耦的设计架构，Source、Transform、Sink 插件与具体的执行引擎（Engine）是分离的。

2.2 操作系统支持

SeaTunnel 基于 Java 开发，理论上支持所有安装了 JDK 的操作系统。

操作系统	适用场景	说明
Linux (CentOS, Ubuntu, etc.)	生产环境 (推荐)	稳定性高，适合长期运行服务。
macOS	开发/测试	适合开发者本地调试和编写 Config。

2.3 环境准备

在开始安装 SeaTunnel 之前，请确保你的环境满足以下要求：

JDK 版本 ：必须安装 Java 8 或 Java 11 。
- 可以通过命令 java -version 检查。
- 确保设置了 JAVA_HOME 环境变量。

3. 核心组件深度解析

在使用 SeaTunnel 之前，深入理解其核心组件的内部机制有助于你更好地调优和排查问题。

3.1 Source (数据源)

Source 负责从外部系统读取数据，并将其转换为 SeaTunnel 内部的行格式（SeaTunnelRow）。

Enumerator (枚举器) ：运行在 Master 节点（Coordinator）。负责发现数据分片（Splits）。例如，在 JDBC Source 中，Enumerator 会根据 partition_column 的最大值和最小值计算出多个查询范围（Splits）。
Reader (读取器)：运行在 Worker 节点。负责接收 Enumerator 分配的 Splits，并真正执行读取操作。多个 Reader 并行工作，极大提高了读取效率。
Checkpoint 支持：对于流式作业，Source 还需要支持状态保存（如 Kafka 的 Offset），以便在故障恢复时实现断点续传。

3.2 Transform (数据转换)

Transform 负责在数据从 Source 流向 Sink 的过程中对数据进行处理。

无状态转换 ：大多数 Transform（如 Sql, Filter, Replace）是无状态的，即处理当前行不需要依赖其他行的数据。
Schema 变更：Transform 可以改变数据的 Schema（增加、删除、修改字段），下游 Sink 会感知到这种变化。

3.3 Sink (数据目标)

Sink 负责将 SeaTunnel 处理后的数据写入到外部系统。

Writer (写入器)：运行在 Worker 节点。负责将数据写入目标系统。通常支持批量写入以提高吞吐量。
Committer (提交器) ：运行在 Master 节点（可选）。对于支持事务的 Sink（如文件系统、Iceberg），需要一个全局的 Committer 来在 Checkpoint 完成时统一提交事务（二阶段提交），从而实现 Exactly-Once（精确一次）语义。

3.4 执行流程

解析配置：SeaTunnel 解析配置文件，构建逻辑执行计划。
资源分配：Master 节点根据并行度申请资源。
任务分发：Enumerator 生成分片，分发给 Reader。
数据流转 ：Reader -> Transform -> Writer。
状态提交：周期性触发 Checkpoint，保存状态并提交事务。

4. 支持的 Connector 及其优缺点分析

SeaTunnel 支持超过 100 种 Connector，以下是几类最常用的 Connector 及其特性分析：

4.1 关系型数据库 (JDBC)

支持列表: MySQL, PostgreSQL, Oracle, SQLServer, DB2, Teradata, Dameng(达梦), OceanBase, TiDB 等。

优点：
- 通用性强：只要有 JDBC 驱动即可连接几乎所有 SQL 数据库。
- 功能完善 ：支持列投影（只读部分列）、并行读取（基于 partition_column 切分）、Exactly-Once（取决于实现）。
- 自动建表：部分 Connector 支持在目标端自动创建表结构。
缺点：
- 性能瓶颈 ：受限于 JDBC 协议和单机驱动性能，超大规模数据读取可能需要精细调优（如 fetch_size）。
- 源库压力：如果并行度设置过高，可能打满源库连接池或 CPU。

4.2 消息队列

支持列表: Kafka, Pulsar, RocketMQ, Amazon DynamoDB Streams 等。

优点：
- 高吞吐：天生适合大规模流数据处理，支持削峰填谷。
- 格式丰富：支持 JSON, Avro, Protobuf, Canal-JSON, Debezium-JSON 等多种序列化格式。
- Exactly-Once：支持端到端的精确一次语义（依赖 Checkpoint 机制）。
缺点：
- 配置复杂：涉及 Offset 管理、序列化 Schema 配置、Consumer Group 管理等。
- 数据可见性：相比数据库，数据在 Topic 中不够直观，调试稍显麻烦。

4.3 变更数据捕获 (CDC)

支持列表: MySQL-CDC, PostgreSQL-CDC, Oracle-CDC, MongoDB-CDC, SQLServer-CDC, TiDB-CDC 等。

优点：
- 实时性：毫秒级捕获数据库增删改操作。
- 无锁读取：SeaTunnel 的 CDC 实现了无锁并行快照算法，极大降低了对源库的影响。
- 断点续传：支持从 Binlog/WAL 指定位置恢复。
- Schema Evolution：支持表结构变更同步（部分支持）。
缺点：
- 权限要求：通常需要较高的数据库权限（如 REPLICATION SLAVE）。
- 依赖日志：源库必须开启 Binlog（或 WAL），且保留时间需足够长。

4.4 文件系统 & 云存储

支持列表: LocalFile, HDFS, S3, OSS, GCS, FTP, SFTP 等。

优点：
- 海量存储：适合数据湖场景，成本低廉。
- 格式支持：原生支持 Parquet, ORC, Avro, JSON, CSV, Excel, Text 等。
- 压缩支持：支持 Snappy, Gzip, Lzo 等多种压缩算法。
缺点：
- 小文件问题：流式写入时，如果 Checkpoint 间隔太短，容易产生大量小文件（SeaTunnel 有文件合并功能但会增加复杂度）。

4.5 NoSQL & 其他

支持列表: Elasticsearch, Redis, MongoDB, Cassandra, HBase, InfluxDB, ClickHouse, Doris, StarRocks 等。

特点：针对各数据库特性进行了优化，例如 ClickHouse/StarRocks 支持 Stream Load 高速导入，Elasticsearch 支持批量写入。

5. Transform 实战演练 (附带详细注释)

Transform 插件用于在 Source 和 Sink 之间处理数据。以下是几个常用 Transform 的配置示例。

5.1 Sql Transform (最推荐)

使用 SQL 语法对数据进行处理，支持重命名、计算、常量添加、过滤等。

hocon 复制代码

transform {
  Sql {
    # 输入表名，必须与 Source 的 result_table_name 一致
    plugin_input = "fake"
    # 输出表名，供后续 Transform 或 Sink 使用
    plugin_output = "fake_sql"
    
    # SQL 查询语句
    # 1. name as full_name: 字段重命名
    # 2. age + 1: 数值计算
    # 3. 'US' as country: 增加常量列
    # 4. where age > 10: 数据过滤
    query = "select name as full_name, age + 1 as next_year_age, 'US' as country from fake where age > 10"
  }
}

5.2 Filter Transform

用于删除或保留指定字段（注意：不是过滤行，是过滤列/字段）。

hocon 复制代码

transform {
  Filter {
    plugin_input = "fake"
    plugin_output = "fake_filter"
    
    # 仅保留 name 和 age 字段，其他字段会被丢弃
    include_fields = ["name", "age"]
    
    # 或者使用 exclude_fields 删除指定字段
    # exclude_fields = ["card"]
  }
}

5.3 Replace Transform

用于字符串替换，支持正则表达式。

hocon 复制代码

transform {
  Replace {
    plugin_input = "fake"
    plugin_output = "fake_replace"
    
    # 需要替换的字段名
    replace_field = "name"
    # 匹配模式（旧字符串）
    pattern = " "
    # 替换后的字符串（新字符串）
    replacement = "_"
    # 是否使用正则表达式，这里设为 true，表示 pattern 是一个正则
    is_regex = true
    # 是否只替换第一个匹配项
    replace_first = true
  }
}

5.4 Split Transform

将一个字符串字段拆分为多个字段。

hocon 复制代码

transform {
  Split {
    plugin_input = "fake"
    plugin_output = "fake_split"
    
    # 分隔符，这里使用空格
    separator = " "
    # 需要拆分的源字段
    split_field = "name"
    # 拆分后生成的新字段名列表
    output_fields = ["first_name", "last_name"]
  }
}

6. 快速安装

对于新手，推荐直接下载编译好的二进制发行包进行体验。

步骤 1: 下载

前往 SeaTunnel 下载页面下载最新版本的二进制包（例如 apache-seatunnel-2.3.x-bin.tar.gz）。

步骤 2: 解压

bash 复制代码

tar -xzvf apache-seatunnel-2.3.x-bin.tar.gz
cd apache-seatunnel-2.3.x

步骤 3: 安装 Connector 插件

SeaTunnel 的 Connector 是插件化的。首次使用需要下载插件：

bash 复制代码

sh bin/install-plugin.sh

注意：该命令会根据 config/plugin_config 文件中的配置，从 Maven 中央仓库下载常用插件（如 connector-fake, connector-console 等）。如果下载速度慢，请耐心等待或配置 Maven 镜像。

💡 技巧：配置 Maven 国内镜像加速下载

如果遇到下载速度极慢或超时失败的情况，建议配置 Maven 阿里云镜像。

找到或创建 Maven 配置文件：~/.m2/settings.xml (Windows 下为 C:\Users\你的用户名\.m2\settings.xml)。
添加如下镜像配置：

xml 复制代码

<settings>
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>*</mirrorOf>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
</settings>

保存后再次运行 sh bin/install-plugin.sh 即可享受高速下载。

7. 实战：第一个 SeaTunnel 任务

我们将创建一个简单的任务：生成一些随机数据（FakeSource），并将其打印到控制台（Console Sink）。

步骤 1: 创建配置文件

在 config 目录下创建一个名为 hello_world.conf 的文件，内容如下：

hocon 复制代码

env {
  # 并行度设置：决定了有多少个线程同时执行任务。
  # 设置为 1 表示单线程执行，适合测试；生产环境可根据资源调大。
  parallelism = 1
  # 作业模式：
  # BATCH (批处理)：一次性处理完数据后结束（如离线同步）。
  # STREAMING (流处理)：持续运行，实时处理数据（如实时同步）。
  job.mode = "BATCH"
}

source {
  # FakeSource 是一个虚拟数据源，用于生成测试数据
  FakeSource {
    # result_table_name: 将此数据源产生的数据注册为一个临时表，表名为 "fake"
    # 后续的 Transform 或 Sink 可以通过这个名字引用这份数据
    result_table_name = "fake"
    
    # row.num: 指定生成数据的总行数，这里生成 16 行数据
    row.num = 16
    
    # schema: 定义数据的结构（字段名和类型）
    schema = {
      fields {
        name = "string" # 定义一个名为 name 的字符串字段
        age = "int"     # 定义一个名为 age 的整型字段
      }
    }
  }
}

transform {
  # Sql Transform: 使用 SQL 语句对数据进行处理
  Sql {
    # plugin_input: 指定输入数据来源，这里引用了 Source 中定义的 "fake" 表
    plugin_input = "fake"
    
    # plugin_output: 指定处理后的结果表名，命名为 "fake_transformed"
    # 下游的 Sink 将使用这个名字来获取处理后的数据
    plugin_output = "fake_transformed"
    
    # query: 执行的 SQL 查询语句
    # 这里演示了选择 name 和 age 字段，并新增一个常量字段 new_field
    query = "select name, age, 'new_field_val' as new_field from fake"
  }
}

sink {
  # Console Sink: 将数据输出打印到控制台（标准输出）
  Console {
    # plugin_input: 指定要输出的数据来源，这里引用了 Transform 输出的 "fake_transformed" 表
    plugin_input = "fake_transformed"
  }
}

步骤 2: 运行任务

使用 SeaTunnel 自带的 Zeta 引擎运行该任务。

执行命令：

bash 复制代码

./bin/seatunnel.sh --config ./config/hello_world.conf -e local

命令详解：

./bin/seatunnel.sh: 启动脚本，默认使用 Zeta 引擎。
--config (或 -c): 指定配置文件的路径。这里我们指定了刚才创建的 hello_world.conf。
-e local (或 -m local): 指定执行模式。
- local: 本地模式。SeaTunnel 会在当前进程中启动一个轻量级的 Zeta 引擎集群来运行任务，任务结束后集群关闭。适合开发和测试。
- cluster: 集群模式。任务会提交到已经运行的 SeaTunnel 集群中执行。适合生产环境。

步骤 3: 查看结果与日志分析

任务启动后，终端会输出大量日志。我们需要关注以下关键信息：

任务提交成功 ：

看到 Job execution started 表示配置文件解析通过，任务已提交给引擎。

数据处理过程 ：

由于我们使用的是 Console Sink，数据会直接打印在日志中。你应能看到类似如下的输出：

text 复制代码

...
INFO  ...ConsoleSinkWriter - subtaskIndex=0 rowIndex=1: SeaTunnelRow#tableId=-1 SeaTunnelRow#kind=INSERT: CpiOd, 12345, new_field_val
INFO  ...ConsoleSinkWriter - subtaskIndex=0 rowIndex=2: SeaTunnelRow#tableId=-1 SeaTunnelRow#kind=INSERT: eQqTs, 67890, new_field_val
...

subtaskIndex: 并行任务的编号。
rowIndex: 当前处理的行号。
SeaTunnelRow: 打印出的具体数据内容。

任务结束 ：

最后看到 Job Execution Status: FINISHED 表示任务执行成功结束。

8. 常见问题排查 (Troubleshooting)

如果在运行过程中遇到报错，请参考以下常见问题进行排查：

🔴 问题 1: `command not found: java` 或 `JAVA_HOME is not set`

现象：运行脚本时直接报错，提示找不到 Java。
原因：环境未安装 Java 或未配置环境变量。
解决：
1. 运行 java -version 确认 Java 8 或 11 已安装。
2. 设置环境变量：export JAVA_HOME=/path/to/your/java (建议写入 ~/.bashrc 或 ~/.zshrc)。

🔴 问题 2: `Exception in thread "main" ... ClassNotFoundException`

现象：报错提示找不到某个类，例如 ClassNotFoundException: org.apache.seatunnel.connectors.seatunnel.fake.source.FakeSourceFactory。
原因：Connector 插件未安装。默认包中只有引擎核心，没有包含具体的数据源插件。
解决：
- 确保你执行过 sh bin/install-plugin.sh。
- 检查 connectors/seatunnel 目录下是否有对应的 jar 包（例如 connector-fake-*.jar）。

🔴 问题 3: `Config file not valid` 或 `HOCONSyntaxError`

现象：提示配置文件格式错误。
原因：hello_world.conf 中的括号 {} 不匹配，或者关键字拼写错误。
解决：仔细检查配置文件语法。SeaTunnel 使用 HOCON 格式，确保每一层级的 { 和 } 都是成对出现的。

🔴 问题 4: 任务卡住不动

现象：日志停止更新，但任务没有结束。
原因：可能是资源不足（CPU/内存），或者在流模式（STREAMING）下这是正常现象（流任务是无休止运行的）。
解决：
- 如果是 BATCH 模式卡住，检查 plugin_config 里的内存设置。
- 检查是否在 env 中错误地设置了 job.mode = "STREAMING"。

9. 进阶学习资源

官方文档 : https://seatunnel.apache.org/docs/
Connector 列表 : 查看 docs/en/connector-v2 目录，了解所有支持的数据源。
示例代码 : 在 config 目录下通常会有一些模板文件（如 v2.batch.config.template），可以作为参考。

Apache SeaTunnel 批流一体、生态丰富、部署轻便，入门有指南，实战有案例。即刻上手探索，加入开源社区，让数据流转更简单，为数据工程高效赋能！祝你学习愉快！

保姆级 SeaTunnel 入门！再学不会小编当场表演倒立敲代码

1. 什么是 Apache SeaTunnel？

核心特性

2. 架构与环境

2.1 架构图

2.2 操作系统支持

2.3 环境准备

3. 核心组件深度解析

3.1 Source (数据源)

3.2 Transform (数据转换)

3.3 Sink (数据目标)

3.4 执行流程

4. 支持的 Connector 及其优缺点分析

4.1 关系型数据库 (JDBC)

4.2 消息队列

4.3 变更数据捕获 (CDC)

4.4 文件系统 & 云存储

4.5 NoSQL & 其他

5. Transform 实战演练 (附带详细注释)

5.1 Sql Transform (最推荐)

5.2 Filter Transform

5.3 Replace Transform

5.4 Split Transform

6. 快速安装

步骤 1: 下载

步骤 2: 解压

步骤 3: 安装 Connector 插件

💡 技巧：配置 Maven 国内镜像加速下载

7. 实战：第一个 SeaTunnel 任务

步骤 1: 创建配置文件

步骤 2: 运行任务

步骤 3: 查看结果与日志分析

8. 常见问题排查 (Troubleshooting)

🔴 问题 1: command not found: java 或 JAVA_HOME is not set

🔴 问题 2: Exception in thread "main" ... ClassNotFoundException

🔴 问题 3: Config file not valid 或 HOCONSyntaxError

🔴 问题 4: 任务卡住不动

9. 进阶学习资源

🔴 问题 1: `command not found: java` 或 `JAVA_HOME is not set`

🔴 问题 2: `Exception in thread "main" ... ClassNotFoundException`

🔴 问题 3: `Config file not valid` 或 `HOCONSyntaxError`