Kettle 9.1 配置参数详解

目标：系统梳理 Pentaho Data Integration（Kettle，下称 PDI）9.1 社区版的配置体系：环境变量（JAVA_HOME、PENTAHO_DI_JAVA_OPTIONS、KETTLE_HOME）、kettle.properties 变量文件的加载机制与替换实证、Carte 配置文件各键含义、日志级别参数，以及 TextFileOutput 输出文件名的配置陷阱。全部配置项均给出实测验证方法与回显。实测环境为 CentOS 8（x86_64），PDI 9.1.0.0-324 安装于 /opt/pentaho/data-integration，JDK 8。

一、配置体系总览

PDI 9.1 的配置分四层，作用范围与优先级从高到低：

层	载体	典型内容	作用范围
命令行参数	kitchen.sh/pan.sh/carte.sh 的 `-参数`	-file、-level、-param、-logfile	当次执行
Carte 配置文件	carte-master.xml / carte-slave.xml 等自定义 XML	监听地址、端口、账号、主从关系	对应 Carte 实例
kettle.properties	~/.kettle/kettle.properties 或 $KETTLE_HOME/.kettle/kettle.properties	Kettle 变量（KETTLE_LOG_LEVEL、自定义变量等）	所有 Kettle 进程
环境变量	/etc/profile.d/*.sh 或 shell export	JAVA_HOME、PENTAHO_DI_JAVA_OPTIONS、KETTLE_HOME、PATH	服务器全局

命令行参数优先级最高（覆盖同义的变量与环境配置）；kettle.properties 在每个 Kettle 进程启动时加载一次；环境变量是 JVM 与启动脚本层的输入。

二、环境变量详解

2.1 JAVA_HOME

PDI 启动脚本（kitchen.sh/pan.sh/carte.sh/spoon.sh 共用框架）依赖 JVM，建议显式指定 JAVA_HOME 为 JDK 8 路径（PDI 9.1 不兼容 JDK 11+，原因见第七节 7.3）：

readlink -f $(which java)

实测输出：

/usr/lib/jvm/jre-1.8.0/jre/bin/java

据此在 /etc/profile.d/pdi.sh 中固化：

export JAVA_HOME=/usr/lib/jvm/jre-1.8.0

2.2 PENTAHO_DI_JAVA_OPTIONS（JVM 堆内存）

这是 PDI 启动脚本读取的专用 JVM 参数变量，对小内存服务器应将堆限制在 256–512 MB：

export PENTAHO_DI_JAVA_OPTIONS="-Xms256m -Xmx512m"

生效验证：启动任一常驻或执行中的 PDI 进程后，从进程命令行确认实际生效值。以两个 Carte 实例为例：

ps -ef | grep [j]ava | grep -o "Xms[0-9]*m -Xmx[0-9]*m"

实测输出：

Xms256m -Xmx512m
Xms256m -Xmx512m

若需进一步收紧，将两值对齐为 -Xms256m -Xmx256m。systemd 托管场景下，在 unit 文件中用 Environment= 注入同名变量（每行仅一个单元一个变量）：

Environment="PENTAHO_DI_JAVA_OPTIONS=-Xms256m -Xmx512m"

unit 内注入的值优先于 profile 文件，修改后 systemctl daemon-reload 并重启对应单元生效。

2.3 KETTLE_HOME

KETTLE_HOME 重定向 kettle.properties 的查找根目录。设置后，PDI 到 $KETTLE_HOME/.kettle/kettle.properties（而不是 ~/.kettle/kettle.properties）读取变量。

实测：准备一个替代主目录并定义同名变量：

mkdir -p /opt/pentaho/kettle-home/.kettle
printf 'KETTLE_LOG_LEVEL=Debug\nMY_TEST_VAR=hello-from-kettle-home\n' > /opt/pentaho/kettle-home/.kettle/kettle.properties
export KETTLE_HOME=/opt/pentaho/kettle-home

在该环境下执行引用 ${MY_TEST_VAR} 的转换（转换文件见 3.2），文件成功落盘为 /tmp/out-hello-from-kettle-home.txt.txt，变量值来自 KETTLE_HOME 指定目录中的 kettle.properties，说明加载路径已重定向。

💡 说明：不设置 KETTLE_HOME 时，默认读取 ~/.kettle/kettle.properties，两处机制一致。

2.4 PATH 与全局固化

将程序目录加入 PATH 便于直接调用 kitchen/pan/carte：

export PATH=$PATH:/opt/pentaho/data-integration

以上三个变量统一写入 /etc/profile.d/pdi.sh 全局固化：

cat > /etc/profile.d/pdi.sh <<'EOF'
export JAVA_HOME=/usr/lib/jvm/jre-1.8.0
export PENTAHO_DI_JAVA_OPTIONS="-Xms256m -Xmx512m"
export PATH=$PATH:/opt/pentaho/data-integration
EOF
source /etc/profile.d/pdi.sh

三、kettle.properties 变量

3.1 位置与加载机制

默认位置为当前用户主目录下的 ~/.kettle/kettle.properties，每个 Kettle 进程（kitchen/pan/carte/Spoon）启动时加载一次，文件中的每个键值对注册为一个 Kettle 变量，可在转换/作业中用 ${变量名} 引用。设置 KETTLE_HOME 后查找位置改为 $KETTLE_HOME/.kettle/kettle.properties（见 2.3）。

写入示例：

mkdir -p ~/.kettle
printf 'KETTLE_LOG_LEVEL=Debug\nMY_TEST_VAR=hello-from-kettle-home\n' > ~/.kettle/kettle.properties

3.2 变量替换实证

构造一个引用变量的转换：RowGenerator 生成 1 行数据 → TextFileOutput 写文件，输出文件名引用 ${MY_TEST_VAR}。转换文件 test_var_file.ktr 全文：

<?xml version="1.0" encoding="UTF-8"?>
<transformation>
  <info>
    <name>var_file_test</name>
    <trans_type>Normal</trans_type>
    <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>
  </info>
  <order>
    <hop><from>gen</from><to>txt</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>var-file-test</nullif><length>-1</length><precision>-1</precision><set_empty_string>N</set_empty_string></field>
    </fields>
    <limit>1</limit>
    <never_ending>N</never_ending>
    <cluster_schema/>
    <GUI><xloc>100</xloc><yloc>100</yloc><draw>Y</draw></GUI>
  </step>
  <step>
    <name>txt</name>
    <type>TextFileOutput</type>
    <distribute>Y</distribute>
    <copies>1</copies>
    <partitioning><method>none</method><schema_name/></partitioning>
    <separator>;</separator>
    <enclosure>&quot;</enclosure>
    <enclosure_forced>N</enclosure_forced>
    <enclosure_fix_disabled>N</enclosure_fix_disabled>
    <header>N</header>
    <footer>N</footer>
    <format>DOS</format>
    <compression>None</compression>
    <encoding>UTF-8</encoding>
    <endedLine/>
    <fileName>/tmp/out-${MY_TEST_VAR}.txt</fileName>
    <file>
      <name>/tmp/out-${MY_TEST_VAR}.txt</name>
      <extention>txt</extention>
      <append>N</append>
      <split>N</split>
      <haspartno>N</haspartno>
      <add_date>N</add_date>
      <add_time>N</add_time>
      <SpecifyFormat>N</SpecifyFormat>
      <date_time_format/>
      <add_to_result>N</add_to_result>
      <pad>N</pad>
      <fast_dump>N</fast_dump>
      <splitevery>0</splitevery>
    </file>
    <fields/>
    <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>

执行（-norep 表示不登录资源库，文件模式下必加）：

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

验证输出文件名中的变量已被替换为 kettle.properties 里的值：

ls /tmp/out-*

实测输出：

/tmp/out-hello-from-kettle-home.txt.txt

文件名中的 hello-from-kettle-home 正是 ~/.kettle/kettle.properties 中 MY_TEST_VAR 的值，变量加载与替换链路实测打通（.txt.txt 双后缀是 TextFileOutput 自动追加扩展名的行为，见第六节）。

3.3 常用变量速查

变量	作用	本文取值
KETTLE_LOG_LEVEL	全局默认日志级别（级别取值见第五节 5.1）	Debug
自定义变量（如 MY_TEST_VAR）	在转换/作业中以 `${名称}` 引用	hello-from-kettle-home

四、Carte 配置文件键详解

Carte 支持两种启动方式：命令行方式（carte.sh 接口地址端口，使用内置默认账号 cluster/cluster）与配置文件方式（carte.sh 配置.xml，账号与主从关系完全自定义）。配置文件为 XML，结构如下。

4.1 master 配置（/opt/pentaho/carte-master.xml）

<slave_config>
  <slaveserver>
    <name>master</name>
    <hostname>localhost</hostname>
    <port>8081</port>
    <username>admin</username>
    <password>q1w2e3r4</password>
    <master>Y</master>
  </slaveserver>
</slave_config>

4.2 slave 配置（/opt/pentaho/carte-slave.xml）

<slave_config>
  <slaveserver>
    <name>slave1</name>
    <hostname>localhost</hostname>
    <port>8082</port>
    <username>admin</username>
    <password>q1w2e3r4</password>
    <master>N</master>
  </slaveserver>
  <report_to_masters>Y</report_to_masters>
  <masters>
    <slaveserver>
      <name>master</name>
      <hostname>localhost</hostname>
      <port>8081</port>
      <username>admin</username>
      <password>q1w2e3r4</password>
      <master>Y</master>
    </slaveserver>
  </masters>
</slave_config>

4.3 配置键说明

键	层级	说明
name	slaveserver	节点名称，注册与调度时用于识别
hostname	slaveserver	监听地址；对端可达的 IP/主机名
port	slaveserver	Web 服务监听端口
username / password	slaveserver	访问本节点接口的凭据（配置文件方式生效；命令行方式固定为 cluster/cluster）
master	slaveserver	Y 为主节点，N 为子节点
report_to_masters	根	Y 时启动后向 masters 列表注册并保持心跳
masters	根	主节点清单；其 username/password 必须与对端 slaveserver 声明一致，否则注册返回 401

配置文件方式启动：

/opt/pentaho/data-integration/carte.sh /opt/pentaho/carte-master.xml

实测输出（尾部，启动约 15–25 秒）：

2026/10/12 14:27:34 - Carte - Installing timer to purge stale objects after 1440 minutes.
2026/10/12 14:27:35 - Carte - Created listener for webserver @ address : localhost:8081

五、日志级别与日志参数

5.1 -level 日志级别

kitchen.sh 与 pan.sh 共用同一组日志级别（-level 参数，七档）：

级别	说明
Nothing	不输出日志
Error	仅错误
Minimal	仅关键信息
Basic	基本执行信息（默认常用档位）
Detailed	详细信息
Debug	调试信息
Rowlevel	每行数据的处理细节（数据量最大）

用法与实测（Basic 级别下日志文件开头两行）：

kitchen.sh -file=/opt/pentaho/test_gen_log_job.kjb -level=Basic -logfile=/tmp/kitchen-test.log
head -2 /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.

5.2 KETTLE_LOG_LEVEL

kettle.properties 中的全局默认级别（3.3 节示例设为 Debug）。命令行 -level 显式指定时优先于该变量。

5.3 内存中日志缓冲参数

kitchen/pan 均支持两个日志缓冲参数（Usage 原文默认值）：

参数	默认	说明
-maxloglines	0	内部保留的最大日志行数，0 表示全部保留
-maxlogtimeout	0	日志行在内存中的最长保留时间（分钟），0 表示不过期

六、TextFileOutput 输出文件名配置陷阱

TextFileOutput 步骤的输出路径必须写在 <file> 节点的 <name> 子键中；只写顶层 <fileName> 不生效（实测报 Output filename not set，文件不会生成）。

错误写法（仅顶层 fileName，实测不生成文件）：

    <fileName>/tmp/out.txt</fileName>

正确写法（<file><name> 指定路径，<extention> 指定扩展名；注意 extention 是该步骤 XML 的历史拼写，照此使用）：

    <file>
      <name>/tmp/out-${MY_TEST_VAR}.txt</name>
      <extention>txt</extention>
    </file>

采用正确写法后，实测生成 /tmp/out-hello-from-kettle-home.txt.txt：文件名主体含变量替换结果，末尾的 .txt 来自 <extention> 自动追加，属正常行为。若希望文件名严格等于 <name> 的值，把 <extention> 留空即可。

七、常见问题

7.1 变量输出为变量名字面量

现象：转换结果中出现 ${MY_TEST_VAR} 或变量名字面量，而非期望值。排查顺序：

确认 kettle.properties 位置：未设 KETTLE_HOME 时应在 ~/.kettle/kettle.properties（注意运行账号的主目录）；
确认键值格式：每行 键=值，无引号、无 export 前缀（它是 properties 文件，不是 shell 脚本）；
kettle.properties 是进程启动时加载的，修改后需重启对应 kitchen/pan/carte 进程；
判断技巧：GetVariable 等步骤在变量缺失时会原样输出变量名字面量，看到字面量即可断定变量未被加载。

7.2 KETTLE_HOME 设置后变量"丢失"

设置 KETTLE_HOME 后读取路径变为 $KETTLE_HOME/.kettle/kettle.properties，原 ~/.kettle/ 下的定义不再生效。将 kettle.properties 复制或软链到新位置即可：

mkdir -p $KETTLE_HOME/.kettle
cp ~/.kettle/kettle.properties $KETTLE_HOME/.kettle/

7.3 JVM 参数未生效或启动报 endorsed dirs 错误

现象一：进程实际堆与预期不符——用 ps -ef | grep [j]ava | grep -o "Xms[0-9]*m -Xmx[0-9]*m" 复核（见 2.2），systemd 场景确认 unit 中 Environment= 已注入并 daemon-reload 后重启。

现象二（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+ 已移除该机制。解决：统一使用 JDK 8（java -version 复核默认 JDK），JAVA_HOME 指向 JDK 8 路径。

八、参考链接

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
Oracle JDK 8 工具参考（-Xms/-Xmx 语义）：https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html