架构总览

相关源文件

本页面内容基于以下源文件生成：

• docs/en/architecture/overview.md
• README.md
• seatunnel-engine/README.md

SeaTunnel 是一个分布式、多模态、高性能的数据集成工具，专为解决大规模数据同步场景而设计。该项目通过分层架构实现了引擎无关性，允许同一套连接器在 SeaTunnel Engine (Zeta)、Apache Flink 或 Apache Spark 上运行，同时提供高吞吐量、低延迟和强一致性的数据同步能力。

设计目标与定位

SeaTunnel 的核心设计围绕五大目标展开，旨在解决现代数据集成中的关键挑战。

核心设计目标

引擎独立性：将连接器逻辑与执行引擎解耦，使开发者只需编写一次连接器，即可在多种执行引擎上运行。这种设计显著降低了维护成本，并提供了极大的部署灵活性（docs/en/architecture/overview.md:14）。

高性能：支持大规模数据同步，提供超高吞吐量和低延迟。SeaTunnel Engine 的执行计划优化器通过减少网络传输来降低序列化/反序列化开销，从而提升整体性能（seatunnel-engine/README.md:7）。

容错性：通过分布式快照和两阶段提交提供 exactly-once 语义，确保数据一致性（docs/en/architecture/overview.md:16）。

易用性：提供简单的配置方式和丰富的连接器生态系统，支持超过 160 种连接器（README.md:22）。

可扩展性：基于插件的架构设计，允许轻松添加新的连接器和转换逻辑（docs/en/architecture/overview.md:18）。

目标应用场景

SeaTunnel 针对以下核心场景进行了优化：

SeaTunnel 解决了数据集成中的常见挑战：多样化的数据源、复杂的同步场景（实时、CDC、全量）、资源效率以及数据质量监控（README.md:14-19）。

分层架构设计

SeaTunnel 采用清晰的分层架构，实现关注点分离和高度灵活性。整体架构从上到下分为五层，每层承担特定职责。

正在加载图表渲染器...

各层职责详解

配置层：负责作业定义和参数配置。支持 HOCON 格式配置文件、SQL 语法以及 Web UI 交互方式。配置验证器确保作业定义的正确性（docs/en/architecture/overview.md:80）。

API 层：提供连接器的统一抽象。核心接口包括：

• SeaTunnelSource：数据源读取接口
• SeaTunnelSink：数据目的地写入接口
• SeaTunnelTransform：数据转换接口
• CatalogTable 和 TableSchema：表结构和 Schema 管理
• SchemaChangeEvent：Schema 变更事件处理（docs/en/architecture/overview.md:42-44）

连接器层：实现具体的数据源和目的地。包含 JDBC、Kafka、MySQL-CDC、Elasticsearch、Iceberg 等 160+ 连接器（docs/en/architecture/overview.md:51）。

转换层：将 SeaTunnel API 适配到引擎特定 API。包含 Flink/Spark 适配器、上下文包装器和序列化适配器，负责在不同引擎间进行 API 转换和上下文映射（docs/en/architecture/overview.md:60-61）。

引擎层：负责作业执行和资源管理。支持三种执行引擎，每种引擎有独立的调度、容错和状态管理机制（docs/en/architecture/overview.md:84）。

核心模块详解

模块一：SeaTunnel API 层

职责边界：API 层定义了连接器开发的标准契约，但不包含任何具体实现。它负责统一数据类型系统、Schema 管理和检查点协调，确保不同连接器之间的互操作性。

入口与关键 API：

• SeaTunnelSource 接口：定义数据源读取的生命周期方法
• SeaTunnelSink 接口：定义数据写入的事务性语义
• SeaTunnelTransform 接口：定义数据转换的流水线操作
• CatalogTable 类：封装表元数据和 Schema 信息（docs/en/architecture/overview.md:42-44）

关键数据结构：

• TableSchema：包含字段名、数据类型、约束条件
• SeaTunnelRow：运行时数据行表示
• SchemaChangeEvent：Schema 变更事件（添加列、修改类型等）

关键调用链：

1. 配置层解析作业定义 → 创建 Source/Sink/Transform 实例
2. 转换层将 SeaTunnel API 包装为引擎特定 API
3. 引擎层调用包装后的 API 执行数据读写

错误处理与边界条件：

• Schema 不兼容时抛出 SchemaIncompatibleException
• 类型转换失败时提供默认值或跳过策略
• 检查点失败时触发作业回滚

模块二：连接器生态系统

职责边界：连接器层负责与外部数据源的实际交互，包括连接管理、数据读取/写入、CDC 事件捕获。连接器不负责作业调度或容错管理。

入口与关键 API：

• 各连接器实现 SeaTunnelSource 或 SeaTunnelSink 接口
• JDBC 连接器：通过 JDBC 驱动连接数据库
• Kafka 连接器：通过 Kafka Consumer/Producer API 读写消息
• MySQL-CDC 连接器：通过 binlog 捕获变更事件（docs/en/architecture/overview.md:51）

关键数据结构：

• 连接配置：主机、端口、认证信息
• 分片信息：并行读取时的分片策略
• 状态信息：CDC 场景下的位点信息

关键调用链：

1. 引擎调用 Source.createReader() 创建读取器
2. 读取器调用 pollNext() 获取数据
3. 数据经过 Transform 处理后传递给 Sink
4. Sink 调用 write() 写入目标

错误处理与边界条件：

• 连接失败时支持重试机制
• 数据类型不支持时提供转换或跳过选项
• CDC 位点持久化确保断点续传

模块三：转换层

职责边界：转换层负责将 SeaTunnel API 适配到不同执行引擎的原生 API，处理上下文转换、序列化适配和状态管理差异。它不执行实际的数据处理逻辑。

入口与关键 API：

• FlinkSource/FlinkSink：Flink 引擎适配器
• SparkSource/SparkSink：Spark 引擎适配器
• 上下文适配器：处理配置和运行时上下文转换
• 序列化适配器：处理不同引擎的序列化格式（docs/en/architecture/overview.md:60-61）

关键数据结构：

• 引擎上下文：包含引擎特定的配置和状态
• 类型映射表：SeaTunnel 类型到引擎类型的映射

关键调用链：

1. 引擎启动时加载对应的转换层适配器
2. 适配器将 SeaTunnel Source/Sink 包装为引擎原生 Source/Sink
3. 引擎调用包装后的组件执行作业

错误处理与边界条件：

• 不支持的引擎特性时抛出 UnsupportedOperationException
• 序列化失败时记录错误并跳过
• 状态迁移时处理版本兼容性

模块四：SeaTunnel Engine (Zeta)

职责边界：SeaTunnel Engine 是默认的执行引擎，负责作业调度、资源管理、容错处理和状态管理。它独立于大数据组件（如 Zookeeper、HDFS）运行，提供轻量化部署方案。

入口与关键 API：

• Master 节点：负责作业调度和集群管理
• Worker 节点：负责任务执行
• Checkpoint 机制：负责状态持久化和容错（docs/en/architecture/overview.md:70-72）

关键数据结构：

• 作业定义：包含 Source、Transform、Sink 的 DAG
• 任务状态：检查点快照、位点信息
• 集群状态：Master/Worker 心跳、资源使用情况

关键调用链：

1. 客户端提交作业到 Master
2. Master 解析作业并生成执行计划
3. Master 将任务分配给 Worker
4. Worker 执行任务并定期汇报状态
5. Checkpoint 协调器定期触发检查点

错误处理与边界条件：

• 任务失败时仅影响上下游任务（Pipeline 级别容错）
• 数据源有存储时间限制时启用数据缓存
• 动态线程共享减少线程创建开销（seatunnel-engine/README.md:8-9）

数据流与调用链

以下序列图展示了 SeaTunnel 端到端的数据流和关键组件交互：

正在加载图表渲染器...

数据流关键节点说明

作业提交阶段：

1. 客户端通过 HOCON 配置或 SQL 语法定义作业
2. 配置层解析作业定义并验证参数
3. API 层根据配置创建 Source、Sink、Transform 实例
4. 转换层将 SeaTunnel API 适配到目标引擎 API

数据同步阶段：

1. 引擎调用 Source 的 pollNext() 方法获取数据
2. 数据以 SeaTunnelRow 格式在引擎内部传递
3. Transform 对数据进行转换（过滤、映射、聚合等）
4. Sink 将数据写入目标系统
5. 循环执行直到 Source 返回 EOF

容错与检查点：

1. 引擎定期触发 Checkpoint（默认基于 Chandy-Lamport 算法）
2. Source 记录读取位点
3. Sink 执行两阶段提交确保 exactly-once 语义
4. 检查点持久化到分布式存储

架构约束与边界：

• Source 和 Sink 必须实现 SeaTunnel API，不能直接使用引擎原生 API
• Transform 只能处理 SeaTunnelRow 类型数据
• 检查点间隔需要在性能和容错之间权衡

多引擎支持与 SeaTunnel Engine

SeaTunnel 的核心优势之一是支持多种执行引擎，用户可以根据现有基础设施选择最合适的引擎。

引擎对比

SeaTunnel Engine 设计理念

SeaTunnel Engine 作为默认引擎，针对数据同步场景进行了深度优化（seatunnel-engine/README.md:1）：

更快：执行计划优化器减少网络传输，降低序列化/反序列化开销。支持限速功能，确保数据同步以合理速度进行（seatunnel-engine/README.md:7）。

更稳定：以 Pipeline 为最小粒度进行 Checkpoint 和容错。单个任务失败只影响上下游任务，避免整个作业失败或回滚。支持数据缓存功能，当目标写入失败时不影响源端数据读取（seatunnel-engine/README.md:8）。

更省空间：采用动态线程共享技术，在实时同步场景中，对于表数量多但单表数据量小的情况，在共享线程中运行同步任务，减少线程创建开销。在 CDC 场景中复用日志读取和解析资源（seatunnel-engine/README.md:9）。

简单易用：减少对第三方服务的依赖，独立实现集群管理、快照存储和集群 HA 功能，无需依赖 Zookeeper、HDFS 等大数据组件（seatunnel-engine/README.md:10）。

核心设计决策与取舍

决策一：引擎无关 API 设计

选择理由：通过统一的 SeaTunnel API 层抽象，连接器开发者只需实现一次即可在多种引擎上运行。这显著降低了维护成本，并允许用户根据现有基础设施灵活选择引擎。

技术实现：定义 SeaTunnelSource、SeaTunnelSink、SeaTunnelTransform 三大核心接口，转换层负责适配到引擎特定 API。

已知限制：某些引擎特有功能（如 Flink 的 Watermark 机制）无法通过统一 API 暴露。

决策二：Pipeline 级别容错

选择理由：传统全局 Checkpoint 在大规模作业中会导致严重的性能开销。SeaTunnel Engine 采用 Pipeline 级别容错，单个任务失败只影响上下游，避免全局回滚。

技术实现：每个 Pipeline 独立管理 Checkpoint，失败时只需重放该 Pipeline 的数据。

已知限制：跨 Pipeline 的事务一致性需要额外协调机制。

决策三：动态线程共享

选择理由：在多表同步场景中，为每个表创建独立线程会导致资源浪费。动态线程共享技术允许小表共享线程，减少系统开销。

技术实现：运行时动态分配任务到共享线程池，根据负载自动调整。

已知限制：大表仍需要独立线程以保证吞吐量。

决策四：独立于大数据组件

选择理由：传统数据同步工具依赖 Zookeeper、HDFS 等组件，部署复杂。SeaTunnel Engine 独立实现这些功能，降低部署门槛。

技术实现：内置集群管理、快照存储和 HA 机制，无需外部依赖。

已知限制：超大规模集群可能需要外部协调服务。

决策五：批流一体连接器

选择理由：传统方案需要为批处理和流处理分别开发连接器。SeaTunnel 的连接器同时支持批流模式，简化开发和维护。

技术实现：连接器根据执行模式（BATCH/STREAMING）自动调整行为。

已知限制：某些数据源（如文件系统）更适合批处理模式。

技术选型表格

模块依赖关系

以下图表展示了核心模块之间的依赖关系：

正在加载图表渲染器...

依赖关系说明

配置层 → API 层：配置层解析作业定义后，调用 API 层创建 Source、Sink、Transform 实例。

API 层 → 连接器层：连接器层实现 API 层定义的接口，提供具体的数据读写能力。

连接器层 → 转换层：转换层接收连接器实例，将其包装为引擎特定的 API。

转换层 → 引擎层：转换后的作业提交到对应的执行引擎（Zeta、Flink 或 Spark）。

连接器层 → 外部数据源：连接器通过 JDBC、Kafka 协议等与外部系统交互。

关键配置与启动流程

核心配置项

启动流程

1. 配置加载：从 HOCON 文件或 SQL 语句解析作业定义
2. 作业验证：验证配置完整性、连接器可用性
3. 实例创建：创建 Source、Sink、Transform 实例
4. 引擎适配：转换层将 SeaTunnel API 适配到目标引擎
5. 作业提交：将适配后的作业提交到执行引擎
6. 任务调度：引擎分配任务到 Worker 节点
7. 数据同步：执行数据读取、转换、写入循环
8. 容错处理：定期触发 Checkpoint，处理失败恢复
9. 作业完成：所有数据处理完毕，释放资源

错误处理策略

SeaTunnel 通过清晰的分层架构、引擎无关的 API 设计和针对数据同步场景的深度优化，为大规模数据集成提供了高效、稳定、易用的解决方案。其模块化设计允许灵活扩展，而内置的 SeaTunnel Engine 则提供了开箱即用的轻量化部署体验。