Apache Hop Docker Compose 部署指南

目标：在具备 Docker 与 Docker Compose 的 Linux 服务器上，使用 Apache Hop 官方镜像 apache/hop 以 Compose 方式部署数据编排平台 2.19.0，覆盖持续运行的 hop server 与一次性执行的 hop run 两种形态，示例账号 admin、密码 q1w2e3r4。

一、环境信息

项目	值
部署方式	Docker Compose（`docker compose`）
官方镜像	`apache/hop`（镜像标签与 Hop 版本号一致，如 `2.19.0`、`latest`）
发行版本	Apache Hop 2.19.0
容器内安装目录	`/opt/hop`（部署路径，镜像内置）
容器内数据挂载点	`/files`（卷挂载点，镜像内置）
服务端口	8080（HTTP，供 hop server Web/API，镜像 `EXPOSE 8080`）
宿主持久化目录	`/opt/data/apache-hop`
示例账号	`admin`，示例密码 `q1w2e3r4`

💡 说明：Apache Hop 数据编排平台官方提供 apache/hop 镜像。镜像入口脚本 run.sh 读取一套 HOP_* 环境变量，据此决定启动 hop 的命令与参数，因此同一镜像既能以 hop server 常驻运行，也能以 hop run 一次性执行转换，还可运行 hop gui 图形界面。

二、镜像选型说明

镜像	用途	说明
`apache/hop:2.19.0`	生产/测试锁版本	推荐，对应 Hop 2.19.0，可复现性最好
`apache/hop:latest`	尝鲜	跟随最新稳定版
`apache/hop:<历史版本>`	回退/多版本	镜像标签与 Hop 版本一一对应

✅ 选型建议：生产环境固定 2.19.0 版本标签，避免 latest 漂移带来的行为变化；多版本并行时用不同目录与 Compose 项目名隔离。

镜像基于 Alpine 构建，内置 JDK；容器默认 EXPOSE 8080，默认工作目录 /home/hop，卷挂载点 /files 用于放置转换/工作流文件。

三、前置条件

服务器已安装 Docker。验证 Docker 与 Compose：

docker --version
docker compose version

实测回显示例：

Docker version 26.1.x
Docker Compose version v2.x

可访问镜像仓库拉取 apache/hop。如使用镜像加速器，请按服务器配置调整。
宿主准备好数据持久化目录：

mkdir -p /opt/data/apache-hop/project/pipelines
mkdir -p /opt/data/apache-hop/project/metadata
mkdir -p /opt/data/apache-hop/files

⚠️ 注意：镜像基于 Alpine，宿主卷目录权限建议保持可写；若用 root 运行可暂以 root 用户写入。

四、部署步骤

4.1 形态一：以 `hop server` 常驻运行（compose）

创建 /opt/data/apache-hop/docker-compose.yml，该配置把 Hop 作为 Web 服务器常驻监听 8080：

services:
  hop:
    image: apache/hop:2.19.0
    container_name: hop-server
    restart: unless-stopped
    hostname: hop-server
    environment:
      - HOP_COMMAND=server
      - HOP_SERVER_HOSTNAME=0.0.0.0
      - HOP_SERVER_PORT=8080
      - HOP_SERVER_AUTH=true
      - HOP_SERVER_USER=admin
      - HOP_SERVER_PASSWORD=${HOP_SERVER_PASSWORD}
      - HOP_PROJECT_NAME=default
      - HOP_PROJECT_DIRECTORY=/files/project
      - HOP_PROJECT_CONFIG_FILE_NAME=project-config.json
      - HOP_OPTIONS=-Xms256m -Xmx512m
      - HOP_LOG_LEVEL=Basic
    ports:
      - "8080:8080"
    volumes:
      - /opt/data/apache-hop/project:/files/project
      - /opt/data/apache-hop/files:/files

💡 说明：环境变量中引用 ${HOP_SERVER_PASSWORD} 用于从宿主机环境注入密码，避免明文落入 compose 文件。可在启动前先导出：
export HOP_SERVER_PASSWORD=q1w2e3r4

启动服务：

cd /opt/data/apache-hop
docker compose up -d
docker compose ps

回显示例：

NAME         IMAGE              COMMAND ...   STATUS      PORTS
hop-server   apache/hop:2.19.0  ...           Up 5 sec    0.0.0.0:8080->8080/tcp

校验服务日志出现监听信息：

docker compose logs -f hop

回显示例（节选）：

HopServer - Enabling project 'default'
HopServer - Two-way password encoder initialized with plugin ID 'Hop' for project 'default'
HopServer - Installing timer to purge stale objects after 1440 minutes.
HopServer - Hop Server: Basic authentication is ENABLED
HopServer - Created listener for webserver @ address : localhost:8080

4.2 形态二：以 `hop run` 一次性执行转换（compose）

同样可用 Compose 一次性拉起并执行一个转换，执行完即退出。首先把转换文件放在宿主数据目录：

cat > /opt/data/apache-hop/files/my-first-pipeline.hpl <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<pipeline>
  <info>
    <name>my-first-pipeline</name>
    <name_sync_with_filename>Y</name_sync_with_filename>
    <description>my first hop pipeline</description>
    <pipeline_type>Normal</pipeline_type>
    <created_user>root</created_user>
  </info>
  <order>
    <hop><from>Generate Rows</from><to>Dummy</to><enabled>Y</enabled></hop>
  </order>
  <transform>
    <name>Generate Rows</name>
    <type>RowGenerator</type>
    <description/>
    <copies>1</copies>
    <partitioning><method>none</method><schema_name/></partitioning>
    <fields>
      <field><name>x</name><type>Integer</type><length>9</length></field>
    </fields>
    <interval_in_ms>1000</interval_in_ms>
    <limit>5</limit>
    <never_ending>N</never_ending>
  </transform>
  <transform>
    <name>Dummy</name>
    <type>Dummy</type>
    <description/>
    <copies>1</copies>
    <partitioning><method>none</method><schema_name/></partitioning>
  </transform>
</pipeline>
EOF

新建一次性执行用的 Compose 文件 /opt/data/apache-hop/docker-compose.run.yml：

services:
  hop-run:
    image: apache/hop:2.19.0
    container_name: hop-run-once
    restart: "no"
    environment:
      - HOP_COMMAND=run
      - HOP_FILE_PATH=/files/my-first-pipeline.hpl
      - HOP_RUN_CONFIG=local
      - HOP_OPTIONS=-Xms256m -Xmx512m
      - HOP_LOG_LEVEL=Basic
    volumes:
      - /opt/data/apache-hop/files:/files

执行并查看日志：

cd /opt/data/apache-hop
docker compose -f docker-compose.run.yml run --rm hop-run

回显示例（节选，执行成功退出码为 0）：

HopRun - Enabling project 'default'
HopRun - Starting pipeline: /files/my-first-pipeline.hpl
my-first-pipeline - Executing this pipeline using the Local Pipeline Engine with run configuration 'local'
my-first-pipeline - Execution started for pipeline [my-first-pipeline]
Generate Rows.0 - Finished processing (I=0, O=0, R=0, W=5, U=0, E=0)
Dummy.0 - Finished processing (I=0, O=0, R=5, W=5, U=0, E=0)
my-first-pipeline - Pipeline duration : 0.0xx seconds
my-first-pipeline - Execution finished on a local pipeline engine with run configuration 'local'

五、数据持久化说明

项目/文件挂载：/opt/data/apache-hop/project:/files/project 与 /opt/data/apache-hop/files:/files 把转换、工作流与项目元数据持久化到宿主，容器重建不丢数据。
审计/日志：可把 HOP_LOG_PATH 指向 /files 下的日志文件（镜像内置默认写 /opt/hop/hop.err.log），例如：

    environment:
      - HOP_LOG_PATH=/files/hop.err.log

容器停止后再启动（docker compose up -d）数据仍存在；彻底清理用 docker compose down -v（会删除卷，谨慎使用）。

六、常用环境变量表

以下环境变量摘自官方镜像 Dockerfile，均为实测有效键：

环境变量	默认值	含义
`HOP_COMMAND`	无	要执行的 `hop` 子命令，如 `run`、`server`、`gui`
`HOP_COMMAND_PARAMETERS`	空	追加的 `hop` 命令参数（空格分隔）
`HOP_FILE_PATH`	空	要运行的转换/工作流文件路径
`HOP_RUN_CONFIG`	空	运行配置名（如 `local`）
`HOP_RUN_PARAMETERS`	空	运行参数，如 `key=value`
`HOP_START_ACTION`	空	工作流开始动作名
`HOP_LOG_LEVEL`	`Basic`	日志级别：NOTHING/ERROR/MINIMAL/BASIC/DETAILED/DEBUG/ROWLEVEL
`HOP_SYSTEM_PROPERTIES`	空	逗号分隔的 `KEY=VALUE` 系统属性列表
`HOP_PROJECT_NAME`	`project1`	项目名
`HOP_PROJECT_DIRECTORY`	空	项目目录路径
`HOP_PROJECT_CONFIG_FILE_NAME`	`project-config.json`	项目配置文件
`HOP_ENVIRONMENT_NAME`	`environment1`	生命周期环境名
`HOP_OPTIONS`	`-XX:+AggressiveHeap`	传给 Java 的 JVM 参数（含堆大小）
`HOP_SERVER_HOSTNAME`	`0.0.0.0`	服务监听地址
`HOP_SERVER_PORT`	`8080`	服务端口
`HOP_SERVER_AUTH`	`true`	是否开启 Basic 认证
`HOP_SERVER_USER`	`cluster`	服务认证用户名
`HOP_SERVER_PASSWORD`	`cluster`	服务认证密码

⚠️ 说明：HOP_OPTIONS 在官方镜像中的默认值为 -XX:+AggressiveHeap（趋向吃满内存），生产务必显式覆盖为受控堆，如 -Xms256m -Xmx512m（见第八节 JVM 内存专项）。

七、常用配置参数说明（command）

入口脚本等价于执行 hop $HOP_COMMAND $HOP_COMMAND_PARAMETERS。表内字段与「酷参数」来自官方镜像入口脚本变量，组合示例：

场景	`HOP_COMMAND`	关键配合变量
运行转换	`run`	`HOP_FILE_PATH`、`HOP_RUN_CONFIG`、`HOP_RUN_PARAMETERS`
运行工作流	`run`	`HOP_FILE_PATH`、`HOP_START_ACTION`（可选）
启动 Web 服务器	`server`	`HOP_SERVER_HOSTNAME`/`PORT`/`USER`/`PASSWORD`/`AUTH`
打开图形界面	`gui`	`HOP_OPTIONS`（桌面环境）

八、配置文件持久化（conf 挂载）

若需把完整的 Hop 配置目录（含 config/hop-config.json 与项目配置）挂载进容器做持久化，可在服务上追加卷并同步环境变量：

    environment:
      - HOP_PROJECT_NAME=default
      - HOP_PROJECT_DIRECTORY=/files/project
      - HOP_PROJECT_CONFIG_FILE_NAME=project-config.json
    volumes:
      - /opt/data/apache-hop/project:/files/project

⚠️ 注意：project-config.json 中的路径常使用 ${PROJECT_HOME} 相对占位，容器内由 HOP_PROJECT_DIRECTORY 决定实际根路径；保持目录名一致即可复用已有项目结构。

8.1 JVM 内存专项（compose 形态）

镜像默认 HOP_OPTIONS=-XX:+AggressiveHeap 会尽量占用机器内存，Compose 部署时按下列方式限制堆在 256–512MB：

    environment:
      - HOP_OPTIONS=-Xms256m -Xmx512m

加入上述行后，docker compose up -d 重建容器，再进入容器用 jps -v 复核实际生效值：

docker compose exec hop bash -lc 'jps -v | tr " " "\n" | grep -E "^-Xms|^-Xmx"'

回显示例：

-Xms256m
-Xmx512m

✅ 验证要点：jps -v 输出中出现 -Xms256m 与 -Xmx512m 即表示容器内 Hop 进程堆限制已生效。

九、等价 docker run 运行方式

不使用 Compose 时，可等价改用 docker run 启动 Hop Server：

docker run -d --name hop-server \
  -e HOP_COMMAND=server \
  -e HOP_SERVER_HOSTNAME=0.0.0.0 \
  -e HOP_SERVER_PORT=8080 \
  -e HOP_SERVER_AUTH=true \
  -e HOP_SERVER_USER=admin \
  -e HOP_SERVER_PASSWORD=q1w2e3r4 \
  -e HOP_OPTIONS="-Xms256m -Xmx512m" \
  -p 8080:8080 \
  -v /opt/data/apache-hop/project:/files/project \
  apache/hop:2.19.0

对应的一次性执行转换：

docker run --rm --name hop-run-once \
  -e HOP_COMMAND=run \
  -e HOP_FILE_PATH=/files/my-first-pipeline.hpl \
  -e HOP_RUN_CONFIG=local \
  -e HOP_OPTIONS="-Xms256m -Xmx512m" \
  -v /opt/data/apache-hop/files:/files \
  apache/hop:2.19.0

十、常用运维命令

以下命令均在 /opt/data/apache-hop（compose 文件所在目录）执行。

启动/停止/查看状态：

docker compose up -d
docker compose ps
docker compose logs -f hop
docker compose stop
docker compose start
docker compose restart hop

进入容器内检视/复核 JVM：

docker compose exec hop bash -lc 'jps -lv'

重置并清理（删除容器，-v 同时删卷，谨慎）：

docker compose down

拉取指定版本的镜像：

docker pull apache/hop:2.19.0

十一、常见问题（FAQ）

11.1 `hop server` 启动后 8080 无法访问

定位：检查是否将端口正确映射到宿主（-p 8080:8080 或 compose ports:），并确认 HOP_SERVER_HOSTNAME=0.0.0.0（默认即如此）。若沿用 localhost 则只在本机可访问。解决后在浏览器访问 http://<服务器IP>:8080，认证用 admin/q1w2e3r4。

11.2 `hop run` 报 `Please specify a run configuration to execute the pipeline with`

定位：HOP_RUN_CONFIG=local 指向的运行配置在项目 metadata/pipeline-run-configuration/ 下不存在。解决：在项目目录中加上 metadata/pipeline-run-configuration/local.json（本地引擎配置，名称 local），或改用一个已存在的运行配置名。

11.3 容器内存被 Hop 吃满

定位：官方镜像 HOP_OPTIONS 默认 -XX:+AggressiveHeap。解决：在 compose/run 中显式设置 HOP_OPTIONS=-Xms256m -Xmx512m，并用 jps -v 复核（见 8.1 节）。

11.4 执行报 `UnsupportedClassVersionError`

定位：镜像内置 JDK 与 Hop 2.19.0 匹配，一般不会发生；若自建镜像误带入旧 JDK（如 17）则会报错。解决：使用官方 apache/hop:2.19.0 镜像，其内置 JDK 与版本匹配。

十二、参考链接

Apache Hop 官方下载站：https://dlcdn.apache.org/hop/
Apache Hop 项目官网：https://hop.apache.org/
Apache Hop Docker 仓库：https://github.com/apache/hop/tree/2.19.0-rc1/docker
Apache Hop 官方文档：https://hop.apache.org/manual/latest/

Apache Hop Docker Compose 部署指南

Apache Hop Docker Compose 部署指南

一、环境信息

二、镜像选型说明

三、前置条件

四、部署步骤

4.1 形态一：以 hop server 常驻运行（compose）

4.2 形态二：以 hop run 一次性执行转换（compose）

五、数据持久化说明

六、常用环境变量表

七、常用配置参数说明（command）

八、配置文件持久化（conf 挂载）

8.1 JVM 内存专项（compose 形态）

九、等价 docker run 运行方式

十、常用运维命令

十一、常见问题（FAQ）

11.1 hop server 启动后 8080 无法访问

11.2 hop run 报 Please specify a run configuration to execute the pipeline with

11.3 容器内存被 Hop 吃满

11.4 执行报 UnsupportedClassVersionError

十二、参考链接

4.1 形态一：以 `hop server` 常驻运行（compose）

4.2 形态二：以 `hop run` 一次性执行转换（compose）

11.1 `hop server` 启动后 8080 无法访问

11.2 `hop run` 报 `Please specify a run configuration to execute the pipeline with`

11.4 执行报 `UnsupportedClassVersionError`