简介面向数据集成开发与ETL学习者的Pentaho Kettle 9.5自编译包适配macOS M1芯片及Windows、Linux平台需JDK17运行解压后即可使用图形化设计与任务调度功能适合快速搭建实验环境或进行版本迁移验证。压缩包约387.49MB共1078个文件包含626个jar核心库与插件、196个ktr转换样例、19个kjb作业文件以及xml配置、svg/xul界面资源、bat与sh跨平台启动脚本和说明文档目录结构完整便于按模块检索和二次扩展。已有2875人学习下载。读者可获得可直接运行的ETL开发环境通过内置转换与作业样例熟悉数据抽取、清洗、转换和加载流程也能结合脚本与配置理解多平台启动、插件加载及调试排错思路对研究Kettle 9.5新版本特性的技术人员同样有参考价值。1. macOS 上拿到 pdi-ce-9.5.0.1-261 之后先判断它能不能跑你的活在 macOS 上做批量数据搬运很多人第一步就卡在环境上其实包本身没问题——pdi-ce-9.5.0.1-261 是 Kettle 9.5 的社区版完整发行包解压即用不需要安装器也不写注册表。它解决的是「把散落在 CSV、Excel、各种关系库里的数据按一套可视化的步骤串起来定时跑、可回放」这件事。Spoon 负责画流程pan 跑单个转换kitchen 跑作业carte 提供一个远程执行端点四个入口覆盖了从开发到调度的完整链路。适合已经在用 JDBC 做数据同步、但受够了手写脚本难维护的中小团队也适合要给别人交付一套「看得见流程」的 ETL 的人。不适合追求极致吞吐的实时链路它是批处理工具认清这一点后面少走很多弯路。2. 解压之后先动这几处四个入口脚本、JDK 版本与 lib 目录拿到压缩包解压你会看到一个># 列出本机已安装的所有 JDK注意看版本号和架构x86_64 / arm64 /usr/libexec/java_home -V输出里会带路径和架构信息这一步很重要因为后面 Apple Silicon 的问题就出在架构上。找到 1.8 或 11 的那一行把它固定下来# 临时指定只对当前终端会话生效适合先验证能不能起来 export JAVA_HOME$(/usr/libexec/java_home -v 1.8) # 进到解压目录用绝对路径启动避免相对路径带来的 classpath 问题 cd /opt/pdi-ce-9.5.0.1-261/data-integration ./spoon.sh-v 1.8是向java_home要 1.8 版本如果你装的是 11 就换成-v 11。验证通过之后把这行export写进~/.zshrc或者更省事的做法是直接打开spoon.sh在文件靠前的位置插一行显式的JAVA_HOME赋值——这样别人拿到这份目录也能跑不依赖他自己的 shell 配置。提示不要图省事在spoon.sh里写死某个 JDK 的完整路径里的版本号机器升级 JDK 之后脚本会静默失效报错信息还指不到这一行。启动成功后会弹出 Spoon 的主窗口左边是「转换」和「作业」两棵树。如果窗口出来了但一片空白、或者闪一下就没了先别怀疑包坏了翻到第 5 章对号入座。2.3 lib 与 plugins驱动和插件的正确落点lib目录是运行时 classpath 的一部分所有 JDBC 驱动、公共依赖都放这里。Kettle 9.5 的lib里已经预置了一部分驱动但版本往往偏旧连新版本的数据库服务端时容易报协议不兼容。判断当前带了什么cd /opt/pdi-ce-9.5.0.1-261/data-integration # 看看已经预置了哪些数据库驱动注意版本号 ls lib | grep -i -E mysql|postgresql|ojdbc|mssql|sqlite如果要换驱动做法是先删旧的再放新的不要两个版本的 jar 共存。同一个驱动两个版本同时在lib里JVM 加载哪一个取决于 classpath 顺序表现出来就是「有时候能连、有时候连不上」这种玄学问题。# 把新驱动复制进 lib然后删掉同名的旧版本 cp ~/Downloads/mysql-connector-j-8.x.x.jar lib/ # 确认目录里只剩一个 mysql 驱动 ls lib | grep -i mysql移动或替换 jar 之后必须重启 SpoonJava 不会热加载 classpath 里的新 jar。这一点看起来是常识但我见过太多次「驱动放进去了怎么还是连不上」最后发现是窗口一直没关。plugins目录是另一套机制放的是 Kettle 的步骤插件比如某些大数据的输入输出步骤结构和lib不一样每个插件一个子目录里面有自己的plugin.xml。除非你要装额外的步骤类型否则这个目录不用碰。2.4 用户级配置放在 ~/.kettle 的意义第一次启动 Spoon 之后用户主目录下会多出一个.kettle目录这里面放的是跟「这台机器上这个用户」绑定的配置和安装目录完全分离。# 看看 Spoon 启动后生成了什么 ls -la ~/.kettle里面通常会有几个关键文件kettle.properties存全局变量shared.xml存共享的数据库连接repositories.xml存资源库列表。这个分离设计的价值在于安装目录可以多人共用、可以整体替换升级而每个人的连接密码和变量各自独立。kettle.properties的用法值得单独说一句。它是一个纯 keyvalue 文件里面定义的变量在任何转换和作业里都能通过${变量名}引用适合放环境相关的值比如数据库地址、输出根目录# ~/.kettle/kettle.properties # 这里放跟环境绑定的值转换里用 ${变量名} 引用 DWD_DB_HOST127.0.0.1 DWD_DB_PORT3306 DWD_DB_NAMEdwd OUTPUT_ROOT/data/etl/out这样做的好处是同一份.ktr文件在开发机和生产机上不用改任何东西换一份kettle.properties就行。代价是这个文件不在版本控制里团队协作时要单独维护一份模板。我一般会在项目仓库里放一个kettle.properties.example把必须配的项列全新人照着填。3. 在 Spoon 里拉一条 CSV 到库的转换连接、类型与批量提交参数这一章用一个具体场景走完整条链路本地有一个每日导出的 CSV要清洗掉无效行、统一字段类型、补一个自增主键最后写进数据库表。这条链路短但把连接、编码、类型、批量提交四个最容易出问题的地方全踩了一遍跑通它之后做更复杂的转换就是加步骤的事。3.1 先建共享连接还是本地连接Spoon 里建数据库连接有两个入口一个是转换画布上双击「表输入」这类步骤时弹出的本地连接另一个是菜单里的「共享连接」。两者的区别不是配置项多少而是连接的存活范围。共享连接存在~/.kettle/shared.xml里所有转换和作业都能引用改一次全局生效本地连接只存在于当前这个.ktr文件里跟着文件走。团队协作时我倾向于用本地连接原因是共享连接跟着人走、不跟着文件走别人拿到你的.ktr打开一看连接名是有的但配置是空的跑起来直接报错。建连接时几个字段值得多说两句字段说明常见误填连接类型选具体数据库类型不要选「通用」选通用后驱动类要手填容易写错包名主机名称只填主机不要带端口和库名填成127.0.0.1:3306/dwd会连接超时数据库名称只填库名某些驱动要求填完整 URL看类型端口号默认值通常是对的改过端口的要手动改忘了改连到默认端口上的另一个实例用户名/密码建议在转换里用变量引用明文密码跟着.ktr进了代码仓库最后一行的处理方式是密码栏里填${DWD_DB_PASSWORD}然后在kettle.properties或者启动参数里给值。这样.ktr文件可以放心提交。建完连接后Spoon 左下角有个「测试」按钮点一下会真的去连一次。这一步不要跳过因为连接配置错误在画布上是看不出来的只有在真正执行时才会暴露而那时候你已经画了十几个步骤了。3.2 输入步骤的两个必调项分隔符与编码拖一个「CSV 文件输入」到画布上双击打开。文件名那一栏可以直接填路径也可以填${OUTPUT_ROOT}/daily.csv这种带变量的形式后者在切换环境时更省事。真正需要动手调的是两个地方。第一是分隔符。默认是逗号但如果你的导出文件用的是制表符或者竖线必须改。更隐蔽的情况是文件里既有逗号又有引号包裹的字段比如北京,朝阳,100这种要在「分隔符」旁边的引号选项里把「封闭符」设成双引号否则第一列会被切成两列后面所有字段整体错位一位而且不会报错数据就这么静默地错了。第二是编码。macOS 上本地生成的 CSV 默认是 UTF-8但如果你这个文件是从某些表格软件另存出来的很可能是 UTF-8 带 BOM。BOM 是文件开头三个不可见字节Kettle 读进来会把它粘在第一个字段名上导致后面「表输出」时报「未知列」。在输入步骤的编码下拉里明确选UTF-8然后点「预览」看第一行的字段名有没有异常字符。预览窗口是这条链路上最值得反复用的工具。它把当前步骤的输出前若干行直接摊开给你看字段名、类型、值一目了然。我一般会在每个关键步骤后面都点一次预览而不是等整条转换跑完再回头找是哪一步出的问题。3.3 字段选择与过滤记录把类型转换做在入口CSV 输入出来的所有字段默认都是字符串。如果直接把字符串往数据库的整型列里塞有的驱动会自动转有的会报错行为不一致。正确做法是紧跟着加一个「字段选择」步骤在「元数据」标签页里把每个字段的类型、长度、格式一次性定死。「字段选择」这个步骤名字有点误导它其实干三件事改名、改类型、删字段。配置上分两个标签页「选择和修改」管改名和删除「元数据」管类型。新手常犯的错是只改了「选择和修改」里的字段名忘了在「元数据」里同步改结果改名没生效。字段选择 配置要点元数据标签页 -------------------------------- id_raw - Integer 长度 10 amount - Number 长度 15,2 格式 #,##0.00 biz_date - Date 格式 yyyy-MM-dd remark - String 长度 255日期字段这里有个坑CSV 里的日期是字符串2024-05-01元数据里把类型设成 Date 的同时格式必须填yyyy-MM-dd并且和源数据完全一致。少一个字符都会解析成 null而且不报错只是那一列全空。填完之后立刻预览看到日期列显示成正常的日期格式才算过。类型定好之后接一个「过滤记录」步骤用来剔掉不想要的行。比如金额为空或者为负的行直接丢弃条件写成amount IS NULL OR amount 0然后在「发送 true 的数据到」里接一个空步骤或者直接不接把 false 的分支接到下游。这个「true 丢弃、false 保留」的接法一开始有点反直觉但只要记住过滤记录是「满足条件的走 true 分支」就不会搞混。3.4 表输出的批量参数与失败处理最后一个步骤是「表输出」。目标表、数据库连接、字段映射都好理解真正影响成败的是下面这几个参数。第一是「提交记录数量」默认是 1000。这个值决定每多少行做一次 commit。设太小比如 1那就是逐行提交速度慢到无法接受设太大比如 100000一旦中途失败回滚的代价很大而且某些数据库对单次事务的日志量有上限。1000 到 5000 是比较稳妥的区间具体看单行大小。第二是「不执行任何更新只做插入」这个勾选项。勾上之后走的是纯 insert 路径速度最快但主键冲突会直接抛异常终止整条转换。如果你的数据可能有重复要么在上游先去重要么改用「插入/更新」步骤。第三是「指定数据库字段」这个按钮。点开它会列出目标表的字段你要把上游的流字段一一映射过去。这里最容易出问题的是字段顺序和大小写尤其当目标表在不同数据库上建的时候大小写策略不一样。建议映射完之后点一次「SQL」按钮看看它生成的 insert 语句长什么样字段名和占位符对得上才算完。-- 表输出实际生成的语句大致长这样字段数量必须和映射一致 INSERT INTO dwd.daily_summary (id, biz_date, amount, remark) VALUES (?, ?, ?, ?);四个步骤串起来整条转换大概是这个样子CSV 文件输入 → 字段选择 → 过滤记录 → 表输出。画完之后先按 F8 跑一次Spoon 底部会显示每一步的读入/写出行数和耗时。如果某一步的「写出」是 0说明上游条件把它全过滤掉了回去看过滤记录的条件写反没有。4. 脱离图形界面pan 与 kitchen 的参数、变量和退出码Spoon 里跑通只是第一步真正的价值在于能脱离图形界面、被调度器反复触发。这一章讲清楚 pan 和 kitchen 怎么传参、变量在哪里生效、退出码怎么被调度器识别——这三点没搞明白跑批永远是手工活。4.1 pan 跑单个转换的最小命令集pan 是用来执行单个.ktr的。最小可用命令就一行# 进到安装目录用绝对路径指定转换文件日志级别设成 Basic cd /opt/pdi-ce-9.5.0.1-261/data-integration ./pan.sh \ -file/data/etl/ktr/daily_load.ktr \ -levelBasic \ -logfile/data/etl/logs/daily_load_$(date %Y%m%d).log三个参数各自的含义-file指向.ktr的绝对路径。用相对路径也能跑但它是相对于当前工作目录解析的而调度器触发时的当前目录往往不是你想象的那个所以一律写绝对路径。-level控制日志详细程度可选值从少到多是Nothing、Error、Minimal、Basic、Detailed、Debug、Rowlevel。日常跑批用Basic出了问题临时改成Detailed复跑一次。Rowlevel会把每一行数据都打出来日志能瞬间涨到几个 G除了排查极难复现的单行问题平时不要开。-logfile把日志写文件同时终端也会输出一份。文件名里拼日期是个小习惯配合日志轮转脚本能省掉后面清理的麻烦。参数传递用-param:# 传一个业务日期参数给转换里的 ${batch_date} ./pan.sh \ -file/data/etl/ktr/daily_load.ktr \ -param:batch_date2024-05-01 \ -param:envprod \ -levelBasic转换里所有出现${batch_date}的地方都会被替换成2024-05-01。注意是替换不是变量赋值所以在「表输入」的 SQL 里用它的时候要勾上「替换 SQL 语句里的变量」这个选项否则 SQL 会原样带着${batch_date}发给数据库报语法错误。4.2 kitchen 跑作业与变量传递的两条路径kitchen 执行的是.kjb作业文件。作业和转换的区别在于作业是「流程编排」——它可以串多个转换、加条件判断、发邮件、执行 shell。所以 kitchen 的参数体系和 pan 基本一致但变量传递要多想一层。# 跑一个作业传入起始日期日志级别用 Detailed 方便排查 cd /opt/pdi-ce-9.5.0.1-261/data-integration ./kitchen.sh \ -file/data/etl/kjb/daily_job.kjb \ -param:start_date2024-05-01 \ -levelDetailed \ -logfile/data/etl/logs/daily_job.log作业里传变量给下游转换有两条路可以走。第一条是用-param传进来的参数。它在整个作业生命周期内可见作业里的「转换」步骤执行子转换时子转换可以直接用${start_date}引用。这条路最简单缺点是参数的值在作业启动时就固定了中途改不了。第二条是在作业里用「设置变量」步骤。这个步骤可以在流程中间动态生成变量比如把上一步查出来的最大 ID 存成变量传给下一个转换。关键点在于「变量作用域」这个下拉框选「根作业」是整个作业链都可见选「父作业」只对上一层可见。选错了的现象是变量明明设了下游转换里取出来是空的。我一般的做法是外部传进来的用-param流程中间算出来的用「设置变量」并选「根作业」两者不要混着用同一个名字否则谁覆盖谁完全取决于执行顺序。4.3 日志级别与退出码调度器到底看什么调度器不管是系统自带的还是第三方的判断一次跑批成没成看的不是日志里有没有「ERROR」字样而是进程退出码。这一点是很多人忽略的。pan 和 kitchen 的退出码约定很简单0 表示整个转换/作业执行成功非 0 表示有步骤失败。所以你的调度脚本里必须检查这个值#!/bin/bash # 跑批并检查退出码非 0 就把日志尾部打出来方便定位 cd /opt/pdi-ce-9.5.0.1-261/data-integration ./pan.sh -file/data/etl/ktr/daily_load.ktr -levelBasic \ -logfile/data/etl/logs/daily_load.log RC$? if [ $RC -ne 0 ]; then echo 跑批失败退出码 $RC日志尾部 tail -n 50 /data/etl/logs/daily_load.log exit $RC fi这里有个容易翻车的地方转换里如果某个步骤失败但你把它的「错误处理」接到了一个「空操作」步骤上那么这一步的失败会被吞掉整条转换最后仍然返回 0。所以要么别接错误处理要么在错误处理分支里显式让作业失败。日志级别和退出码的关系也要说一句-levelNothing虽然能让日志文件极小但失败时你什么都看不到排查成本远高于省下来的那点磁盘。我的习惯是常年Basic只有在跑批量特别大、日志量成为负担时才降到Minimal。5. 排查清单macOS 上跑 Kettle 9.5 最容易翻的五次车这一章全是现象、原因、解决的三段式都是实际遇到过、并且每次都要重新想一遍的问题。按启动阶段和运行阶段分开列方便对号入座。5.1 启动阶段Java、架构与路径现象一双击或执行./spoon.sh后终端刷几行就退出没有任何窗口也没有明显的错误提示。原因JAVA_HOME指向的 JDK 版本不被 Kettle 9.5 支持。这个版本线认的是 Java 8 和 Java 11macOS 上如果用包管理器装了更新的 JDK 并设成了默认spoon.sh会在启动器那一层就失败错误信息被吞在启动器的日志里终端上看到的可能只有一行无关紧要的提示。判断方法是直接在终端敲java -version看输出的是不是 1.8 或 11。解决用/usr/libexec/java_home -V列出所有已装 JDK找到 1.8 或 11 的路径显式export JAVA_HOME后再启动。要长期生效就写进 shell 配置文件或者写进spoon.sh顶部。如果机器上压根没有 8 或 11那就得先装一个这一步绕不过去。现象二Apple Silicon 机器上 Spoon 窗口能出来但界面组件全是空白方块或者启动瞬间崩溃终端里出现UnsatisfiedLinkError提到libswt或.jnilib。原因libswt目录下的原生库是 x86_64 架构的而 arm64 的 JVM 没法加载它。Spoon 的整个界面基于 SWTSWT 必须加载对应平台的原生库架构对不上就直接失败。这是个架构层面的问题不是配置能绕过去的。解决让 Spoon 跑在 x86_64 的 JDK 上通过系统的转译层执行。也就是说JAVA_HOME要指向 x86_64 版本的 JDK 8 或 11而不是 arm64 版本。装完用/usr/libexec/java_home -V确认输出里标的架构选对了再启动。命令行跑批pan/kitchen如果不需要图形界面可以不受这个限制但保险起见还是统一用同一个 JDK。现象三把解压目录放在「下载」或者带中文、带空格的路径下启动时报找不到某个 jar或者 classpath 里出现半截路径。原因spoon.sh里拼 classpath 的时候对空格和特殊字符的处理不够健壮路径里一旦有空格classpath 就会被从空格处截断后面的 jar 全部丢失。中文路径在某些编码环境下表现更糟。解决把整个># 把 UTF-8 BOM 去掉覆盖写回原文件注意先备份 sed -i 1s/^\xEF\xBB\xBF// /data/etl/raw/daily.csv # 确认文件头三个字节不再是 BOM head -c 3 /data/etl/raw/daily.csv | xxdsed那条里的-i 是 macOS 版 BSD sed 的写法和 Linux 上不一样直接抄 Linux 的命令会报错。第二条命令用来验证如果输出的十六进制里没有efbbbf就说明处理干净了。现象五转换在 Spoon 里跑得好好的用 pan 跑批时连接报错提示找不到驱动或者连不上库。原因有几种可能按出现频率排。最常见的是转换里用了共享连接而共享连接存在~/.kettle/shared.xml里跑批的那台机器或者那个用户下面根本没有这个文件。第二种是驱动 jar 放在了安装目录的lib下但跑批时用的是另一个安装目录。第三种是连接密码用了变量引用而跑批时没有把对应的变量传进去或写进kettle.properties。解决第一步看日志里报的具体异常如果是驱动类找不到检查lib目录和 jar 是否只留了一个版本如果是连接为空把共享连接改成转换内的本地连接让配置跟着.ktr文件走如果是认证失败把密码相关的变量在跑批命令里补上-param:或者确认跑批用户主目录下的kettle.properties里有对应条目。改完之后先用-levelDetailed跑一次确认连接建立那一段日志正常再改回Basic。6. 把转换搬到 Carte 上远程执行与调度前的验证手法前面所有内容都是单机跑批。当跑批任务多到一台机器排不开、或者需要从另一个系统远程触发时就要用上 carte 了。它本质是一个常驻的 HTTP 服务把你写好的.ktr和.kjb挂在上面通过 URL 触发执行。这块不算复杂但验证手法有讲究我一般按下面这个顺序走一遍再交给调度。第一步是把 carte 起起来验证服务本身活着# 前台启动 carte监听所有网卡的 8080 端口CtrlC 停止 cd /opt/pdi-ce-9.5.0.1-261/data-integration ./carte.sh 0.0.0.0 8080启动日志里会打出服务地址和默认的集群账号。默认端口是 8080如果和机器上其他服务冲突换成 8081 之类的即可。前台跑起来确认没问题之后再考虑用系统的服务管理方式托管到后台。第二步是验证服务能正常响应# 查服务状态返回内容里能看到当前挂载的转换和作业列表 curl -s http://127.0.0.1:8080/kettle/status/ | head -n 20第三步才是真正触发一次执行# 通过 HTTP 触发一个转换指定日志级别 curl -s http://127.0.0.1:8080/kettle/runTrans/?trans/data/etl/ktr/daily_load.ktrlevelBasic这里有三个地方值得注意。一是trans参数里给的是carte 进程所在机器上的路径不是你本地机器的路径两边目录结构不一致时最容易错。二是路径里如果带空格或中文要先做 URL 编码否则参数会被截断。三是这个接口是异步的请求返回成功只代表任务被接收了不代表跑完了真正的结果要去/kettle/status/里看或者看日志。调度前的验证我一般会做一张小表逐项打勾验证项做法不通过的表现服务可达curl 打 status 接口连接被拒或超时路径正确用绝对路径触发一次返回找不到文件的错误参数生效故意传一个非法日期看是否报错不报错说明参数没进去日志落盘触发后查 carte 的日志目录只有控制台输出没有文件失败可感知人为让一步失败看退出状态失败但状态仍显示成功最后一项是最容易被忽略的。carte 是常驻进程它的「成功/失败」状态不体现在进程退出码上而是体现在任务状态里。如果你的调度系统只看 HTTP 返回码那么任务内部失败它感知不到。稳妥的做法是在作业末尾加一个「检查上一步结果」的环节或者干脆让调度系统去轮询/kettle/status/里的任务状态字段而不是只看请求是否发出。注意carte 默认账号是公开的生产环境一定要改掉并且不要直接监听在公网地址上。这一条没有例外。从那以后我每次把转换搬上 carte 之前都会先手动触发一次故意失败的任务确认失败能被感知到再触发正常的。这个习惯是从一次「跑了三天才发现每天都是空跑」的教训里来的代价有点大。远程执行最怕的不是跑不起来而是跑起来了、看起来成功了、数据其实是空的。希望帮到你。本文还有配套的精品资源点击获取