SeaTunnel 官方 FAQ 实战解读引擎选择、CDC、Save Mode 与配置变量替换全指南【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnelSeaTunnel 是一个多模态、高性能、分布式的海量数据集成工具。官方 FAQdocs/en/faq.md集中回答了社区中最常被问到的问题覆盖引擎选型、批流模式、CDC 增量同步、表结构与存量数据的处理策略Save Mode、配置变量替换、多行文本、任务调度与故障求助等主题。本文以该 FAQ 为骨架结合仓库源码与配套文档逐条展开帮助你在实际项目中快速做出正确的技术选型与配置决策并理解其背后的实现原理。获取帮助与参与社区的正确姿势如果你在使用 SeaTunnel 时遇到问题FAQ 给出了两条最稳定的求助路径问题追踪在 GitHub Issues 中检索或提交问题先搜索是否已有相似案例避免重复提问长文讨论订阅 dev 邮件列表适合深入的技术设计与方案讨论。对于想要参与贡献的开发者官方提供了清晰的 onboarding 路径稳定上手路线Contribution Path环境搭建与插件开发Developer Setup 与 Contribute Plugin。SeaTunnel 支持的数据源与数据目的地SeaTunnel 内置了大量 Source 与 Sink 连接器覆盖关系型数据库、消息队列、对象存储、OLAP/OLTP 数据库与各种 SaaS API支持的 Source 列表Source List支持的 Sink 列表Sink List。从仓库目录结构看连接器实现统一位于 seatunnel-connectors-v2 模块例如 JDBC、Kafka、Elasticsearch、Iceberg、Paimon 等均有独立的 connector 子模块且每个连接器都在 docs/en/connectors/source 与 docs/en/connectors/sink 下配有参数文档可按连接器名精确查阅。批处理与流处理如何选择SeaTunnel 同时支持批处理BATCH与流处理STREAMING两种模式通过env块中的job.mode配置项选择。选择建议批处理适合定时执行的数据集成任务如每日全量/增量同步流处理适合实时数据集成与变更数据捕获CDC场景。一个最小的批处理配置如下来自 config.md 的配置结构示例env { job.mode BATCH }流式任务则将job.mode改为STREAMING并结合checkpoint.interval、checkpoint.timeout等参数启用周期性检查点。常见的env级参数还包括job.name、parallelism、jars加载额外第三方 JAR与shade.identifier配置加解密策略完整列表见 JobEnvConfig 对应章节。必须安装 Spark 或 Flink 吗为什么推荐 Zeta不需要。Spark 与 Flink 并非 SeaTunnel 的强制依赖。SeaTunnel 支持三种集成引擎Zeta为集成场景专门设计的新一代高性能引擎社区强烈推荐功能最完整是 SeaTunnel 自带的引擎无需额外安装Spark适合已有 Spark 技术栈的团队Flink适合已有 Flink 技术栈的团队。Zeta 被社区用户亲切地称为奥特曼 ZetaUltraman Zeta其本地模式的启动脚本即为 bin/seatunnel.sh需在构建后由发行包提供配合-m local[2]即可单机运行见下文变量替换示例。Zeta 的集群运行方式master/worker可参考 config/hazelcast-master.yaml 与 config/hazelcast-worker.yaml 等集群配置文件。数据转换能力transform 模块SeaTunnel 支持丰富的转换函数包括字段映射、数据过滤、数据格式转换等统一通过配置文件中的transform模块声明。一个典型示例来自 config.mdsource { FakeSource { plugin_output fake row.num 100 schema { fields { name string age int card int } } } } transform { Filter { plugin_input fake plugin_output fake1 fields [name, card] } } sink { Clickhouse { host clickhouse:8123 database default table seatunnel_console fields [name, card] username default password plugin_input fake1 } }需要说明的是旧参数名source_table_name/result_table_name已被弃用请尽快迁移到新的plugin_output/plugin_input命名。plugin_output声明当前 source/transform 产出的数据集名称plugin_input声明下游 transform/sink 消费的数据集名称。全部转换插件清单见 Transforms。自定义数据清洗规则支持。你可以在transform模块中配置自定义清洗规则例如清洗脏数据删除无效记录字段转换与格式化。这些能力由各 transform 插件如 Filter、Replace、SQL 等提供具体参数与用法可查阅 Transforms 目录下对应插件的文档。实时增量集成与 CDCSeaTunnel 是否支持实时增量集成支持。SeaTunnel 通过 CDC 连接器实时捕获数据变更适合对实时性要求高的数据集成场景。整个 CDC 连接器体系位于 seatunnel-connectors-v2/connector-cdc按数据库拆分出 MySQL、PostgreSQL、Oracle、SQL Server、MongoDB、TiDB、DB2、Vitess、OpenGauss 等子模块。当前支持的 CDC 数据源FAQ 列出的 CDC 数据源包括MongoDB CDC、MySQL CDC、OpenGauss CDC、Oracle CDC、PostgreSQL CDC、SQL Server CDC、TiDB CDC等。从仓库目录看connector-cdc 下还包含 DB2 与 Vitess 的实现最新支持清单以 Source List 为准。CDC 权限如何开启各 CDC 连接器所需的数据库账号权限如 MySQL 的REPLICATION SLAVE、REPLICATION CLIENT等因连接器而异请按对应连接器的官方文档逐步配置可参考 connector-cdc-mysql 等模块源码与配套文档。是否支持从 MySQL 从库读取 CDC日志如何拉取支持。SeaTunnel 通过订阅 MySQL 的 binlog 日志实现 CDCbinlog 会由 SeaTunnel 服务端进行解析。因此你既可以从主库、也可以从开启了 binlog 的从库replica上捕获变更。没有主键的表能否做 CDC不支持。原因在于如果上游存在两条完全相同的记录当其中一条被删除或修改时下游无法判断到底应该删除/修改哪一条从而引发数据不一致。主键是保证数据唯一性的前提CDC 场景下表必须有主键。自动建表与存量数据处理Save Mode 体系在启动集成任务之前SeaTunnel 允许你通过两个参数精确控制目标端表结构与存量数据的处理策略它们统称为 Save Mode 体系schema_save_mode控制目标表结构schema的处理data_save_mode控制目标表已有数据的处理。schema_save_mode 可选值取值行为RECREATE_SCHEMA表不存在则创建表已存在则删除并重建CREATE_SCHEMA_WHEN_NOT_EXIST表不存在则创建表已存在则跳过创建ERROR_WHEN_SCHEMA_NOT_EXIST表不存在则抛出错误IGNORE忽略表结构的处理上述四个取值与语义在 SchemaSaveMode.java 中均有对应枚举定义RECREATE_SCHEMA、CREATE_SCHEMA_WHEN_NOT_EXIST、ERROR_WHEN_SCHEMA_NOT_EXIST、IGNORE是所有支持自动建表的 Sink 连接器共用的 API 层契约。data_save_mode 可选值取值行为DROP_DATA保留表结构删除已有数据APPEND_DATA保留表结构保留已有数据追加写入CUSTOM_PROCESSING用户自定义处理配合custom_sql使用ERROR_WHEN_DATA_EXISTS若已有数据则抛出错误对应枚举定义见 DataSaveMode.java。以 JDBC Sink 为例JdbcSinkOptions.java 中明确给出了两者的默认值schema_save_mode默认CREATE_SCHEMA_WHEN_NOT_EXISTdata_save_mode默认APPEND_DATA。这意味着不显式配置时SeaTunnel 会自动按表不存在则建表、数据追加写入的保守策略运行。注意JDBC Sink 配置了 query 时的行为边界FAQ 特别提醒当 JDBC Sink 配置了query自定义写入 SQL时save mode 处理不会生效因此CUSTOM_PROCESSING/custom_sql也不会被执行。这是使用自定义 SQL 写入时必须注意的边界。跨 Sink 的行为差异不同连接器对 Save Mode 的支持范围存在差异尤其是文件/对象存储类 Sink跨 Sink 的完整行为对比与generate_sink_sql的关系请参见 Sink Write Modes and Save Modes。JDBC Sinkgenerate_sink_sql还是queryFAQ 给出了非常明确的选型建议generate_sink_sql true配合database、table通常还需要primary_keys让 SeaTunnel 自动生成 INSERT、UPSERT、UPDATE、DELETE 语句并应用 save mode 处理query仅在必须完全掌控每一行的 SQL 语句时使用二者不可同时配置。从 JdbcSinkOptions.java 源码看generate_sink_sql默认值为false而enable_upsert默认值为true即当配置了primary_keys时默认启用 upsert 语义primary_keys本身无默认值需要按表结构显式声明。完整决策表见 Sink Write Modes and Save Modes。精确一次Exactly-Once一致性SeaTunnel 对部分数据源支持精确一次一致性例如 MySQL、PostgreSQL从而保证集成过程中的数据一致性。需要强调的是精确一次能力取决于底层数据库的支撑能力并非所有数据源都能提供请以对应连接器文档为准。JDBC Sink 中与事务相关的参数如is_exactly_once、auto_commit、max_retries、xa_data_source_class_name、max_commit_attempts、transaction_timeout_sec也定义在 JdbcSinkOptions.java 中可作为实现依据。定时调度任务SeaTunnel 本身不内置调度器你可以使用Linux cron 任务实现周期性数据集成使用Apache DolphinScheduler或Apache Airflow等调度工具管理复杂定时任务配合下文介绍的配置变量替换能力可实现同一份配置、动态参数、多次调度的离线批处理模式。配置变量替换Variable SubstitutionFAQ 详细讲解了在配置中声明变量并在运行时动态替换的能力这在定时任务和临时离线处理中非常常用可用于替换时间、日期等变量。SeaTunnel 配置文件支持hocon、json、SQL三种格式其中HOCON 是快速上手与生产示例中最常用的格式且变量替换仅支持 HOCON 格式文件见 config.md。在配置中定义变量配置文件中的任意key value对其值都可以用变量占位。例如在 SQL 转换中... transform { Sql { query select * from dual where city ${city} and dt ${date} } } ...通过命令行传入变量以 Zeta 本地模式启动 SeaTunnel 并传入变量$SEATUNNEL_HOME/bin/seatunnel.sh \ -c $SEATUNNEL_HOME/config/your_app.conf \ -m local[2] \ -i citySingapore \ -i date20231110-c指定配置文件路径-m local[2]以 Zeta 本地模式运行并行度为 2-i/--variable以keyvalue形式指定变量值key与配置中的变量名对应。三种占位写法变量占位支持三种形式见 config.md写法行为${varName}变量未提供时抛出异常${varName:default}变量未提供时使用默认值默认值需用双引号包裹${varName:}变量未提供时使用空字符串此外也可以通过系统环境变量传入变量值例如在 shell 中export varNamevalue with space变量替换的注意事项FAQ 与 config.md 共同给出以下关键注意事项若值包含(等特殊字符请用单引号包裹例如-i password$a^b%c.d~e0*9(若替换变量本身包含双引号或单引号需要把引号一并作为值传入变量值不能包含空格-i jobNamethis is a job name会被截断为job.name this带空格的值请改用环境变量传递动态参数可用命令替换例如-i date$(date %Y%m%d)以下系统保留占位符不能用-i替换${database_name}、${schema_name}、${table_name}、${schema_full_name}、${table_full_name}、${primary_key}、${unique_key}、${field_names}、${partition_keys}详见 Sink Parameter Placeholders 对应文档。多行文本与多行文本中的变量替换如何书写多行文本当文本较长需要换行时可以使用三引号标记文本的开始与结束var Apache SeaTunnel is a next-generation high-performance, distributed, massive data integration tool. 该语法与 config.md 中的多行支持说明一致三引号内的换行符与特殊格式会被原样保留。多行文本中的变量替换技巧由于变量不能直接包裹在三引号内部多行文本中做变量替换需要把变量拼接在三引号片段之间var your string 1 ${your_var} your string 2这一技巧源自 HOCON 底层解析库 lightbend/config 的已知行为对应 lightbend/config#456在 SeaTunnel 中同样适用。学习 SeaTunnel 源码从哪里入手SeaTunnel 拥有高度抽象、结构清晰的架构是学习大数据架构的优秀范例。FAQ 建议从seatunnel-examples模块的SeaTunnelEngineLocalExample.java入手通过本地断点调试逐步理解作业提交与执行链路。当前仓库中核心 API 抽象集中在 seatunnel-api引擎实现位于 seatunnel-engine配置解析与连接器插件机制可参考 seatunnel-config 与 seatunnel-plugin-discovery。开发自己的 Source / Sink / Transform 需要通读全部源码吗不需要。开发自定义连接器Connector V2时你只需关注 SeaTunnel API 提供的 Source、Sink、Transform 接口。完整的开发指南见 Connector Development Guide即仓库根目录下的 seatunnel-connectors-v2/README.md该 README 由 FAQ 直接链接是 Connector V2 开发的权威起点。此外docs/en/developer 下的 contribute-plugin.md、how-to-create-your-connector.md、source-connector-development.md、sink-connector-development.md 等文档可提供更细化的分步指导。小结SeaTunnel 官方 FAQ 覆盖了从如何求助到如何开发插件的完整生命周期。将 FAQ 与仓库源码结合后可以确认引擎选择上 Zeta 是开箱即用且最受社区推荐CDC 场景必须保证表有主键表结构与存量数据处理统一由schema_save_mode/data_save_mode两个参数控制其枚举契约定义在 SchemaSaveMode.java 与 DataSaveMode.java变量替换能力-i keyvalue与多行文本语法则极大提升了同一份配置在定时批处理中的复用性。建议将本文与 config.md、Sink Write Modes and Save Modes 及具体连接器文档配合阅读以获得完整的信息闭环。【免费下载链接】seatunnelSeaTunnel is a multimodal, high-performance, distributed, massive data integration tool.项目地址: https://gitcode.com/GitHub_Trending/se/seatunnel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考