啃不动 SeaTunnel 源码?AI 帮你快速读懂调试

https://github.com/apache/seatunnel

点击蓝字

关注我们

在近期的 Apache SeaTunnel Meetup 上，项目活跃贡献者梁尧博为我们分享了一场非常精彩的话题——AI 时代下如何更高效地进行 SeaTunnel 本地调试。他通过细致的讲解，从环境准备到调试跑通的整个过程都进行了详细的展示，让已经或者打算上手 SeaTunnel 的观众都对如何进行源码调试、问题定位和自己修 bug 有了更直观和深入的了解。现在，分享内容已经整理成文字版，供大家学习参考。

背景

很多人平时用 SeaTunnel，更多是停留在“会配任务、能把流程跑起来”这个阶段。但一旦到了真实项目里，问题往往不会这么听话。可能是依赖冲突，可能是参数不生效，可能是连接器行为和预期不一样，也可能是某个版本本身就有 bug。

这个时候，光会改配置通常不够，最后还是得回到源码、日志、断点和本地调试。只有你能把问题在自己电脑上复现出来，知道它到底卡在哪一层，AI 才能真正帮你分析、改代码、验证结果。

所以本次分享想讲的不是“怎么把 SeaTunnel 跑起来”，而是怎么再往前走一步，做到能看源码、能本地调试、能自己查问题、能自己修 bug。AI 在这里不是替你做判断的人，而是一个很强的搭档。前提是，你得先把环境和问题握在自己手里。

适用人群

适合已经接触或正在使用 SeaTunnel 的数据开发、实施、运维人群，尤其适合那些希望进一步学会源码调试、问题定位和自己修 bug 的人。

1. 环境准备

官方文档：https://seatunnel.apache.org/zh-CN/

先准备这些基础环境：

JDK 8 或 11
Git
JetBrains / IDEA
Maven

这些工具的安装这里就不展开了。如果你本身在写 Java，这一段一般都不陌生。

补一句和 Windows 有关的提醒：

如果你要调试 Hive、Iceberg 这类连接器，后面很可能会碰到HADOOP_HOME或winutils的问题，文末会单独讲。

2. Fork仓库并克隆代码

仓库位置可以从官方文档直接跳转：

官方仓库：

https://github.com/apache/seatunnel

Fork 完以后，你自己的仓库地址会类似这样：

https://github.com/LeonYoah/seatunnel.git

为什么建议先 fork：

后面提交自己的改动更方便
不会直接影响官方仓库
如果要提 PR，这也是更常见的做法

如果网络不太稳定，可以借助代理地址：

git clone https://cdn.gh-proxy.org/https://github.com/LeonYoah/seatunnel.gitcd seatunnelgit checkout 2.3.13-release

如果本地提示没有这个分支，可以先把官方仓库加成上游：

git remote add upstream https://cdn.gh-proxy.org/https://github.com/apache/seatunnel.gitgit fetch upstream --prunegit checkout 2.3.13-release

补充一个常用地址，平时能直接记一下：

https://gh-proxy.com/

3. Maven编译和IDEA设置

先用 IDEA 打开seatunnel项目，然后到Project Structure里把 JDK 指到JDK 8：

然后再看 Maven 设置。

如果你接受把依赖装到系统默认位置，C 盘，且网络环境很好，这一步其实可以简单一点，因为 IDEA 自带 Maven。

如果你想单独指定 Maven 路径，可以先安装自己的 Maven,然后在$MAVEN_HOME/conf/settings.xml里配镜像。下面这份只是参考，本地仓库路径记得换成你自己的：

<?xml version="1.0" encoding="UTF-8"?><settingsxmlns="http://maven.apache.org/SETTINGS/1.0.0"          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">    <localRepository>D:\apache-maven-3.8.6\ck</localRepository>    <proxies>    </proxies>    <servers>    </servers>    <mirrors>        <mirror>            <id>alimaven</id>            <name>aliyun maven</name>            <url>http://maven.aliyun.com/nexus/content/groups/public/</url>            <mirrorOf>central</mirrorOf>        </mirror>        <mirror>            <id>repo1</id>            <mirrorOf>central</mirrorOf>            <name>central repo</name>            <url>http://repo1.maven.org/maven2/</url>        </mirror>        <mirror>            <id>repo2</id>            <name>Mirror from Maven Repo2</name>            <url>https://repo.spring.io/plugins-release/</url>            <mirrorOf>central</mirrorOf>        </mirror>    </mirrors>    <profiles>    </profiles></settings>

然后再到 IDEA 设置里确认：

这里有一项容易漏：

use settings from .mvn/config
记得取消勾选

接着执行下面两个命令：

# 代码格式化mvn spotless:apply# 编译安装mvn clean install -Dmaven.test.skip=true -T 1C

编译完成以后，就可以开始本地调试了。

4. 从example模块起调

常用启动类：

org.apache.seatunnel.example.engine.SeaTunnelEngineLocalExample

先改启动配置：

把provided带上：

然后点击Shorten command line，选择JAR manifest：

最后用Debug模式运行：

5. 用自己的配置文件启动

代码里有这样一行：

String configurePath = args.length > 0 ? args[0] : "/examples/fake_to_console.conf";

这行代码的意思很直接：

如果你启动时传了参数，就读你传入的配置文件
如果没传，就默认读/examples/fake_to_console.conf

所以，自己的配置文件一般放到examples目录下最省事：

6. 实战案例：
pg cdc报错怎么查、怎么修

这里拿一个真实问题举例。

群里有人反馈pg cdc任务报错：

原始堆栈：

	at org.apache.seatunnel.connectors.cdc.base.source.reader.IncrementalSourceSplitReader.fetch(IncrementalSourceSplitReader.java:94)	at org.apache.seatunnel.connectors.seatunnel.common.source.reader.fetcher.FetchTask.run(FetchTask.java:54)	... 7 moreCaused by: org.apache.seatunnel.common.utils.SeaTunnelException: Read split SnapshotSplit(tableId=traffic.public.users, splitKeyType=ROW<id INT>, splitStart=null, splitEnd=null, lowWatermark=null, highWatermark=null) error due to java.lang.NullPointerException.	at org.apache.seatunnel.connectors.cdc.base.source.reader.external.IncrementalSourceScanFetcher.checkReadException(IncrementalSourceScanFetcher.java:216)	at org.apache.seatunnel.connectors.cdc.base.source.reader.external.IncrementalSourceScanFetcher.pollSplitRecords(IncrementalSourceScanFetcher.java:117)	at org.apache.seatunnel.connectors.cdc.base.source.reader.IncrementalSourceSplitReader.fetch(IncrementalSourceSplitReader.java:91)	... 8 moreCaused by: io.debezium.DebeziumException: java.lang.NullPointerException	at org.apache.seatunnel.connectors.seatunnel.cdc.postgres.source.reader.snapshot.PostgresSnapshotSplitReadTask.execute(PostgresSnapshotSplitReadTask.java:112)	at org.apache.seatunnel.connectors.seatunnel.cdc.postgres.source.reader.snapshot.PostgresSnapshotFetchTask.execute(PostgresSnapshotFetchTask.java:65)	at org.apache.seatunnel.connectors.cdc.base.source.reader.external.IncrementalSourceScanFetcher.lambda$submitTask$0(IncrementalSourceScanFetcher.java:96)	... 5 moreCaused by: java.lang.NullPointerException	at org.apache.seatunnel.connectors.seatunnel.cdc.postgres.source.reader.snapshot.PostgresSnapshotSplitReadTask.createDataEventsForTable(PostgresSnapshotSplitReadTask.java:183)	at org.apache.seatunnel.connectors.seatunnel.cdc.postgres.source.reader.snapshot.PostgresSnapshotSplitReadTask.createDataEvents(PostgresSnapshotSplitReadTask.java:170)	at org.apache.seatunnel.connectors.seatunnel.cdc.postgres.source.reader.snapshot.PostgresSnapshotSplitReadTask.doExecute(PostgresSnapshotSplitReadTask.java:136)	at org.apache.seatunnel.connectors.seatunnel.cdc.postgres.source.reader.snapshot.PostgresSnapshotSplitReadTask.execute(PostgresSnapshotSplitReadTask.java:107)	... 7 more

这类问题，有明确报错的，我们第一反应应该先看堆栈里最靠后的Caused by。很多时候，最后一个Caused by才是最原始的异常来源。

这次堆栈里最关键的信息其实是：

Caused by: java.lang.NullPointerExceptionat org.apache.seatunnel.connectors.seatunnel.cdc.postgres.source.reader.snapshot.PostgresSnapshotSplitReadTask.createDataEventsForTable(PostgresSnapshotSplitReadTask.java:183)

看到这里，排查思路就清楚了：

先定位到具体文件和行号
在 IDEA 里打断点
用本地环境把问题复现出来
顺着调用链看变量为什么会是空

在 IDEA 里按两次Shift，搜索PostgresSnapshotSplitReadTask.java:183，然后定位到183行：

因为这是pg-cdc的问题，所以你还得先把相关依赖补到当前运行环境对应的pom.xml里：

<dependency>    <groupId>org.apache.seatunnel</groupId>    <artifactId>connector-jdbc</artifactId>    <version>${project.version}</version></dependency><dependency>    <groupId>org.apache.seatunnel</groupId>    <artifactId>connector-cdc-postgres</artifactId>    <version>${project.version}</version></dependency><dependency>    <groupId>org.apache.seatunnel</groupId>    <artifactId>connector-cdc-base</artifactId>    <version>${project.version}</version></dependency><dependency>    <groupId>org.postgresql</groupId>    <artifactId>postgresql</artifactId>    <version>42.7.5</version></dependency>

补完以后刷新 Maven，第一次运行：

发现根本没复现，没出现空指针，那问题出现在哪呢？

此时我们就应该想到控制变量法，尽可能的保证复现环境一致，于是乎我就又问了出现问题的小伙伴他的 PG 版本和驱动，确定他的 pg数据库是 v18，jdbc 驱动是42.7.5 ，我对比发现我们的驱动是 42.4.3，于是更换驱动...

第二次运行：

更新 pom.xml 然后刷新 Maven，空指针出现！那么问题就在驱动身上，我们把空指针出现的代码位置以及版本问题告诉AI，AI此时就开始马力全开，按照真正的方向去定位问题。

总结一下根本原因：就是驱动版本过高影响的，用 42.4.3 会报错，但是用42.7.5 会出现空指针。具体排查思路大家可以看这个 pr:https://github.com/apache/seatunnel/pull/10058

ai给出的修复代码：

TableId tableIdWithoutCatalog = new TableId(null, tableId.schema(), tableId.table());Table table = databaseSchema.tableFor(tableIdWithoutCatalog);if (table == null) {    String catalog = tableId.catalog();    if (catalog == null || catalog.isEmpty()) {        catalog = connectorConfig.databaseName();    }    if (catalog != null && !catalog.isEmpty()) {        TableId tableIdWithCatalog = new TableId(catalog, tableId.schema(), tableId.table());        table = databaseSchema.tableFor(tableIdWithCatalog);    }}if (table == null) {    throw new IllegalStateException(            String.format("Cannot find table schema for %s", tableId));}createDataEventsForTable(snapshotContext, snapshotReceiver, table);

问题修完以后，再开始打包：

打开 Maven 面板
先做代码格式化
再执行clean install
找到对应 jar，上传到服务器connectors目录，替换同名 jar
重启 SeaTunnel 集群

8.1 Windows 打包整套 SeaTunnel 后，shell 脚本报错

如果你打的是整套安装包：

mvn clean package -pl seatunnel-dist -am -Dmaven.test.skip=true

参考：https://www.cnblogs.com/qixing/p/14287479.html

在 Linux 服务器上解压后，如果报这个错：

#/bin/sh^m: 坏的解释器: 没有那个文件或目录

一般是脚本换行符有问题。

可以这样处理：

doc2unix bin/*.sh

或者手动处理单个脚本：

sed -i 's/\r$//' seatunnel.sh

8.2 Windows 下的 HADOOP_HOME / winutils 问题

如果你在 Windows 下调试 Hive、Iceberg 这类连接器，经常会碰到这个错误：

java.io.FileNotFoundException: HADOOP_HOME and hadoop.home.dir are unset

原因通常不是“少装了一个普通依赖”，而是 Windows 缺少 Hadoop 那部分本地运行支持。

这时候，即使你装了 Hadoop，本地也不一定能直接用。更常见的办法是补winutils。

winutils.exe是 Hadoop 在 Windows 下运行时需要的本地工具，用来补 Linux 环境里的那部分系统调用。从 Hadoop 2.2 开始，这个文件不再跟安装包一起发，所以需要自己下载和配置。

安装步骤：

下载：

git clone https://cdn.gh-proxy.org/https://github.com/cdarlint/winutils.git

配置HADOOP_HOME环境变量

示例值：

D:\ideaProject\winutils\hadoop-2.9.2

安装完成以后，Windows 就可以正常使用hadoop命令了。

结语

AI 时代并没有让读源码和调试过时，恰恰相反，它们变得更有价值了。你越能把环境跑起来、把问题复现出来、把断点打进去，AI 就越能真正帮上忙。

希望这篇分享能让大家从“会配任务、能跑起来”，再往前走一步，变成能看源码、能本地调试、能独立查问题、也能自己修 bug 的人。这样以后再碰到问题，我们就不是只能等答案，而是可以带着 AI 一起把问题查清楚、改明白、真正解决。

·END·

白鲸开源

白鲸开源是一家开源原生的DataOps商业公司，是国家高新技术企业，由多个Apache Foundation Member成立，80%员工都是 Apache Committer，运营2个全球Apache开源项目(DolphinScheduler, SeaTunnel）。白鲸开源已根据全球最佳实践发布商业版产品WhaleStudio(含白鲸数据调度平台WhaleScheduler和白鲸数据集成平台WhaleTunnel）。我们致力于打造下一代开源原生的DataOps 平台，助力企业在大数据和云时代，智能化地完成多数据源、多云及信创环境的数据集成、调度开发和治理，以提高企业解决数据问题的效率，提升企业分析洞察能力和决策能力。

了解更多

公司网站:www.whaleops.com

联系邮箱: xiyan@whaleops.com

如果您希望深入了解文中提到的数据质量功能，或者讨论如何将 WhaleStudio 与你的业务流程相结合，我们非常愿意为你提供帮助。欢迎扫码获取WhaleStudio产品白皮书。