Kettle 9.1 Carte 命令详解

详解 Kettle 9.1 Carte：Usage 与 -h 帮助全文、命令行与配置文件两种启动方式、默认凭据 cluster/cluster、status/getSlaves 接口回显、-s 停止机制与端口占用排障，全部含实测输出。

KettleKettleETL2026/10/12

Kettle 9.1 Carte 命令详解

目标：详解 Pentaho Data Integration（Kettle，下称 PDI）9.1 内嵌 Web 服务器 Carte（carte.sh）：命令行用法（Usage 与 -h 帮助全文）、「IP+端口」与「配置文件」两种启动方式、默认账号与鉴权实测、status 与 getSlaves 接口的 XML 回显、-s 停止机制，以及进程管理与端口占用排障。全部命令与回显已在 CentOS 8（x86_64）实测通过（PDI 9.1.0.0-324 安装于 /opt/pentaho/data-integration，JDK 8）。

一、Carte 定位与启动方式总览

Carte 是 PDI 内嵌的轻量 Web 服务器（基于 Jetty），承担两类职责：

  • 远程执行节点：通过 HTTP 接口注册并执行转换/作业（分布式的执行单元）；
  • 集群节点：以 master/slave 角色组成 PDI 集群，master 维护成员列表（getSlaves），slave 上报心跳。
启动方式命令形态监听账号适用场景
命令行方式carte.sh <接口地址> <端口>固定为内置默认账号 cluster/cluster单节点快速起服务、临时验证
配置文件方式carte.sh <配置.xml>配置文件中 username/password 自定义集群部署、自定义凭据

所有 HTTP 接口挂在 /kettle/ 上下文路径下，均需 Basic 认证。

💡 说明：运行前置——JDK 8 与 PENTAHO_DI_JAVA_OPTIONS 堆限制（本文实测环境 export PENTAHO_DI_JAVA_OPTIONS="-Xms256m -Xmx512m"）；JDK 11+ 会因启动脚本的 -Djava.endorsed.dirs 拒绝启动（见第八节 8.4）。

二、Usage 与帮助全文

2.1 无参 Usage

carte.sh

实测输出（全文）：

Usage: Carte <Interface address> <Port> [-h] [-p <arg>] [-s] [-u <arg>]
or
Usage: Carte <Configuration File>
Starts or stops the carte server.
Example: Carte 127.0.0.1 8080
Example: Carte 192.168.1.221 8081
Example: Carte /foo/bar/carte-config.xml
Example: Carte http://www.example.com/carte-config.xml
Example: Carte 127.0.0.1 8080 -s -u cluster -p cluster

2.2 -h 完整帮助

带参数形式加 -h 打印详细帮助（不会启动服务）：

carte.sh 127.0.0.1 8080 -h

实测输出（选项与示例部分）：

     -h,--help               This help text
     -p,--password <arg>     The administrator password.  Required only if
                             stopping the Carte server.
     -s,--stop               Stop the running carte server.  This is only
                             allowed when using the hostname/port form of the
                             command.
     -u,--userName <arg>     The administrator user name.  Required only if
                             stopping the Carte server.

Example: Carte 127.0.0.1 8080
Example: Carte 192.168.1.221 8081

Example: Carte /foo/bar/carte-config.xml
Example: Carte http://www.example.com/carte-config.xml
Example: Carte 127.0.0.1 8080 -s -u cluster -p cluster

参数含义（按帮助原文）：

参数含义
-h / --help打印帮助文本
-s / --stop停止正在运行的 Carte（仅限「接口地址 端口」命令形态）
-u / --userName管理员用户名，仅停止时需要
-p / --password管理员密码，仅停止时需要

即 Usage 示例 Carte 127.0.0.1 8080 -s -u cluster -p cluster 的含义是「用 cluster/cluster 凭据停止 8080 上的 Carte」，实测见第六节。

三、方式一：IP + 端口 启动（实测）

/opt/pentaho/data-integration/carte.sh 127.0.0.1 8083

实测输出（尾部；开头的 libwebkitgtk 警告、Karaf/OSGI 初始化日志约 15–25 秒，略）：

14:27:34,852 INFO  [DriverManager] Installing driver kars.
14:27:34,854 INFO  [DriverManager] 0 drivers will be installed.
14:27:34,855 INFO  [DriverManager] Finished installing drivers kars.
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 : 127.0.0.1:8083

看到 Created listener for webserver @ address : 127.0.0.1:8083 即服务就绪，监听地址与端口与命令行一致。

默认账号实测：命令行方式使用内置默认账号 cluster/cluster：

curl -s -o /dev/null -w '%{http_code}\n' -u cluster:cluster http://localhost:8083/kettle/status/
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8083/kettle/status/

实测输出：

200
401

即 cluster/cluster 返回 200，无凭据返回 401。

四、方式二：配置文件 启动（实测）

配置文件为 XML，<slaveserver> 声明本节点（名称/地址/端口/凭据/角色），slave 额外用 <report_to_masters> 与 <masters> 声明向谁注册。以 master（8081）与 slave（8082）双实例为例。

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>

启动 master：

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

实测输出（尾部）：

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

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>

启动 slave（另开窗口）：

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

实测输出（尾部，关键为注册行）：

2026/10/12 12:15:45 - Carte - Registered this slave server to master slave server [master] on address [localhost:8081]
2026/10/12 12:15:45 - Carte - Created listener for webserver @ address : localhost:8082

配置文件方式下，接口凭据以各配置文件 username/password 为准（本文两实例均为 admin/q1w2e3r4），master 的 getSlaves 验证见第五节 5.2。

五、HTTP 接口实测

5.1 status：服务状态（实测）

/kettle/status/ 不带参数返回 HTML 状态页（浏览器可直接打开）；带 ?xml=Y 返回 XML：

curl -s -u admin:q1w2e3r4 "http://localhost:8081/kettle/status/?xml=Y"

实测输出（全文）：

<?xml version="1.0" encoding="UTF-8"?>
<serverstatus>
<statusdesc>Online</statusdesc>
<memory_free>275142840</memory_free>
<memory_total>460324864</memory_total>
<cpu_cores>12</cpu_cores>
<cpu_process_time>13891331243</cpu_process_time>
<uptime>738173</uptime>
<thread_count>74</thread_count>
<load_avg>3.48</load_avg>
<os_name>Linux</os_name>
<os_version>6.8.0-138-generic</os_version>
<os_arch>amd64</os_arch>
  <transstatuslist>
  </transstatuslist>
  <jobstatuslist>
  </jobstatuslist>
</serverstatus>

关键字段：statusdesc（Online 为正常）、memory_free/memory_total（JVM 内存）、uptime（秒）、transstatuslist/jobstatuslist（当前节点上登记的转换/作业，空列表即无执行中任务）。

凭据要求实测（配置文件方式，账号 admin/q1w2e3r4）：

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8081/kettle/status/
curl -s -o /dev/null -w '%{http_code}\n' -u cluster:cluster http://localhost:8081/kettle/status/
curl -s -o /dev/null -w '%{http_code}\n' -u admin:q1w2e3r4 http://localhost:8081/kettle/status/

实测输出：

401
401
200

5.2 getSlaves：集群成员列表（实测）

curl -s -u admin:q1w2e3r4 http://localhost:8081/kettle/getSlaves/

实测输出（全文）：

<?xml version="1.0" encoding="UTF-8"?>
<SlaveServerDetections>
<SlaveServerDetection>
      <slaveserver>
        <name>Dynamic slave [localhost:8082]</name>
        <hostname>localhost</hostname>
        <port>8082</port>
        <webAppName/>
        <username>admin</username>
<password>Encrypted 2be98afc86aa7f2e4ba48b922dbc1bd8e</password>        <proxy_hostname/>
        <proxy_port/>
        <non_proxy_hosts/>
        <master>N</master>
        <sslMode>N</sslMode>      </slaveserver>
<active>Y</active>
<last_active_date>2026/10/12 14:27:31.821</last_active_date>
<last_inactive_date/>
</SlaveServerDetection>

</SlaveServerDetections>

active=Y 表示该子节点心跳正常；password 的 Encrypted ... 是注册信息的加密回显，属正常现象。单节点（无 slave 注册）时返回仅含空 <SlaveServerDetections> 的 XML。

5.3 常用接口一览

以下接口均位于 /kettle/ 上下文、要求 Basic 认证，返回 XML；带 ⭐ 者为本文实测项：

接口用途
/kettle/status/ ⭐服务状态（?xml=Y 为 XML，否则 HTML 状态页）
/kettle/getSlaves/ ⭐集群成员列表（master 视角）
/kettle/registerSlave/子节点向 master 注册（report_to_masters 内部即走此接口）
/kettle/addTrans/登记一个转换到本节点执行
/kettle/addJob/登记一个作业到本节点执行
/kettle/prepareTrans/预执行准备（集群分片转换的两阶段执行第一步）
/kettle/startTrans/ / /kettle/startJob/启动已登记的转换/作业
/kettle/getTransStatus/ / /kettle/getJobStatus/查询执行状态（按 name 与 id 定位）
/kettle/pauseTrans/ / /kettle/stopTrans/ / /kettle/stopJob/暂停/停止执行
/kettle/removeTrans/ / /kettle/removeJob/从节点上移除登记
/kettle/sniff/对指定步骤抽样抓取数据行
/kettle/getProperties/读取节点的 kettle.properties 变量
/kettle/heartbeat/子节点心跳上报（配合 master 的成员检测）
/kettle/allocatePort/集群转换执行时的端口分配
/kettle/canRun/资源检查（能否再承接任务）

💡 说明：除 ⭐ 项外其余接口的参数细节可在官方文档查阅；用法上与 status 一致——GET 请求 + Basic 认证 + XML 回显。

六、停止 Carte（-s 实测）

「接口地址 端口」形态支持原地停止：

/opt/pentaho/data-integration/carte.sh 127.0.0.1 8085 -s -u cluster -p cluster

实测流程（先起后停）：

# 启动
2026/10/12 14:48:14 - Carte - Created listener for webserver @ address : 127.0.0.1:8085
curl -s -o /dev/null -w '%{http_code}\n' -u cluster:cluster http://localhost:8085/kettle/status/
200
# 停止
carte.sh 127.0.0.1 8085 -s -u cluster -p cluster
（命令执行后返回）
curl -s -o /dev/null -w '%{http_code}\n' -u cluster:cluster http://localhost:8085/kettle/status/
000
ps -ef | grep -c "[o]rg.pentaho.di.www.Carte.*8085"
0

即停止后接口不可达（curl 返回 000）、对应进程退出。停止一个并不存在的实例时，报连接异常（实测）：

org.pentaho.di.www.Carte$CarteCommandException: "No Carte Server found at 127.0.0.1:8086
Caused by: com.sun.jersey.api.client.ClientHandlerException: java.net.ConnectException: Connection refused (Connection refused)
Caused by: java.net.ConnectException: Connection refused (Connection refused)

注意：-u/-p 需与目标实例的账号一致（命令行方式为默认的 cluster/cluster；配置文件方式为配置文件中的 username/password）。

七、进程管理建议

  • 前台运行：直接执行 carte.sh 0.0.0.0 8081，日志实时输出，Ctrl+C 停止；适合验证阶段。
  • 后台运行：nohup ./carte.sh 0.0.0.0 8081 > /tmp/carte-8081.log 2>&1 &，日志落盘。
  • 生产托管：systemd 单元托管（ExecStart=/opt/pentaho/data-integration/carte.sh /opt/pentaho/carte-master.xml，Type=simple），实现开机自启与崩溃拉起，完整配置方法见《Kettle 9.1 Carte 集群部署指南》。
  • 强杀兜底：Carte 进程主类为 org.pentaho.di.www.Carte，pkill 按主类匹配时用方括号技巧防自匹配：
pkill -f "[o]rg.pentaho.di.www.Carte"

八、常见问题

8.1 接口返回 401

凭据与启动方式强相关：命令行方式（IP+端口）固定为默认账号 cluster/cluster；配置文件方式以配置文件 username/password 为准。用错误凭据（含对命令行方式用自定义账号）均返回 401。另注意 slave 的 masters 节点中凭据必须与 master 配置一致，否则注册请求也返回 401。

8.2 启动报 Address already in use

现象（日志尾部异常栈）：

Caused by: java.net.BindException: Address already in use
        at sun.nio.ch.Net.bind0(Native Method)
        （中间栈帧省略）
        at org.pentaho.di.www.WebServer.startServer(WebServer.java:285)

端口被残留进程占用。排查与清理：

ss -lntp | grep 8081
pkill -f "[o]rg.pentaho.di.www.Carte"

8.3 -s 停止时报 No Carte Server found

目标地址端口上没有运行中的 Carte（或已退出），见第六节异常回显。先用 status 接口确认目标在运行，再执行停止；同时核对 -u/-p 凭据。

8.4 启动报 -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+ 已移除该机制。解决：统一使用 JDK 8（java -version 复核）。

8.5 启动日志中的 Karaf/OSGI 输出

启动阶段会打印 Karaf Instance、OSGI Service Port、CXF/Jetty bundle 加载等大量 INFO 日志（约 15–25 秒），最终以 Created listener for webserver @ address : <地址:端口> 标志就绪，属正常初始化过程。

九、参考链接