Apache Hop 配置参数详解

Apache Hop 2.19.0 配置参数详解：hop-config.json 全局配置、project-config.json 项目配置、运行配置 local.json、环境变量与 JVM 内存参数，含参数总览表、核心键说明与生产配置模板。

Apache HopApache Hop参数调优Apache大数据配置详解2026/10/11

Apache Hop 配置参数详解

目标：详解 Apache Hop 2.19.0 在 /opt/data/apache-hop 部署下的配置体系——全局 hop-config.json、项目 project-config.json、本地运行配置 local.json、环境变量与 JVM 内存参数，给出参数总览、核心键详解与生产配置模板，参数均来源于本机实测配置。

一、环境信息

项目值
操作系统Ubuntu 22.04.5 LTS
软件版本Apache Hop 2.19.0
运行 JDKOpenJDK 21.0.12.1
安装目录/opt/apache-hop/hop
项目根目录（PROJECT_HOME）/opt/data/apache-hop/project
环境变量文件/etc/profile.d/hop-env.sh
日志目录/opt/data/apache-hop/logs

二、前置条件

  • Apache Hop 2.19.0 已按《Ubuntu 22.04 安装 Apache Hop 2.19.0 指南》安装并配置好 JDK 21、环境变量与项目目录。
  • 具备对 /opt/apache-hop/hop/config/、/opt/data/apache-hop/project/、/etc/profile.d/hop-env.sh 的读写权限（root）。
  • 了解 Hop 的层级：全局（hop-config.json）→ 项目（project-config.json）→ 运行配置（local.json）→ 环境变量，越靠后优先级越高。

三、参数查看与修改方式

配置均为 JSON/YAML 或 shell 环境变量文本，直接编辑对应文件并重启 Hop 进程即生效。查看各配置入口是否存在：

cat /opt/apache-hop/hop/config/hop-config.json
cat /opt/data/apache-hop/project/project-config.json
cat /etc/profile.d/hop-env.sh

查看当前生效的环境变量：

env | grep -E '^(JAVA_HOME|HOP_|PATH)'

查看运行中的 Hop 进程实际 JVM 参数：

jps -lv | grep -i hop

修改建议：优先改 /opt/data/apache-hop/project/ 下的项目级配置与环境变量文件 /etc/profile.d/hop-env.sh；不改动 Hop 安装目录内的出厂配置，便于版本升级与多项目复用。

四、参数总览

配置层级文件/入口关键键作用范围
全局<安装目录>/config/hop-config.jsonLocaleDefault、projectsConfig.*整个 Hop 实例
项目<PROJECT_HOME>/project-config.jsonmetadataBaseFolder、enforcingExecutionInHome、config.variables单个项目
运行配置<PROJECT_HOME>/metadata/pipeline-run-configuration/local.jsonengineRunConfiguration.Local.*、name、defaultSelection本地引擎执行
环境变量/etc/profile.d/hop-env.shJAVA_HOME、HOP_HOME、HOP_OPTIONS、PATH当前 shell / 启动脚本
启动脚本<安装目录>/hopHOP_JAVA_HOME、JAVA_HOME、HOP_OPTIONS 默认值 -Xmx2048mHop 进程启动

五、核心参数分类详解

5.1 全局配置（hop-config.json）

位于 /opt/apache-hop/hop/config/hop-config.json，本机默认内容：

{
  "LocaleDefault": "en_US",
  "projectsConfig": {
    "enabled": true,
    "projectMandatory": true,
    "defaultProject": "default",
    "standardParentProject": "default",
    "projectConfigurations": [
      {
        "projectName": "default",
        "projectHome": "/opt/data/apache-hop/project",
        "configFilename": "project-config.json"
      },
      {
        "projectName": "samples",
        "projectHome": "config/projects/samples",
        "configFilename": "project-config.json"
      }
    ]
  }
}
键本机值含义
LocaleDefaulten_US默认区域语言
projectsConfig.enabledtrue是否启用项目管理模型
projectsConfig.projectMandatorytrue是否强制要求指定项目
projectsConfig.defaultProjectdefault默认项目名
projectsConfig.standardParentProjectdefault标准父项目
projectsConfig.projectConfigurations[]见上项目列表，每项含 projectName、projectHome、configFilename

💡 说明：修改某项目的 projectHome 指向新的数据目录后，Hop 会在该目录读取 project-config.json，并据此定位元数据，实现项目级数据与安装目录解耦。

5.2 项目配置（project-config.json）

位于 /opt/data/apache-hop/project/project-config.json：

{
  "metadataBaseFolder": "${PROJECT_HOME}/metadata",
  "unitTestsBasePath": "${PROJECT_HOME}",
  "dataSetsCsvFolder": "${PROJECT_HOME}/datasets",
  "enforcingExecutionInHome": true,
  "parentProjectName": "",
  "config": {
    "variables": []
  }
}
键本机值含义
metadataBaseFolder${PROJECT_HOME}/metadata元数据（运行配置、数据源等）基路径，${PROJECT_HOME} 为项目根
unitTestsBasePath${PROJECT_HOME}单元测试基路径
dataSetsCsvFolder${PROJECT_HOME}/datasets数据集合 CSV 目录
enforcingExecutionInHometrue强制所有可执行文件须位于项目根内
parentProjectName空父项目名（用于继承）
config.variables[]项目级变量（name/value）

⚠️ 注意：enforcingExecutionInHome=true 时，hop run -f 的路径必须是项目内相对路径，否则报「pipeline path is invalid」。

5.3 运行配置（pipeline-run-configuration/local.json）

位于 /opt/data/apache-hop/project/metadata/pipeline-run-configuration/local.json：

{
  "engineRunConfiguration": {
    "Local": {
      "feedback_size": "50000",
      "sample_size": "100",
      "sample_type_in_gui": "Last",
      "rowset_size": "10000",
      "safe_mode": false,
      "show_feedback": false,
      "topo_sort": false,
      "gather_metrics": false
    }
  },
  "name": "local",
  "configurationVariables": [],
  "description": "",
  "defaultSelection": true
}
键值含义
namelocal运行配置名，hop run -r/--runconfig 按此引用
engineRunConfiguration.Local见上本地引擎参数块
engineRunConfiguration.Local.feedback_size50000每处理多少行输出一次反馈日志
engineRunConfiguration.Local.sample_size100样本行数
engineRunConfiguration.Local.rowset_size10000变换间行集缓冲大小
engineRunConfiguration.Local.safe_modefalse是否开启安全模式
engineRunConfiguration.Local.gather_metricsfalse是否采集性能指标
defaultSelectiontrue是否为默认运行配置

5.4 环境变量与启动脚本（含 JVM 内存）

环境变量文件 /etc/profile.d/hop-env.sh：

# Apache Hop environment
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export HOP_HOME=/opt/apache-hop/hop
export PATH="$HOP_HOME:$PATH"
export HOP_OPTIONS="-Xms256m -Xmx512m"

启动脚本 <安装目录>/hop 中对 Java 与堆的逻辑（摘要）：

  • Java 定位顺序：HOP_JAVA_HOME（最优先）→ JAVA_HOME → 系统 java；
  • 默认堆：若未设置 HOP_OPTIONS，则使用 -Xmx2048m；
  • 未设置 HOP_AUDIT_FOLDER 时写入 ./audit。
环境变量默认值含义
JAVA_HOME/usr/lib/jvm/java-21-openjdk-amd64JDK 21 根目录（2.19.0 必需）
HOP_HOME/opt/apache-hop/hopHop 安装目录
HOP_JAVA_HOME空独立覆盖 Hop 使用的 JVM（优先于 JAVA_HOME）
HOP_OPTIONS-Xmx2048m（脚本内置）JVM 参数，含堆大小
HOP_CONFIG_LOCATION空全局配置目录覆盖

💡 说明：为控制服务器内存，将堆限制在 256–512MB（-Xms256m -Xmx512m）。修改后重启依赖 Hop 的进程，并用 jps -lv 确认 -Xmx512m 生效（见三、参数查看与修改方式）。

六、生产配置模板

适用场景：16GB 内存、SSD、单机数据编排与定时 ETL 任务生产部署。

全局 hop-config.json 关键项建议：

{
  "LocaleDefault": "zh_CN",
  "projectsConfig": {
    "enabled": true,
    "projectMandatory": true,
    "defaultProject": "default",
    "projectConfigurations": [
      {
        "projectName": "default",
        "projectHome": "/opt/data/apache-hop/project",
        "configFilename": "project-config.json"
      }
    ]
  }
}

项目 project-config.json：

{
  "metadataBaseFolder": "${PROJECT_HOME}/metadata",
  "unitTestsBasePath": "${PROJECT_HOME}",
  "dataSetsCsvFolder": "${PROJECT_HOME}/datasets",
  "enforcingExecutionInHome": true,
  "config": {
    "variables": [
      { "name": "AUDIT_FOLDER", "value": "/opt/data/apache-hop/audit" }
    ]
  }
}

运行配置 local.json（本地执行，含合理缓冲）：

{
  "engineRunConfiguration": {
    "Local": {
      "feedback_size": "100000",
      "sample_size": "100",
      "sample_type_in_gui": "Last",
      "rowset_size": "20000",
      "safe_mode": false,
      "show_feedback": false,
      "topo_sort": false,
      "gather_metrics": true
    }
  },
  "name": "local",
  "configurationVariables": [],
  "description": "production local run config",
  "defaultSelection": true
}

环境变量 /etc/profile.d/hop-env.sh 生产建议值：

export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
export HOP_HOME=/opt/apache-hop/hop
export PATH="$HOP_HOME:$PATH"
export HOP_OPTIONS="-Xms256m -Xmx512m"

✅ 说明：-Xms256m -Xmx512m 将堆固定在 256–512MB 区间，配合 gather_metrics=true 采集执行指标，适合 16GB 内存场景下长期稳定运行；如单次处理行数极大（千万级），可视实际将 rowset_size 上调并复核堆上限。

七、常见问题

7.1 改了 projectHome 后 hop run 找不到文件

定位：enforcingExecutionInHome=true 时文件必须在项目 PROJECT_HOME 内。解决：把 .hpl/.hwf 放进对应 pipelines/、workflows/ 子目录，再用项目内相对路径运行。

7.2 HOP_OPTIONS 设置后堆没变（仍很大）

定位：可能是 HOP_OPTIONS 未被当前 shell 继承，或 hop 脚本用了 HOP_JAVA_HOME 分支。解决：确认环境变量已 export 并 source，用 env | grep HOP 与 jps -lv 复核；极端情况显式设置 HOP_JAVA_HOME 并在脚本中临时指定 HOP_OPTIONS.

7.3 改配置后不生效

定位：Hop 配置在进程启动时读取一次。解决：修改任一 *.json 或环境变量后重启对应 Hop 进程（若为常驻 hop server，重启服务）。

7.4 项目需要父项目继承功能但这里用不上

定位：parentProjectName 为空表示不继承父项目。如需复用公共元数据，在 hop-config.json 的 projectConfigurations[] 增加父项目并在 project-config.json 填 parentProjectName。

八、参考链接