简介：KettleWeb数据集成平台源码基于Kettle原生6.1.0.1版本扩展开发，面向需要处理大量数据集成任务的中高级Java开发者与数据分析团队。它在保留Kettle核心转换能力的基础上，补充了Web端操作界面，让用户无需依赖桌面客户端即可完成数据抽取、转换与加载流程，适合企业内部ETL工具搭建与二次开发学习。资源包共约2000个文件，压缩后49.81MB，以754个gif图像、633个db数据库文件、159个JavaScript脚本、140个Java源码、118个CSS样式表为主，另含12个ktr转换配置、11个xml配置及少量properties、json等文件，前端样式与后端逻辑分层清晰。目前已有896人学习下载。读者可从中获取完整的Java Web工程结构、Kettle集成调用示例、前端主题与表单样式实现，以及转换配置文件的组织方式，便于快速理解数据集成平台的架构设计与功能扩展思路。
1. 从一次数据同步事故说起：KettleWeb 到底解决什么问题
凌晨两点，业务方在群里甩出一张截图：报表里的订单金额比昨天少了三十万。排查到四点，根因不是 SQL 写错，也不是数据库抽风，而是三台机器上各跑着一份.kjb和.ktr文件，运维手动改过其中一台的连接参数，另外两台还在往旧库写。这种「脚本散落、配置漂移、没人知道谁在跑什么」的场面，做数据集成的同学大概率都经历过。
KettleWeb 这个方向，本质就是把 Pentaho Data Integration（大家更熟的叫法是 Kettle）那套转换和作业能力，从桌面客户端 Spoon 里搬到一个 Java Web 平台上：浏览器里建转换、配数据库连接、定时调度、看执行日志，底层还是 Kettle 引擎在跑。它要解决的不是「Kettle 能不能抽数据」，而是「几十上百个转换怎么集中管、怎么让非开发人员也能改、怎么在出问题时快速定位」。适合谁？手里已经有一堆 Kettle 脚本、被运维和业务方追着改配置的 Java 后端；也适合想拿一个真实 Web 项目练手、把 Java 基础、Spring Boot、MyBatis、前端表格这些点串起来的人。源码类项目最容易踩的坑是「跑不起来」，所以下面我会按能复现的顺序讲，而不是按教科书目录讲。
2. 把 KettleWeb 跑起来：环境、依赖与最小启动路径
2.1 先确认 Kettle 引擎和 JDK 的版本咬合关系
Kettle 是 Java 写的，它对 JDK 版本相当敏感。老版本 PDI 在 JDK 8 上稳，新版本 PDI 往 JDK 11、17 迁移时，pentaho-kettle依赖里有些反射调用会报InaccessibleObjectException。我一般先做一件事：把项目pom.xml里 Kettle 相关依赖的版本号抄下来，去 Maven 中央仓库确认它编译时用的 JDK，再决定本地装哪个 JDK。
<!-- pom.xml 里 Kettle 核心依赖的典型形态 --> <dependency> <groupId>pentaho-kettle</groupId> <artifactId>kettle-core</artifactId> <version>9.4.0.0-343</version> <!-- 版本号以你拿到的源码为准 --> </dependency> <dependency> <groupId>pentaho-kettle</groupId> <artifactId>kettle-engine</artifactId> <version>9.4.0.0-343</version> </dependency>逻辑说明：kettle-core提供转换/作业的元数据模型，kettle-engine提供执行引擎，两个都要引，只引一个会在TransMeta或Trans初始化时报NoClassDefFoundError。参数说明：版本号必须和源码里其他 Pentaho 依赖保持一致，混用不同小版本经常出现StepMetaInterface接口不匹配。如果源码里用的是pentaho-kettle老坐标，注意它和org.pentaho.di新坐标的包名差异，改坐标时 import 也要跟着改。
2.2 数据库和连接池：别让元数据库拖垮启动
KettleWeb 自己需要一个库存用户、转换定义、调度记录，Kettle 仓库（Repository）又需要一个库存转换元数据。常见做法是两者共用一个 MySQL 实例、不同 schema。启动前先建库建表，源码里一般带schema.sql或init.sql，用命令行导入最稳。
# 建库并导入初始化脚本，字符集必须显式指定 mysql -uroot -p -e "CREATE DATABASE kettleweb DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;" mysql -uroot -p kettleweb < sql/init.sql # 确认表是否建全，重点看这几张 mysql -uroot -p kettleweb -e "SHOW TABLES;"逻辑说明：utf8mb4是为了兼容转换名、字段注释里的中文和特殊符号，用utf8在存 emoji 或生僻字时会截断。参数说明：init.sql路径以源码实际目录为准，有的项目放在src/main/resources/db下。导入后重点确认t_transformation、t_job、t_schedule、t_user这几张表存在，缺表通常是脚本没跑完或中途报错被忽略。
连接池配置在application.yml里，Kettle 引擎自己也会开连接，所以池子不能配太小。
spring: datasource: url: jdbc:mysql://127.0.0.1:3306/kettleweb?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai username: root password: your_password hikari: maximum-pool-size: 20 # 平台自身 + Kettle 执行共用，别低于 10 minimum-idle: 5 connection-timeout: 30000逻辑说明：serverTimezone不写会在 MySQL 8 上抛时区异常，这是血泪经验。参数说明：maximum-pool-size要按并发转换数估，一个转换执行期间可能占用 1 到 2 个连接，20 是中小规模的安全值；如果调度任务多，调到 30 以上并同步调大 MySQL 的max_connections。
2.3 启动与第一个转换：从 Spoon 文件到 Web 执行
源码项目一般提供两种入口：上传已有的.ktr文件，或在 Web 界面里新建。先用上传方式验证引擎通不通，比在界面里点半天快。
// 用 Kettle API 加载并执行一个转换的最小示例 KettleEnvironment.init(); // 全局初始化，整个 JVM 只调一次 TransMeta transMeta = new TransMeta("path/to/demo.ktr"); Trans trans = new Trans(transMeta); trans.execute(null); // null 表示不传命令行参数 trans.waitUntilFinished(); // 阻塞等待，Web 环境要放线程池里 if (trans.getErrors() > 0) { // 记录 trans.getResult() 里的错误行数，别只打一句"执行失败" }逻辑说明：KettleEnvironment.init()会加载插件、初始化日志，重复调用会报错，所以通常放在 Spring 的@PostConstruct或静态块里只执行一次。参数说明：waitUntilFinished()是阻塞的，在 Web 请求线程里直接调会把 Tomcat 线程占死，正确做法是丢进ExecutorService异步执行，前端轮询执行状态。trans.getErrors()返回错误条数，配合trans.getResult().getLogText()才能拿到具体哪一行出错。
3. Web 层怎么管转换：定义、调度与执行状态
3.1 转换定义的存储模型：元数据拆表还是整文件存
这是设计上第一个要拍板的地方。常见两种做法：一种是把.ktr的 XML 整体存进一张表的LONGTEXT字段，另一种是解析成步骤、跳、连接等结构化表。前者实现快、和 Kettle 原生格式零损耗，后者查询灵活但解析和回写复杂。
| 方案 | 优点 | 代价 | 适用场景 |
|---|---|---|---|
| 整文件存 XML | 实现简单，兼容所有步骤类型 | 无法按步骤查询，改一个字段要整体替换 | 转换数量少、以执行为主 |
| 结构化拆表 | 可按步骤/连接检索，支持细粒度权限 | 解析器要覆盖所有 StepMeta，工作量大 | 需要多人协作、审计 |
我一般选整文件存 XML，因为 Kettle 的步骤类型太多，结构化拆表很难覆盖全，遇到没解析的步骤就丢配置。存的时候加一个版本号字段，每次保存生成新版本，出问题能回滚，这就是后悔药。
CREATE TABLE t_transformation ( id BIGINT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(128) NOT NULL, content LONGTEXT NOT NULL, -- .ktr 的 XML 原文 version INT NOT NULL DEFAULT 1, create_time DATETIME NOT NULL, update_time DATETIME NOT NULL, UNIQUE KEY uk_name_version (name, version) );逻辑说明：UNIQUE KEY保证同名转换版本不重复，查询最新版用ORDER BY version DESC LIMIT 1。参数说明：content用LONGTEXT而不是TEXT，因为复杂转换的 XML 很容易超过 64KB。version每次保存自增，不要用更新时间当版本，同一秒内两次保存会撞。
3.2 调度：Quartz 和 Kettle 作业的边界在哪
调度这块最容易混淆：Kettle 自己有Job（.kjb），里面可以有Start步骤和定时；Quartz 是 Java 侧的调度框架。两者别叠着用，否则会出现「Quartz 触发一次，Kettle 作业内部又按自己的定时再跑一次」的翻车现场。
我的做法是：调度统一交给 Quartz，Kettle 作业只负责「被调用时执行一次」，把.kjb里的定时步骤去掉。
// Quartz Job 里调用 Kettle 转换 public class KettleExecuteJob implements Job { @Override public void execute(JobExecutionContext context) { Long transId = context.getMergedJobDataMap().getLong("transId"); // 从库里取 XML，落成临时文件或直接构造 TransMeta TransMeta transMeta = new TransMeta(new ByteArrayInputStream(xml.getBytes(StandardCharsets.UTF_8)), null, true, null, null); Trans trans = new Trans(transMeta); trans.execute(null); trans.waitUntilFinished(); // 把 trans.getResult() 写进执行记录表 } }逻辑说明：new TransMeta(InputStream, ...)这个构造可以直接吃 XML 流，省去落临时文件，但要注意编码统一用 UTF-8。参数说明：context.getMergedJobDataMap()拿的是调度时传的参数，transId用来定位转换。执行结果一定要落库，否则前端只能看到「成功/失败」，看不到处理了多少行、耗时多久，排障时就是黑匣子。
3.3 执行状态回传：轮询还是长连接
前端要知道转换跑到哪了，两种常见做法：定时轮询执行记录表，或者用 WebSocket 推。轮询实现简单，但转换多的时候数据库压力大；WebSocket 实时，但要处理断线重连。
// 前端轮询执行状态的简化写法 async function pollStatus(execId) { const timer = setInterval(async () => { const res = await fetch(`/api/exec/${execId}/status`); const data = await res.json(); if (data.state === 'FINISHED' || data.state === 'FAILED') { clearInterval(timer); // 终态必须清掉，否则一直打接口 renderResult(data); } }, 2000); }逻辑说明：setInterval必须在拿到终态时clearInterval，否则页面不关就一直请求，这是新手最常见的资源泄漏。参数说明：轮询间隔 2000ms 是体验和压力的折中，转换普遍跑几分钟以上可以放到 5000ms。如果项目里已经集成了 WebSocket，优先用推送，轮询只作为降级方案。
4. 避坑与排查：KettleWeb 落地时最容易翻车的五件事
4.1 转换在 Spoon 里能跑，Web 里报找不到插件
现象：同一个.ktr，Spoon 执行正常，Web 平台执行报StepMetaInterface找不到或ClassNotFoundException。
原因：Kettle 的步骤是插件机制，Spoon 启动时会扫描plugins目录，Web 项目打包成 jar 后插件目录没被打进去，或者KETTLE_HOME没设对。
解决：在启动脚本里显式设置KETTLE_HOME指向包含plugins的目录，或者把用到的插件依赖单独引到pom.xml。启动时打印一次KettleEnvironment的插件加载日志，确认目标步骤在列表里。
4.2 中文乱码：从库到文件一路都是坑
现象：抽取出来的中文变成问号或乱码。
原因：三个环节都可能出问题——MySQL 连接串没写characterEncoding、Kettle 步骤里的字段编码没设、输出文件没指定编码。
解决：连接串统一加useUnicode=true&characterEncoding=utf8；文本文件输出步骤里显式选 UTF-8；数据库字段和表都用utf8mb4。三处都对齐后再测，只改一处往往还是乱。
4.3 调度任务重复执行
现象：一个转换在日志里同一分钟跑了两三次。
原因：Quartz 集群模式下没配isClustered，或者多实例部署时每个实例都注册了同一个触发器。
解决：Quartz 配置里开启集群，用数据库锁；或者调度层加分布式锁，执行前先抢锁。单机部署也要检查是不是重复注册了 Job。
4.4 大表抽取把内存打爆
现象：转换跑一会儿就OutOfMemoryError。
原因：Kettle 默认按批提交，但某些步骤（排序、聚合）会把数据全量加载进内存。
解决：排序、聚合类步骤调大临时文件使用、限制缓存行数；抽取时加LIMIT分批，或者用「表输入 + 分页」的方式。JVM 启动参数-Xmx按数据量调，但根治要靠分批。
4.5 执行记录只写成功不写失败
现象：转换失败了，但执行记录表里状态还是「运行中」。
原因：trans.waitUntilFinished()之后的异常没被捕获，或者异步线程里抛异常没人接。
解决：用try-catch-finally包住执行逻辑，finally里根据trans.getErrors()更新终态。异步执行要用Future.get()拿异常，别把异常吞在线程池里。
5. 进阶：把 KettleWeb 做成能长期维护的平台
跑通只是起点，真正决定这个平台能不能活下去的，是几件容易被忽略的事。
第一件是执行日志的留存策略。Kettle 的日志量很大，一个跑几小时的转换能产生几十 MB 日志。全存数据库，几个月后表就爆了。我的习惯是：执行记录表只存摘要（状态、行数、耗时、错误数），详细日志按天落文件，文件名带执行 ID，前端要看详情时按 ID 去读文件。这样数据库轻，日志也能长期保留。
第二件是转换的版本对比。前面说了每次保存生成新版本，但光有版本没用，得能看 diff。Kettle 的 XML 结构规整，用XMLUnit或简单的文本 diff 就能对比两个版本的差异，前端高亮显示改了哪些步骤、哪些连接参数。这个功能在多人协作时能省掉大量「谁改的、改了什么」的扯皮。
第三件是参数化。硬编码的连接信息是运维噩梦。把数据库连接、文件路径、日期范围抽成 Kettle 的命名参数，Web 界面提供参数表单，调度时传入。这样同一个转换能复用到不同环境，不用为测试和生产各存一份。
| 能力 | 最小实现 | 进阶实现 |
|---|---|---|
| 日志 | 存摘要到库 | 摘要入库 + 详情落文件 + 按 ID 检索 |
| 版本 | 版本号自增 | 版本 diff + 一键回滚 |
| 参数 | 转换内写死 | 命名参数 + Web 表单 + 调度传参 |
| 权限 | 登录即可用 | 按转换/按操作分配权限 |
最后说个验证方法：拿一个真实的、有几十万行数据的转换，在 Web 平台跑一遍，对比 Spoon 里的执行结果，行数、金额汇总、错误行都要一致。不一致就说明参数传递或编码有问题，别急着上生产。
我自己踩过最深的坑，是早期图省事把执行逻辑直接写在 Controller 里，同步阻塞，结果一个慢转换把整个应用的线程占满，所有接口都超时。后来改成异步加状态轮询，才稳定下来。做这类平台，执行和展示一定要解耦，这个习惯我保持到现在。希望帮到你。
本文还有配套的精品资源，点击获取
