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

背景

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

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

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

适用人群

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

1. 环境准备

官方文档： Apache SeaTunnel

先准备这些基础环境：

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.git
cd seatunnel
git checkout 2.3.13-release

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

git remote add upstream https://cdn.gh-proxy.org/https://github.com/apache/seatunnel.git
git fetch upstream --prune
git 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"?>
<settings xmlns="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 目录下最省事：

p10

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

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

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

p11

原始堆栈：

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 more
Caused 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 more
Caused 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 more
Caused 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.NullPointerException
at org.apache.seatunnel.connectors.seatunnel.cdc.postgres.source.reader.snapshot.PostgresSnapshotSplitReadTask.createDataEventsForTable(PostgresSnapshotSplitReadTask.java:183)

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

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

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

p12

因为这是 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>

p13

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

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

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

第二次运行：

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

p14 总结一下根本原因：就是驱动版本过高影响的，用 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 集群

7. AI 怎么用，效果才更好

很多人现在一遇到问题，第一反应就是把报错直接复制到网页版 DeepSeek 或 ChatGPT 里。这样不是完全没用，但大多数时候，得到的是“检查配置”“尝试升级版本”“看看依赖是不是冲突”这一类泛化建议。

p19 这类回答的问题不在于它一定错，而在于它经常不够贴近你当前的项目和环境。尤其是下面这些情况：

问题很新
问题和当前源码分支强相关
需要真实运行环境才能判断
需要结合日志、配置、依赖和调用链一起看

所以更推荐的方式是：

本地先把环境跑起来
把源码、日志、配置和复现步骤准备好
再让 AI 一起看代码、看异常、看执行过程

这时候，像 Codex、 Claude Code 这类工具的价值就会更明显，因为它们不只是“回答一个问题”，而是能直接参与到代码、环境和执行过程中。

参考下面的案例：

p20

这里我们就可以看到， ai能够运行 docker 去跑一个真实 pg环境验证 bug,也能直接调用 jar 包执行去分析 DatabaseMetaData的行为，且定位到了真实问题就是驱动版本影响的，这提供了非常大的便利。

8. 常见补充问题

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

p21

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

p22

结语

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

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

ITPub博客

AI 让 SeaTunnel 读源码和调试过时了吗？

背景