Kettle 9.1 Kitchen 与 Pan 命令详解

目标：详解 Pentaho Data Integration（Kettle，下称 PDI）9.1 社区版的两个命令行执行器——Kitchen（作业执行器 kitchen.sh）与 Pan（转换执行器 pan.sh）：完整 Options 参数表、文件模式执行实测、日志文件输出、列表类参数行为、-version 的真实表现，以及退出日志的逐行解读。全部命令与回显已在 CentOS 8（x86_64）实测通过（PDI 9.1.0.0-324 安装于 /opt/pentaho/data-integration，JDK 8）。

一、定位与运行方式

工具	脚本	执行对象	典型用途
Kitchen	kitchen.sh	作业（.kjb）	定时 ETL 主流程、带成功/失败分支的编排
Pan	pan.sh	转换（.ktr）	单个转换的批处理执行、调试

两者均为无界面执行器（对应图形设计器 Spoon 中设计的作业/转换），共用同一套脚本框架与 JVM 参数变量 PENTAHO_DI_JAVA_OPTIONS，仅参数集不同。前置要求：JDK 8（PDI 9.1 启动脚本与 JDK 11+ 不兼容，见第五节 5.1）。

💡 说明：执行环境变量建议先固化到 /etc/profile.d/pdi.sh：JAVA_HOME 指向 JDK 8 路径、PENTAHO_DI_JAVA_OPTIONS="-Xms256m -Xmx512m"、PATH 追加 /opt/pentaho/data-integration。

本文使用两个测试文件（全文见 2.1 的作业文件与 3.1 前置的转换文件）：作业 test_gen_log_job.kjb（START → 执行转换），转换 test_gen_log.ktr（RowGenerator 生成 3 行 → WriteToLog 打印）。

二、Kitchen 命令详解

2.1 语法与 Options 全表

无参运行打印全部选项（实测）：

kitchen.sh

实测输出：

#######################################################################
WARNING:  no libwebkitgtk-1.0 detected, some features will be unavailable
    Consider installing the package with apt-get or yum.
    e.g. 'sudo apt-get install libwebkitgtk-1.0-0'
#######################################################################
Options:
  -rep            = Repository name
  -user           = Repository username
  -trustuser      = !Kitchen.ComdLine.RepUsername!
  -pass           = Repository password
  -job            = The name of the job to launch
  -dir            = The directory (dont forget the leading /)
  -file           = The filename (Job XML) to launch
  -level          = The logging level (Basic, Detailed, Debug, Rowlevel, Error, Minimal, Nothing)
  -logfile        = The logging file to write to
  -listdir        = List the directories in the repository
  -listjobs       = List the jobs in the specified directory
  -listrep        = List the available repositories
  -norep          = Do not log into the repository
  -version        = show the version, revision and build date
  -param          = Set a named parameter <NAME>=<VALUE>. For example -param:FILE=customers.csv
  -listparam      = List information concerning the defined parameters in the specified job.
  -export         = Exports all linked resources of the specified job. The argument is the name of a ZIP file.
  -custom         = Set a custom plugin specific option as a String value in the job using <NAME>=<Value>, for example: -custom:COLOR=Red
  -maxloglines    = The maximum number of log lines that are kept internally by Kettle. Set to 0 to keep all rows (default)
  -maxlogtimeout  = The maximum age (in minutes) of a log line while being kept internally by Kettle. Set to 0 to keep all rows indefinitely (default)

（开头的 libwebkitgtk 警告仅影响 GUI 相关功能，命令行执行可忽略，见第五节 5.2。）

参数按用途分组：

分组	参数	说明
执行对象（二选一）	-file / -job+-dir	-file 直接指定作业 XML 文件路径；-job+-dir 指定资源库中的作业
资源库	-rep/-user/-pass/-trustuser/-norep	资源库名、账号、密码、信任账号；文件模式必须加 -norep
日志	-level/-logfile	日志级别七档；日志落盘路径
参数传递	-param/-custom	向作业注入命名参数/插件自定义参数
列表查询	-listrep/-listdir/-listjobs/-listparam	列出资源库、目录、作业、参数定义
导出	-export	将作业的关联资源导出为 ZIP
其他	-version/-maxloglines/-maxlogtimeout	版本显示、内存日志缓冲控制（默认均为 0，即全保留）

2.2 文件模式执行作业（实测）

先准备作业与转换文件。转换 /opt/pentaho/test_gen_log.ktr：

<?xml version="1.0" encoding="UTF-8"?>
<transformation>
  <info>
    <name>gen_log_test</name>
    <trans_type>Normal</trans_type>
    <directory>/</directory>
    <size_rowset>10000</size_rowset>
    <created_user>-</created_user>
    <created_date>2026/10/12 12:00:00.000</created_date>
    <modified_user>-</modified_user>
    <modified_date>2026/10/12 12:00:00.000</modified_date>
  </info>
  <order>
    <hop><from>gen</from><to>log</to><enabled>Y</enabled></hop>
  </order>
  <notepads></notepads>
  <step>
    <name>gen</name>
    <type>RowGenerator</type>
    <distribute>Y</distribute>
    <copies>1</copies>
    <partitioning><method>none</method><schema_name/></partitioning>
    <fields>
      <field>
        <name>msg</name>
        <type>String</type>
        <nullif>hello-kettle</nullif>
        <length>-1</length>
        <precision>-1</precision>
        <set_empty_string>N</set_empty_string>
      </field>
    </fields>
    <limit>3</limit>
    <never_ending>N</never_ending>
    <cluster_schema/>
    <GUI><xloc>100</xloc><yloc>100</yloc><draw>Y</draw></GUI>
  </step>
  <step>
    <name>log</name>
    <type>WriteToLog</type>
    <distribute>Y</distribute>
    <copies>1</copies>
    <partitioning><method>none</method><schema_name/></partitioning>
    <log_level>log_level_basic</log_level>
    <displayHeader>Y</displayHeader>
    <limitRows>N</limitRows>
    <limitRowsNumber>0</limitRowsNumber>
    <logmessage>msg</logmessage>
    <byname>Y</byname>
    <cluster_schema/>
    <GUI><xloc>300</xloc><yloc>100</yloc><draw>Y</draw></GUI>
  </step>
  <step_error_handling></step_error_handling>
  <slave_transformation>N</slave_transformation>
  <attributes/>
</transformation>

作业 /opt/pentaho/test_gen_log_job.kjb（START 入口 → TRANS 条目引用上面的转换）：

<?xml version="1.0" encoding="UTF-8"?>
<job>
  <name>run_ktr_job</name>
  <directory>/</directory>
  <created_user>-</created_user>
  <created_date>2026/10/12 12:00:00.000</created_date>
  <modified_user>-</modified_user>
  <modified_date>2026/10/12 12:00:00.000</modified_date>
  <parameters></parameters>
  <slaveservers></slaveservers>
  <entries>
    <entry>
      <name>START</name>
      <type>SPECIAL</type>
      <start>Y</start>
      <dummy>N</dummy>
      <repeat>N</repeat>
      <schedulerType>0</schedulerType>
      <intervalSeconds>60</intervalSeconds>
      <intervalMinutes>60</intervalMinutes>
      <hour>12</hour>
      <minutes>0</minutes>
      <weekDay>1</weekDay>
      <DayOfMonth>1</DayOfMonth>
      <parallel>N</parallel>
      <draw>Y</draw>
      <nr>0</nr>
      <xloc>100</xloc>
      <yloc>100</yloc>
    </entry>
    <entry>
      <name>run trans</name>
      <type>TRANS</type>
      <filename>/opt/pentaho/test_gen_log.ktr</filename>
      <arg_from_previous>N</arg_from_previous>
      <exec_local>Y</exec_local>
      <exec_remote>N</exec_remote>
      <clear_rows>N</clear_rows>
      <wait_until_finished>Y</wait_until_finished>
      <parameters><pass_all_parameters>Y</pass_all_parameters></parameters>
      <parallel>N</parallel>
      <draw>Y</draw>
      <nr>0</nr>
      <xloc>300</xloc>
      <yloc>100</yloc>
    </entry>
  </entries>
  <hops>
    <hop>
      <from>START</from><to>run trans</to>
      <from_nr>0</from_nr><to_nr>0</to_nr><nr>0</nr>
      <enabled>Y</enabled><evaluation>Y</evaluation><unconditional>N</unconditional>
    </hop>
  </hops>
  <notepads></notepads>
</job>

执行作业：

kitchen.sh -file=/opt/pentaho/test_gen_log_job.kjb -level=Basic -norep

实测输出（尾部；开头的 Karaf/OSGI 初始化日志略）：

14:26:51,865 INFO  [KarafBoot] Checking to see if org.pentaho.clean.karaf.cache is enabled
（Karaf/OSGI 初始化日志略）
2026/10/12 12:14:30 - run_ktr_job - Start of job execution
2026/10/12 12:14:30 - run_ktr_job - Job execution finished
2026/10/12 12:14:30 - Carte - Installing timer to purge stale objects after 1440 minutes.
2026/10/12 12:14:30 - Finished!
2026/10/12 12:14:30 - Start=2026/10/12 12:14:30.058, Stop=2026/10/12 12:14:30.108
2026/10/12 12:14:30 - Processing ended after 0 seconds.

Start of job execution → Job execution finished → Finished! 三行齐备即作业成功（本作业内嵌转换在 Basic 级别不逐步打印行数据，转换明细可用 pan 单独执行验证，见 3.2）。

2.3 -logfile 日志落盘（实测）

kitchen.sh -file=/opt/pentaho/test_gen_log_job.kjb -level=Basic -logfile=/tmp/kitchen-test.log

控制台仍输出执行摘要；日志完整写入 /tmp/kitchen-test.log：

head -2 /tmp/kitchen-test.log
tail -5 /tmp/kitchen-test.log

实测输出：

2026/10/12 14:25:08 - Kitchen - Logging is at level : Basic
2026/10/12 14:25:08 - Kitchen - Start of run.
2026/10/12 14:25:21 - run_ktr_job - Job execution finished
2026/10/12 14:25:21 - Carte - Installing timer to purge stale objects after 1440 minutes.
2026/10/12 14:25:21 - Finished!
2026/10/12 14:25:21 - Start=2026/10/12 14:25:21.610, Stop=2026/10/12 14:25:21.675
2026/10/12 14:25:21 - Processing ended after 0 seconds.

定时任务场景建议固定 -level=Basic -logfile=/var/log/pdi/kitchen-$(date +\%Y\%m\%d).log 式落盘，便于回溯（crontab 中 % 需转义为 \%）。

2.4 列表类参数实测

无资源库环境下 -listrep 的行为：

kitchen.sh -listrep

实测输出（尾部）：

2026/10/12 14:25:33 - Kitchen - Start of run.
List of repositories:

其后为空列表（未配置任何资源库时）。-listparam 对未定义参数的作业不输出参数行（实测仅初始化日志）：

kitchen.sh -file=/opt/pentaho/test_gen_log_job.kjb -listparam

若作业在 <parameters> 中定义了命名参数，此处会逐行列出参数名、默认值与描述，并用 -param:NAME=value（或 -param NAME=value）注入。

2.5 -version 的真实行为（实测）

kitchen.sh -version

实测输出：

2026/10/12 12:12:40 - Kitchen - Kettle version 9.1.0.0-324, build 9.1.0.0-324, build date : 2020-09-07 05.09.05
2026/10/12 12:12:40 - Kitchen - Start of run.
ERROR: Kitchen can't continue because the job couldn't be loaded.

⚠️ 注意：单独传 -version 会打印版本行，但 Kitchen 随后仍按正常流程加载作业，因未指定作业而报 ERROR: Kitchen can't continue because the job couldn't be loaded. 并退出（exit 非零）。这是 9.1 的实际行为：不要把 kitchen.sh -version 用在脚本健康检查里。

查看版本的推荐方式：任取一条实际执行命令的首行日志（2.2/3.2 输出均含 Kettle version 9.1.0.0-324, build 9.1.0.0-324, build date : 2020-09-07 05.09.05），或直接确认核心 jar：

ls /opt/pentaho/data-integration/lib | grep kettle-core

实测输出：

kettle-core-9.1.0.0-324.jar

三、Pan 命令详解

3.1 语法与 Options 全表

pan.sh

实测输出：

#######################################################################
WARNING:  no libwebkitgtk-1.0 detected, some features will be unavailable
    Consider installing the package with apt-get or yum.
    e.g. 'sudo apt-get install libwebkitgtk-1.0-0'
#######################################################################
Options:
  -rep            = Repository name
  -user           = Repository username
  -trustuser      = Repository username
  -pass           = Repository password
  -trans          = The name of the transformation to launch
  -dir            = The directory (dont forget the leading /)
  -file           = The filename (Transformation in XML) to launch
  -level          = The logging level (Basic, Detailed, Debug, Rowlevel, Error, Minimal, Nothing)
  -logfile        = The logging file to write to
  -listdir        = List the directories in the repository
  -listtrans      = List the transformations in the specified directory
  -listrep        = List the available repositories
  -exprep         = Export all repository objects to one XML file
  -norep          = Do not log into the repository
  -safemode       = Run in safe mode: with extra checking enabled
  -version        = show the version, revision and build date
  -param          = Set a named parameter <NAME>=<VALUE>. For example -param:FOO=bar
  -listparam      = List information concerning the defined named parameters in the specified transformation.
  -metrics        = Gather metrics during execution
  -maxloglines    = The maximum number of log lines that are kept internally by Kettle. Set to 0 to keep all rows (default)
  -maxlogtimeout  = The maximum age (in minutes) of a log line while being kept internally by Kettle. Set to 0 to keep all rows indefinitely (default)

与 Kitchen 的差异：执行对象为 -file 或 -trans+-dir（转换），并多出 -safemode（启用额外检查的安全模式）与 -metrics（执行期间采集度量指标）；列表查询为 -listtrans（转换清单）。

3.2 文件模式执行转换（实测）

pan.sh -file=/opt/pentaho/test_gen_log.ktr -level=Basic -norep

实测输出（尾部；开头的 libwebkitgtk 警告与 Karaf/OSGI 初始化日志略）：

2026/10/12 12:14:06 - log.0 - msg = hello-kettle
2026/10/12 12:14:06 - log.0 - ------------> Linenr 3------------------------------
2026/10/12 12:14:06 - log.0 - ====================
2026/10/12 12:14:06 - log.0 - Finished processing (I=0, O=0, R=3, W=3, U=0, E=0)
2026/10/12 12:14:06 - Carte - Installing timer to purge stale objects after 1440 minutes.
2026/10/12 12:14:06 - Finished!
2026/10/12 12:14:06 - Start=2026/10/12 12:14:06.259, Stop=2026/10/12 12:14:06.313
2026/10/12 12:14:06 - Processing ended after 0 seconds.
2026/10/12 12:14:06 - gen_log_test -
2026/10/12 12:14:06 - gen_log_test - Step gen.0 ended successfully, processed 3 lines. ( - lines/s)
2026/10/12 12:14:06 - gen_log_test - Step log.0 ended successfully, processed 3 lines. ( - lines/s)

关键行解读：

输出行	含义
`log.0 - msg = hello-kettle`	WriteToLog 步骤打印字段值（行号 1/2 行同格式，节选）
`Finished processing (I=0, O=0, R=3, W=3, U=0, E=0)`	步骤统计：I 输入/O 输出/R 读取/W 写入/U 更新/E 错误
`Step gen.0 ended successfully, processed 3 lines.`	生成步骤处理 3 行，与 `<limit>3</limit>` 一致
`Start=2026/10/12 12:14:06.259, Stop=2026/10/12 12:14:06.313` / `Processing ended after 0 seconds.`	起止时间与耗时

同一转换在 Ubuntu 22.04 上以相同命令执行亦通过（Finished processing (I=0, O=0, R=0, W=3, U=0, E=0) 与 Finished!），命令行为跨发行版一致。

3.3 -logfile 与 -version（实测）

pan.sh -file=/opt/pentaho/test_gen_log.ktr -level=Basic -logfile=/tmp/pan-test.log
tail -4 /tmp/pan-test.log

实测输出：

2026/10/12 14:25:51 - Processing ended after 0 seconds.
2026/10/12 14:25:51 - gen_log_test -
2026/10/12 14:25:51 - gen_log_test - Step gen.0 ended successfully, processed 3 lines. ( - lines/s)
2026/10/12 14:25:51 - gen_log_test - Step log.0 ended successfully, processed 3 lines. ( - lines/s)

pan.sh -version

实测输出：

2026/10/12 14:27:16 - Kettle version 9.1.0.0-324, build 9.1.0.0-324, build date : 2020-09-07 05.09.05
ERROR: No repository provided, can't load transformation.

与 Kitchen 同理：-version 打印版本行后继续加载流程，因缺转换而报 ERROR: No repository provided, can't load transformation. 退出，勿用于健康检查。

四、退出行为与脚本化要点

成功标志：日志出现 Finished! 与 Processing ended after N seconds.，进程退出码为 0。
失败时：日志出现 ERROR: 行（如作业加载失败、转换路径不存在），退出码非 0，脚本中应以退出码为准做分支。
文件模式必带 -norep，避免启动时尝试登录资源库。
日志双轨：控制台摘要 + -logfile 全量落盘，可同时使用；-level 同时作用于两路。

五、常见问题

5.1 启动脚本报 -Djava.endorsed.dirs 不支持（JDK 11+）

现象：

-Djava.endorsed.dirs=... is not supported. Endorsed standards and standalone APIs
in modular form will be supported via the concept of upgradeable modules.
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

原因：PDI 9.1 启动脚本固定拼接非空 -Djava.endorsed.dirs，JDK 9+ 已移除该机制。解决：kitchen/pan 统一使用 JDK 8，java -version 复核默认 JDK，必要时在脚本前显式 export JAVA_HOME=/usr/lib/jvm/jre-1.8.0。

5.2 启动时 libwebkitgtk 警告

现象（每次启动均打印，不影响命令行执行）：

#######################################################################
WARNING:  no libwebkitgtk-1.0 detected, some features will be unavailable
    Consider installing the package with apt-get or yum.
    e.g. 'sudo apt-get install libwebkitgtk-1.0-0'
#######################################################################

说明：该库仅服务 Spoon 图形界面中的部分预览功能（如内置浏览器组件），kitchen/pan 批处理完全不受影响，可忽略；CentOS 8 的软件源已不再提供 libwebkitgtk-1.0，无需强行安装。

5.3 作业内引用的转换找不到

现象：ERROR: Kitchen can't continue because the job couldn't be loaded. 或 TRANS 条目报文件不存在。排查：kjb 中 <filename> 必须是执行端可访问的绝对路径（本文为 /opt/pentaho/test_gen_log.ktr）；文件模式执行时确认路径存在且运行账号有读权限。

5.4 -version 用于健康检查误报

见 2.5/3.3：kitchen.sh -version / pan.sh -version 都会以非零退出码结束。健康检查改用真实执行一条最小作业/转换，或检查 kettle-core jar 文件名。

六、参考链接

Pentaho Data Integration 官方产品页：https://www.hitachivantara.com/en-us/products/data-management-analytics/pentaho-data-integration.html
Pentaho 9.1 官方文档中心：https://help.pentaho.com/Documentation/9.1
crontab 百分号转义说明（man 5 crontab）：https://man7.org/linux/man-pages/man5/crontab.5.html