简介这是一份面向数据工程师与开发人员的 Apache SeaTunnel 数据集成配置案例源码包聚焦 MySQL 到 HDFS 以及 Hive 到 MySQL 两条常见迁移链路可直接参考或运行验证。资源共包含 3 个文件以 .inscode 项目配置、HTML 说明文档和 .gitignore 文件为主压缩包整体仅 8KB体积轻量、结构清晰。目前已有 25 人学习适合正在评估或上手 SeaTunnel 的初级、中级使用者。通过该案例读者可以快速理解配置文件写法、源端与目标端参数设置方法以及前置环境准备、HDFS/Hive 服务启动等环节的注意事项尤其有助于在本地快速复现并完成数据迁移实验。1. 整体设计与配置思路拆解先说结论SeaTunnel 搞配置核心难点从来不是“怎么写”而是“怎么知道为什么这么写”。我在这套可运行源码里把配置拆成了四层来看——环境层、连接器层、转换层、同步策略层每一层都有独立的配置文件和运行参数互不干扰但又顺序依赖。为什么要这么拆很简单真实生产环境里数据源不可能只有一个目标端也经常在 MySQL、达梦、Kafka 之间换来换去。如果把所有连接信息揉在一个配置文件里改一次同步任务就要动全局出错概率极大。而这套源码的设计就是让你在config目录下按业务线建独立子目录每个同步场景一个文件像搭积木一样拼装。以最常见的“业务库到数仓”场景为例同步链路是 MySQL → SeaTunnel → 达梦或 Hive中间还要做字段映射和类型转换。这套源码里对应的核心配置是mysql_to_dameng.conf它做了三件事用env段声明并行度、checkpoint 间隔和状态后端相当于给整个任务定调子用source段配置 MySQL 连接和增量读取模式用sink段配置达梦连接和写入策略。每段之间的变量通过${}占位符解耦这样同一个模板直接套到测试环境、预发环境、生产环境只需要改外部参数文件即可。这个思路借鉴了 Twelve-Factor 的配置外置理念在 SeaTunnel 里虽然不是强制但实测对多人协作和 CI/CD 集成非常友好。另一个关键设计是“先看计划再执行”。这套源码里所有任务都有一个--plan模式参数可以先打印出物理执行计划确认读取字段、转换逻辑、写入方式都符合预期后再真正跑任务。这一步对于排查“为什么数据对不上”之类的问题能节省大量时间。2. 环境准备与部署实操2.1 本地 Windows 部署流程先解决“怎么把 SeaTunnel 跑起来”这个最基础也最容易卡住的问题。很多人在 Linux 上部署很顺利一到 Windows 本地就蒙了其实 SeaTunnel 对 Windows 的支持已经相当成熟关键点只在设置两个环境变量。部署步骤我按这套源码的 README 顺序走一遍下载 SeaTunnel 发行版压缩包解压到D:\seatunnel路径不要带中文和空格配置环境变量SEATUNNEL_HOMED:\seatunnel并把%SEATUNNEL_HOME%\bin加入PATH在%SEATUNNEL_HOME%\config\seatunnel-env.shWindows 下实际读的是seatunnel-env.cmd里确认JAVA_HOME指向 JDK 1.8 或 11执行seatunnel.bat --version验证安装。这里有个特别容易踩的坑Windows 下如果之前装过其他 Java 生态工具PATH里可能有多个 Java 版本SeaTunnel 启动脚本用的java命令不一定是你预期的那一个。我在源码里专门加了一个check-env.bat脚本启动前先打印当前生效的 Java 版本和SEATUNNEL_HOME路径发现问题可以及时调整。启动脚本跑通之后还需要验证插件目录。plugins目录下能看到connector-mysql、connector-dameng、connector-console等子目录每个子目录里都有对应的 jar 包和plugin-mapping.properties。这个目录结构不是摆设SeaTunnel 启动时会扫描这里的映射关系决定哪些 connector 可以被配置文件引用。2.2 构建可运行源码的依赖准备这套源码我用的是 SeaTunnel 2.3.x 版本线构建工具是 Maven。本地运行前需要把几个核心模块 install 到本地仓库命令如下git clone https://github.com/apache/seatunnel.git cd seatunnel mvn -T 2C -pl seatunnel-core/seatunnel-flink-starter,seatunnel-connectors-v2/connector-mysql,seatunnel-connectors-v2/connector-dameng -am install -DskipTests -Dcheckstyle.skiptrue为什么要单独指定这几个模块而不是mvn install全部构建因为 SeaTunnel 的 connector 非常庞杂全量构建不仅耗时而且某些 connector 依赖的第三方库在本地环境可能版本冲突。只构建需要的那几个能节省大量时间也避免无关模块干扰调试。构建完成之后把对应 connector 目录下target/*.jar复制到发行版的plugins目录里。如果你用的是我源码里附带的一键脚本build-and-deploy.bat它会自动完成从编译到拷贝的整个过程最终生成一个可以直接运行的runtime目录。源码里还带了一个docker-compose.yml里面预置了 MySQL 8.0 和达梦 8 的开发容器方便在没有现成环境的情况下做全链路测试。我自己在本地实测时就是靠它把上下游环境拉起来的整个启动过程大约需要 30 秒。3. 核心配置案例与可运行代码解析3.1 第一个案例MySQL 全量同步到达梦这个案例是最常用的入门场景也是整套源码里最容易改造成其他同步链路的基础模板。先看完整的配置文件mysql_to_dameng.confenv { parallelism 2 job.mode BATCH checkpoint.interval 10000 } source { MySQL { url jdbc:mysql://localhost:3306/business_db?useSSLfalseserverTimezoneAsia/Shanghai username root password 123456 query SELECT id, order_no, user_id, total_amount, created_at FROM orders WHERE created_at 2024-01-01 result_table_name orders_src } } transform { FieldMapper { source_table_name orders_src result_table_name orders_mapped field_mapper { id order_id order_no order_no total_amount total_amount created_at created_at } } } sink { Dameng { source_table_name orders_mapped url jdbc:dm://localhost:5236/DAMENG username SYSDBA password SYSDBA database DAMENG table ods_orders schema MAIN save_mode APPEND pre_sql TRUNCATE TABLE MAIN.ods_orders } }逐段解释一下背后的逻辑。env段里parallelism 2表示读取和写入的并发度为 2也就是两个并行子任务。对于这个量级的全量同步2 个并发足够再高反而可能因为源库连接数限制导致读取变慢。job.mode BATCH表示这是批任务如果是实时同步需要改成STREAMING。checkpoint.interval 10000是 checkpoint 间隔 10 秒决定了任务失败后最多回放多少数据。source段的query是真正执行的读取 SQL。这里建议把字段名和过滤条件写得尽可能明确不要写SELECT *否则后续字段映射会变得不可控。result_table_name是 Souce 读出来的虚拟表名下游要用这个名字引用它。transform段只做了一个字段映射把源表字段名改成目标表字段名。虽然这个案例里只有一个转换但它是整套数据同步链路中承上启下的关键一环。需要注意的是field_mapper里的 key 是源字段value 是目标字段顺序不要搞反。sink段里最有讲究的是save_mode和pre_sql。APPEND模式不会清空目标表直接追加写入pre_sql则会在写入前先执行一次清理。这两个配合使用可以实现“每次全量重刷”的效果。如果目标表已经有主键更推荐用UPSERT模式下面会讲。3.2 第二个案例增量同步与 UPSERT 模式全量同步解决的是“从零开始”的问题但实际业务中更常见的是“每天新增/变更的数据怎么平稳地进数仓”。这时候就需要增量同步SeaTunnel 里最直观的增量方式是在查询 SQL 里用时间条件做稳点。source { MySQL { url jdbc:mysql://localhost:3306/business_db?useSSLfalseserverTimezoneAsia/Shanghai username root password 123456 query SELECT id, order_no, user_id, total_amount, updated_at FROM orders WHERE updated_at ${last_time} result_table_name orders_incr } } sink { Dameng { source_table_name orders_incr url jdbc:dm://localhost:5236/DAMENG username SYSDBA password SYSDBA database DAMENG table ods_orders save_mode UPSERT key_fields [order_id] } }这个配置的核心在于${last_time}参数和UPSERT模式。${last_time}是从外部传入的参数运行时通过--variable last_time2024-06-01 00:00:00指定。这个值通常由调度系统比如 DolphinScheduler 或 Airflow在每次任务启动前自动算好实现“每天只同步前一天变更的数据”。这套源码里附带了一个last_time.sh脚本可以按天自动计算时间并触发同步任务。save_mode UPSERT的模式下达梦会根据key_fields指定的字段判断记录是否存在存在就更新不存在就插入。注意key_fields必须对应目标表的主键或唯一索引否则达梦不知道以什么为判断依据同步结果会出现大量重复数据。增量同步比全量同步多了一个隐患如果业务库的updated_at索引没有建好每次增量查询都会触发全表扫描同步任务会越来越慢。我的经验是在源库的updated_at字段上建索引是最低成本也是收益最明显的优化手段没有之一。3.3 第三个案例达梦 CDC 实时同步达梦 CDCChange Data Capture是这套源码里最有价值的部分也是网上资料相对稀疏的方向。用 SeaTunnel 做达梦 CDC 同步本质上是通过达梦的 LogMiner 工具读取归档日志把 INSERT、UPDATE、DELETE 操作解析成流式事件再写入目标端。直接看配置env { parallelism 1 job.mode STREAMING checkpoint.interval 5000 } source { DamengCDC { hostname localhost port 5236 username SYSDBA password SYSDBA database DAMENG table_list [BUSINESS.ORDERS] mode logminer start_mode latest } } sink { Kafka { source_table_name dameng_cdc_data bootstrap.server localhost:9092 topic dameng_cdc_orders semantic EXACTLY_ONCE format json } }这段配置里有三个关键决策点。第一个是mode logminer。达梦 CDC 有多种实现方式LogMiner 是相对通用、对业务库侵入最小的一种——它不需要在每个表上建触发器而是直接解析日志。代价是要求数据库开启归档模式否则没有足够的历史日志可读。开启归档需要数据库管理员权限具体 SQL 是ALTER DATABASE ADD ARCHIVELOG DEST /dm8/arch。第二个是start_mode latest。它表示从当前日志位置开始读取只捕获启动之后的变更。如果需要从历史的某个时间点开始消费可以改成start_mode timestamp并配合start_timestamp参数。这个选择决定了首次启动时是否能捞到之前的变更数据要根据业务需求来定。第三个是 Kafka sink 的semantic EXACTLY_ONCE。它结合 checkpoint 机制保证每条从达梦读出的变更恰好被写入 Kafka 一次。注意 EXACTLY_ONCE 对 Kafka 版本有要求必须 0.11 以上。如果使用的 Kafka 版本较旧需要降级为AT_LEAST_ONCE这样在极端情况下可能产生少量重复数据需要下游做去重。达梦 CDC 同步链路天然是流式的所以parallelism 1。在 LogMiner 模式下并行读取日志会出现顺序错乱导致下游无法正确还原数据变更顺序。如果单表数据量极大更适合的做法是拆成多个任务按表维度分开同步而不是提高并行度。4. SeaTunnel Web 本地调试与运行验证4.1 部署 SeaTunnel Web 并配置数据源命令行方式对于开发调试没问题但到了团队协作阶段配置管理、任务调度的需求就出来了。这时候用 SeaTunnel Web 能直观地管理任务。这套源码里的seatunnel-web目录就是为本地调试准备的。部署步骤修改seatunnel-web/conf/application.yml把数据库连接指向本地 MySQLWeb 端用 MySQL 存元数据初始化数据库脚本seatunnel-web/sql/seatunnel_server.sql启动 Web 服务默认端口 8080浏览器访问http://localhost:8080用管理员账号登录。进入 Web 控制台后先到“数据源”页面配置 MySQL 和达梦连接。这一步的作用是把连接信息集中管理之后创建同步任务时只需要选择数据源不需要在任务配置里反复写 IP、端口、账号密码。实测下来多人协作时这个机制能明显减少配置错误也方便 DBA 统一管控账号权限。4.2 在 Web 端创建实时同步任务与日志排查Web 端创建任务的逻辑其实和写配置文件大同小异只不是把 JSON 配置拆成了表单。我建议的方式是先切换到“编辑 JSON”模式直接粘贴前面那段达梦 CDC 到 Kafka 的配置保存后任务就创建好了。这个流程里你必须主动拦截两个问题第一个是数据源连通性。很多人在 Web 端填了达梦连接信息但没测试连通性就直接建任务结果任务一跑就报连接超时。Web 端的数据源管理页有“测试连接”按钮务必先测通再往下走。第二个是任务提交之后的状态感知。Web 端提交任务后实际是提交给了 SeaTunnel 集群的作业服务。如果集群没有起来或者 Web 端配置的地址不对任务会一直停在 “SUBMITTED” 状态。排查时先看 Web 端日志再到集群节点上看logs/seatunnel-engine.log两边对比就能定位。调试过程中最有用的功能是“实时日志”面板。每次任务运行时在这个面板能直接看到 checkpoint 完成情况、读取记录数、写入失败的具体异常堆栈。比起命令行方式Web 端的日志面板不用手工翻文件确实方便不少。但要注意Web 端的日志展示有一定延迟几秒到十几秒对于实时性要求高的调试场景还是以服务端日志为准。4.3 命令行检查任务状态的补充方法如果你习惯用命令行操作比如在服务器上排查问题也可以直接用 SeaTunnel 自带的脚本查看任务状态。在bin目录下执行seatunnel-engine.sh -getRunningJob seatunnel-engine.sh -getJobInfo {jobId}第一条命令列出所有正在运行的任务及 ID第二条命令输出指定任务的详细统计信息包括读了多少条、写了多少条、checkpoint 次数、异常信息等。这套源码里我封装了一个job-monitor.sh可以每 5 秒轮询一次并在任务失败时自动抓取最新日志比较适合长时间跑批的同步任务。5. 常见问题与排查技巧实录5.1 连接器加载失败现象提交任务时提示Connector [mysql] not found或No suitable connector。原因绝大多数情况是插件发版版本和配置文件里的 connector 名称对不上。SeaTunnel 的 connector 命名包括连接器类型和版本后缀比如connector-mysql对应配置文件里写MySQL但如果是老版本的connector-cdc-mysql配置文件里就得写MySQL-CDC。名称不匹配时引擎找不到对应实现类。排查方法先看plugins目录下到底有哪些 connector 子目录再对照配置文件里的连接器名逐一比大小写。SeaTunnel 的 connector 名称是大小写敏感的mysql和MySQL是两个概念。另外确认plugin-mapping.properties文件没有被误删引擎依赖这个文件建立名字到实现类的映射。5.2 达梦驱动类冲突现象同步任务启动时抛java.lang.AbstractMethodError或ClassNotFoundException: dm.jdbc.driver.DmDriver。原因这类问题多是驱动 jar 包冲突。SeaTunnel 的 Dameng connector 自带达梦 JDBC 驱动但如果你在lib目录里又放了一份不同版本的驱动就会造成类加载冲突。JVM 加载到到旧版本的驱动时某些新接口方法没有被实现于是抛 AbstractMethodError。解决方法把lib目录下的多余驱动 jar 移走只保留 connector 自带的版本。如果必须用特定版本的驱动把lib目录下的dm-jdbc.jar也替换成相同版本保证全链路加载的是同一个类。5.3 MySQL 同步到达梦时汉字乱码现象数据同步完成后达梦表里的中文数据变成问号或乱码。原因字符集不一致。MySQL 源表是 UTF-8达梦库的字符集如果是 GB18030那么写入时如果两边没有做字符集转换就会出现乱码。排查步骤先确认达梦库的字符集SELECT * FROM V$NLS_PARAMETERS WHERE PARAMETER NLS_CHARACTERSET。如果是 GB18030在 SeaTunnel 连接达梦的 URL 里加上?characterEncodingutf-8并在连接器配置里显式指定charset UTF-8。一套源码里已经预置了charset配置项默认改成 UTF-8 即可。5.4 全量任务同步过程中数据中断现象数据量大的表同步到一半任务失败错误信息显示连接超时或被断开。原因大部分情况是源库设置了wait_timeout长时间运行的查询被数据库掐断了连接。另外如果源库 binlog 格式不是 ROW做 CDC 时也可能因为解析不了而中断。解决思路在 JDBC URL 上增加connectTimeout60000socketTimeout600000参数适当放大超时时间在env段调大checkpoint.interval让 checkpoint 机制更宽松如果是全量同步把源表按主键范围拆成多个分片每个分片单独一个任务避免单个任务运行时间过长。5.5 参数优先级配置文件 vs 命令行这套源码里所有配置都可以灵活组合但你最好明确一个规则命令行传入的参数优先于配置文件。比如配置里写死parallelism 2但提交时命令行加--parallelism 4实际生效的是 4。排查问题时先确认任务实际拿到的参数是什么可以通过--plan模式打印执行计划来确认。6. 从案例到生产的一些体会这套配置案例跑通之后后续扩展方向很清晰。最简单的做法是把 MySQL 源替换成 Oracle 或 PostgreSQL只需改source段里的连接器和 query 语法后面 transform 和 sink 可以原封不动。同理目标端从达梦换成 ClickHouse只需改sink段的连接器类型和写入模式前面的读取和转换几乎不受影响。如果要做实时数仓可以再加上Sink端的 Iceberg 或 Hudi connector把 CDC 数据直接落到数据湖做流批一体。这个扩展方向在社区里已经有不少实践案例但要注意 Iceberg 的 catalog 配置和 hive metastore 的依赖会稍微复杂一些。最后分享一个排错习惯。你在改任何同步任务配置之前先用 git 把当前能跑通的配置提交一个版本。出了问题直接git diff看改了哪些参数绝大多数问题都出在自己改的那几行里。我自己维护数据同步任务的几年里这个习惯帮我省下的时间非常可观。这套源码和配置案例我用下来最直观的收获就是SeaTunnel 本身并不难难的是把不同数据源、不同目标端、不同同步模式排列组合之后还能保持清晰和可控。有了这套可复用的配置模板和排查思路至少我在面对新的同步需求时不是从零开始摸索而是基于已验证的路径做增量调整。本文还有配套的精品资源点击获取 SeaTunnel数据同步配置实战：MySQL到达梦全量与增量同步详解
简介这是一份面向数据工程师与开发人员的 Apache SeaTunnel 数据集成配置案例源码包聚焦 MySQL 到 HDFS 以及 Hive 到 MySQL 两条常见迁移链路可直接参考或运行验证。资源共包含 3 个文件以 .inscode 项目配置、HTML 说明文档和 .gitignore 文件为主压缩包整体仅 8KB体积轻量、结构清晰。目前已有 25 人学习适合正在评估或上手 SeaTunnel 的初级、中级使用者。通过该案例读者可以快速理解配置文件写法、源端与目标端参数设置方法以及前置环境准备、HDFS/Hive 服务启动等环节的注意事项尤其有助于在本地快速复现并完成数据迁移实验。1. 整体设计与配置思路拆解先说结论SeaTunnel 搞配置核心难点从来不是“怎么写”而是“怎么知道为什么这么写”。我在这套可运行源码里把配置拆成了四层来看——环境层、连接器层、转换层、同步策略层每一层都有独立的配置文件和运行参数互不干扰但又顺序依赖。为什么要这么拆很简单真实生产环境里数据源不可能只有一个目标端也经常在 MySQL、达梦、Kafka 之间换来换去。如果把所有连接信息揉在一个配置文件里改一次同步任务就要动全局出错概率极大。而这套源码的设计就是让你在config目录下按业务线建独立子目录每个同步场景一个文件像搭积木一样拼装。以最常见的“业务库到数仓”场景为例同步链路是 MySQL → SeaTunnel → 达梦或 Hive中间还要做字段映射和类型转换。这套源码里对应的核心配置是mysql_to_dameng.conf它做了三件事用env段声明并行度、checkpoint 间隔和状态后端相当于给整个任务定调子用source段配置 MySQL 连接和增量读取模式用sink段配置达梦连接和写入策略。每段之间的变量通过${}占位符解耦这样同一个模板直接套到测试环境、预发环境、生产环境只需要改外部参数文件即可。这个思路借鉴了 Twelve-Factor 的配置外置理念在 SeaTunnel 里虽然不是强制但实测对多人协作和 CI/CD 集成非常友好。另一个关键设计是“先看计划再执行”。这套源码里所有任务都有一个--plan模式参数可以先打印出物理执行计划确认读取字段、转换逻辑、写入方式都符合预期后再真正跑任务。这一步对于排查“为什么数据对不上”之类的问题能节省大量时间。2. 环境准备与部署实操2.1 本地 Windows 部署流程先解决“怎么把 SeaTunnel 跑起来”这个最基础也最容易卡住的问题。很多人在 Linux 上部署很顺利一到 Windows 本地就蒙了其实 SeaTunnel 对 Windows 的支持已经相当成熟关键点只在设置两个环境变量。部署步骤我按这套源码的 README 顺序走一遍下载 SeaTunnel 发行版压缩包解压到D:\seatunnel路径不要带中文和空格配置环境变量SEATUNNEL_HOMED:\seatunnel并把%SEATUNNEL_HOME%\bin加入PATH在%SEATUNNEL_HOME%\config\seatunnel-env.shWindows 下实际读的是seatunnel-env.cmd里确认JAVA_HOME指向 JDK 1.8 或 11执行seatunnel.bat --version验证安装。这里有个特别容易踩的坑Windows 下如果之前装过其他 Java 生态工具PATH里可能有多个 Java 版本SeaTunnel 启动脚本用的java命令不一定是你预期的那一个。我在源码里专门加了一个check-env.bat脚本启动前先打印当前生效的 Java 版本和SEATUNNEL_HOME路径发现问题可以及时调整。启动脚本跑通之后还需要验证插件目录。plugins目录下能看到connector-mysql、connector-dameng、connector-console等子目录每个子目录里都有对应的 jar 包和plugin-mapping.properties。这个目录结构不是摆设SeaTunnel 启动时会扫描这里的映射关系决定哪些 connector 可以被配置文件引用。2.2 构建可运行源码的依赖准备这套源码我用的是 SeaTunnel 2.3.x 版本线构建工具是 Maven。本地运行前需要把几个核心模块 install 到本地仓库命令如下git clone https://github.com/apache/seatunnel.git cd seatunnel mvn -T 2C -pl seatunnel-core/seatunnel-flink-starter,seatunnel-connectors-v2/connector-mysql,seatunnel-connectors-v2/connector-dameng -am install -DskipTests -Dcheckstyle.skiptrue为什么要单独指定这几个模块而不是mvn install全部构建因为 SeaTunnel 的 connector 非常庞杂全量构建不仅耗时而且某些 connector 依赖的第三方库在本地环境可能版本冲突。只构建需要的那几个能节省大量时间也避免无关模块干扰调试。构建完成之后把对应 connector 目录下target/*.jar复制到发行版的plugins目录里。如果你用的是我源码里附带的一键脚本build-and-deploy.bat它会自动完成从编译到拷贝的整个过程最终生成一个可以直接运行的runtime目录。源码里还带了一个docker-compose.yml里面预置了 MySQL 8.0 和达梦 8 的开发容器方便在没有现成环境的情况下做全链路测试。我自己在本地实测时就是靠它把上下游环境拉起来的整个启动过程大约需要 30 秒。3. 核心配置案例与可运行代码解析3.1 第一个案例MySQL 全量同步到达梦这个案例是最常用的入门场景也是整套源码里最容易改造成其他同步链路的基础模板。先看完整的配置文件mysql_to_dameng.confenv { parallelism 2 job.mode BATCH checkpoint.interval 10000 } source { MySQL { url jdbc:mysql://localhost:3306/business_db?useSSLfalseserverTimezoneAsia/Shanghai username root password 123456 query SELECT id, order_no, user_id, total_amount, created_at FROM orders WHERE created_at 2024-01-01 result_table_name orders_src } } transform { FieldMapper { source_table_name orders_src result_table_name orders_mapped field_mapper { id order_id order_no order_no total_amount total_amount created_at created_at } } } sink { Dameng { source_table_name orders_mapped url jdbc:dm://localhost:5236/DAMENG username SYSDBA password SYSDBA database DAMENG table ods_orders schema MAIN save_mode APPEND pre_sql TRUNCATE TABLE MAIN.ods_orders } }逐段解释一下背后的逻辑。env段里parallelism 2表示读取和写入的并发度为 2也就是两个并行子任务。对于这个量级的全量同步2 个并发足够再高反而可能因为源库连接数限制导致读取变慢。job.mode BATCH表示这是批任务如果是实时同步需要改成STREAMING。checkpoint.interval 10000是 checkpoint 间隔 10 秒决定了任务失败后最多回放多少数据。source段的query是真正执行的读取 SQL。这里建议把字段名和过滤条件写得尽可能明确不要写SELECT *否则后续字段映射会变得不可控。result_table_name是 Souce 读出来的虚拟表名下游要用这个名字引用它。transform段只做了一个字段映射把源表字段名改成目标表字段名。虽然这个案例里只有一个转换但它是整套数据同步链路中承上启下的关键一环。需要注意的是field_mapper里的 key 是源字段value 是目标字段顺序不要搞反。sink段里最有讲究的是save_mode和pre_sql。APPEND模式不会清空目标表直接追加写入pre_sql则会在写入前先执行一次清理。这两个配合使用可以实现“每次全量重刷”的效果。如果目标表已经有主键更推荐用UPSERT模式下面会讲。3.2 第二个案例增量同步与 UPSERT 模式全量同步解决的是“从零开始”的问题但实际业务中更常见的是“每天新增/变更的数据怎么平稳地进数仓”。这时候就需要增量同步SeaTunnel 里最直观的增量方式是在查询 SQL 里用时间条件做稳点。source { MySQL { url jdbc:mysql://localhost:3306/business_db?useSSLfalseserverTimezoneAsia/Shanghai username root password 123456 query SELECT id, order_no, user_id, total_amount, updated_at FROM orders WHERE updated_at ${last_time} result_table_name orders_incr } } sink { Dameng { source_table_name orders_incr url jdbc:dm://localhost:5236/DAMENG username SYSDBA password SYSDBA database DAMENG table ods_orders save_mode UPSERT key_fields [order_id] } }这个配置的核心在于${last_time}参数和UPSERT模式。${last_time}是从外部传入的参数运行时通过--variable last_time2024-06-01 00:00:00指定。这个值通常由调度系统比如 DolphinScheduler 或 Airflow在每次任务启动前自动算好实现“每天只同步前一天变更的数据”。这套源码里附带了一个last_time.sh脚本可以按天自动计算时间并触发同步任务。save_mode UPSERT的模式下达梦会根据key_fields指定的字段判断记录是否存在存在就更新不存在就插入。注意key_fields必须对应目标表的主键或唯一索引否则达梦不知道以什么为判断依据同步结果会出现大量重复数据。增量同步比全量同步多了一个隐患如果业务库的updated_at索引没有建好每次增量查询都会触发全表扫描同步任务会越来越慢。我的经验是在源库的updated_at字段上建索引是最低成本也是收益最明显的优化手段没有之一。3.3 第三个案例达梦 CDC 实时同步达梦 CDCChange Data Capture是这套源码里最有价值的部分也是网上资料相对稀疏的方向。用 SeaTunnel 做达梦 CDC 同步本质上是通过达梦的 LogMiner 工具读取归档日志把 INSERT、UPDATE、DELETE 操作解析成流式事件再写入目标端。直接看配置env { parallelism 1 job.mode STREAMING checkpoint.interval 5000 } source { DamengCDC { hostname localhost port 5236 username SYSDBA password SYSDBA database DAMENG table_list [BUSINESS.ORDERS] mode logminer start_mode latest } } sink { Kafka { source_table_name dameng_cdc_data bootstrap.server localhost:9092 topic dameng_cdc_orders semantic EXACTLY_ONCE format json } }这段配置里有三个关键决策点。第一个是mode logminer。达梦 CDC 有多种实现方式LogMiner 是相对通用、对业务库侵入最小的一种——它不需要在每个表上建触发器而是直接解析日志。代价是要求数据库开启归档模式否则没有足够的历史日志可读。开启归档需要数据库管理员权限具体 SQL 是ALTER DATABASE ADD ARCHIVELOG DEST /dm8/arch。第二个是start_mode latest。它表示从当前日志位置开始读取只捕获启动之后的变更。如果需要从历史的某个时间点开始消费可以改成start_mode timestamp并配合start_timestamp参数。这个选择决定了首次启动时是否能捞到之前的变更数据要根据业务需求来定。第三个是 Kafka sink 的semantic EXACTLY_ONCE。它结合 checkpoint 机制保证每条从达梦读出的变更恰好被写入 Kafka 一次。注意 EXACTLY_ONCE 对 Kafka 版本有要求必须 0.11 以上。如果使用的 Kafka 版本较旧需要降级为AT_LEAST_ONCE这样在极端情况下可能产生少量重复数据需要下游做去重。达梦 CDC 同步链路天然是流式的所以parallelism 1。在 LogMiner 模式下并行读取日志会出现顺序错乱导致下游无法正确还原数据变更顺序。如果单表数据量极大更适合的做法是拆成多个任务按表维度分开同步而不是提高并行度。4. SeaTunnel Web 本地调试与运行验证4.1 部署 SeaTunnel Web 并配置数据源命令行方式对于开发调试没问题但到了团队协作阶段配置管理、任务调度的需求就出来了。这时候用 SeaTunnel Web 能直观地管理任务。这套源码里的seatunnel-web目录就是为本地调试准备的。部署步骤修改seatunnel-web/conf/application.yml把数据库连接指向本地 MySQLWeb 端用 MySQL 存元数据初始化数据库脚本seatunnel-web/sql/seatunnel_server.sql启动 Web 服务默认端口 8080浏览器访问http://localhost:8080用管理员账号登录。进入 Web 控制台后先到“数据源”页面配置 MySQL 和达梦连接。这一步的作用是把连接信息集中管理之后创建同步任务时只需要选择数据源不需要在任务配置里反复写 IP、端口、账号密码。实测下来多人协作时这个机制能明显减少配置错误也方便 DBA 统一管控账号权限。4.2 在 Web 端创建实时同步任务与日志排查Web 端创建任务的逻辑其实和写配置文件大同小异只不是把 JSON 配置拆成了表单。我建议的方式是先切换到“编辑 JSON”模式直接粘贴前面那段达梦 CDC 到 Kafka 的配置保存后任务就创建好了。这个流程里你必须主动拦截两个问题第一个是数据源连通性。很多人在 Web 端填了达梦连接信息但没测试连通性就直接建任务结果任务一跑就报连接超时。Web 端的数据源管理页有“测试连接”按钮务必先测通再往下走。第二个是任务提交之后的状态感知。Web 端提交任务后实际是提交给了 SeaTunnel 集群的作业服务。如果集群没有起来或者 Web 端配置的地址不对任务会一直停在 “SUBMITTED” 状态。排查时先看 Web 端日志再到集群节点上看logs/seatunnel-engine.log两边对比就能定位。调试过程中最有用的功能是“实时日志”面板。每次任务运行时在这个面板能直接看到 checkpoint 完成情况、读取记录数、写入失败的具体异常堆栈。比起命令行方式Web 端的日志面板不用手工翻文件确实方便不少。但要注意Web 端的日志展示有一定延迟几秒到十几秒对于实时性要求高的调试场景还是以服务端日志为准。4.3 命令行检查任务状态的补充方法如果你习惯用命令行操作比如在服务器上排查问题也可以直接用 SeaTunnel 自带的脚本查看任务状态。在bin目录下执行seatunnel-engine.sh -getRunningJob seatunnel-engine.sh -getJobInfo {jobId}第一条命令列出所有正在运行的任务及 ID第二条命令输出指定任务的详细统计信息包括读了多少条、写了多少条、checkpoint 次数、异常信息等。这套源码里我封装了一个job-monitor.sh可以每 5 秒轮询一次并在任务失败时自动抓取最新日志比较适合长时间跑批的同步任务。5. 常见问题与排查技巧实录5.1 连接器加载失败现象提交任务时提示Connector [mysql] not found或No suitable connector。原因绝大多数情况是插件发版版本和配置文件里的 connector 名称对不上。SeaTunnel 的 connector 命名包括连接器类型和版本后缀比如connector-mysql对应配置文件里写MySQL但如果是老版本的connector-cdc-mysql配置文件里就得写MySQL-CDC。名称不匹配时引擎找不到对应实现类。排查方法先看plugins目录下到底有哪些 connector 子目录再对照配置文件里的连接器名逐一比大小写。SeaTunnel 的 connector 名称是大小写敏感的mysql和MySQL是两个概念。另外确认plugin-mapping.properties文件没有被误删引擎依赖这个文件建立名字到实现类的映射。5.2 达梦驱动类冲突现象同步任务启动时抛java.lang.AbstractMethodError或ClassNotFoundException: dm.jdbc.driver.DmDriver。原因这类问题多是驱动 jar 包冲突。SeaTunnel 的 Dameng connector 自带达梦 JDBC 驱动但如果你在lib目录里又放了一份不同版本的驱动就会造成类加载冲突。JVM 加载到到旧版本的驱动时某些新接口方法没有被实现于是抛 AbstractMethodError。解决方法把lib目录下的多余驱动 jar 移走只保留 connector 自带的版本。如果必须用特定版本的驱动把lib目录下的dm-jdbc.jar也替换成相同版本保证全链路加载的是同一个类。5.3 MySQL 同步到达梦时汉字乱码现象数据同步完成后达梦表里的中文数据变成问号或乱码。原因字符集不一致。MySQL 源表是 UTF-8达梦库的字符集如果是 GB18030那么写入时如果两边没有做字符集转换就会出现乱码。排查步骤先确认达梦库的字符集SELECT * FROM V$NLS_PARAMETERS WHERE PARAMETER NLS_CHARACTERSET。如果是 GB18030在 SeaTunnel 连接达梦的 URL 里加上?characterEncodingutf-8并在连接器配置里显式指定charset UTF-8。一套源码里已经预置了charset配置项默认改成 UTF-8 即可。5.4 全量任务同步过程中数据中断现象数据量大的表同步到一半任务失败错误信息显示连接超时或被断开。原因大部分情况是源库设置了wait_timeout长时间运行的查询被数据库掐断了连接。另外如果源库 binlog 格式不是 ROW做 CDC 时也可能因为解析不了而中断。解决思路在 JDBC URL 上增加connectTimeout60000socketTimeout600000参数适当放大超时时间在env段调大checkpoint.interval让 checkpoint 机制更宽松如果是全量同步把源表按主键范围拆成多个分片每个分片单独一个任务避免单个任务运行时间过长。5.5 参数优先级配置文件 vs 命令行这套源码里所有配置都可以灵活组合但你最好明确一个规则命令行传入的参数优先于配置文件。比如配置里写死parallelism 2但提交时命令行加--parallelism 4实际生效的是 4。排查问题时先确认任务实际拿到的参数是什么可以通过--plan模式打印执行计划来确认。6. 从案例到生产的一些体会这套配置案例跑通之后后续扩展方向很清晰。最简单的做法是把 MySQL 源替换成 Oracle 或 PostgreSQL只需改source段里的连接器和 query 语法后面 transform 和 sink 可以原封不动。同理目标端从达梦换成 ClickHouse只需改sink段的连接器类型和写入模式前面的读取和转换几乎不受影响。如果要做实时数仓可以再加上Sink端的 Iceberg 或 Hudi connector把 CDC 数据直接落到数据湖做流批一体。这个扩展方向在社区里已经有不少实践案例但要注意 Iceberg 的 catalog 配置和 hive metastore 的依赖会稍微复杂一些。最后分享一个排错习惯。你在改任何同步任务配置之前先用 git 把当前能跑通的配置提交一个版本。出了问题直接git diff看改了哪些参数绝大多数问题都出在自己改的那几行里。我自己维护数据同步任务的几年里这个习惯帮我省下的时间非常可观。这套源码和配置案例我用下来最直观的收获就是SeaTunnel 本身并不难难的是把不同数据源、不同目标端、不同同步模式排列组合之后还能保持清晰和可控。有了这套可复用的配置模板和排查思路至少我在面对新的同步需求时不是从零开始摸索而是基于已验证的路径做增量调整。本文还有配套的精品资源点击获取