Apache HertzBeat Docker Compose 部署指南

目标：使用 Docker Compose 一键部署 Apache HertzBeat 1.9.0 实时监控系统（官方镜像 apache/hertzbeat），覆盖数据持久化、常用环境变量与 command 参数、配置文件挂载、等价 docker run、常用运维命令与常见问题。配合同一服务的采集器镜像 apache/hertzbeat-collector 可做分布式采集。本指南与《Ubuntu 22.04 安装 Apache HertzBeat 1.9.0 指南》为两种等价部署方式；前端/API 默认端口与 JDK、账号等与安装指南一致，此处不再赘述安装流程，只聚焦 Compose 编排。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Docker Engine：27.x（含 Compose v2 插件）
镜像：apache/hertzbeat（对应 HertzBeat 1.9.0，官方镜像仓库 docker.io/apache/hertzbeat）
容器名：apache-hertzbeat
端口映射：宿主 31157 → 容器 1157（面板/API）、31158 → 容器 1158（调度）
数据目录（宿主）：/opt/data/ops/hertzbeat/data（内嵌 H2 + DuckDB 历史库）
配置目录（宿主）：/opt/data/ops/hertzbeat/config（挂载覆盖容器 /opt/hertzbeat/config）
日志/扩展库目录（宿主）：/opt/data/ops/hertzbeat/logs、/opt/data/ops/hertzbeat/ext-lib
部署文件：/opt/data/ops/hertzbeat/docker-compose.yaml

二、镜像选型说明

镜像标签	对应版本	说明
`apache/hertzbeat`（默认 latest）	1.9.0	官方主服务镜像（面板 + manager + collector 于一体，Agentless）
`apache/hertzbeat-collector`	1.9.0	独立采集器镜像，与主服务解耦做分布式采集（可选）
`apache/hertzbeat-collector-native`	1.9.0-linux-amd64	GraalVM 原生采集器，启动更快、内存更低（可选）

💡 说明：单机快速体验只需 apache/hertzbeat 一个服务即可。官方镜像内已内置 JDK，无需在宿主安装 JDK。如需按版本锁定镜像，在 image 中写 tag（如 apache/hertzbeat:1.9.0）。

三、前置条件

已安装 Docker Engine 与 Compose v2 插件，验证：docker --version && docker compose version
已规划好数据/配置目录（建议独立数据盘，避免系统盘被写满）
网络可拉取 docker.io/apache/hertzbeat（内网可配置镜像加速源或中转后 docker load）

四、部署步骤

4.1 创建部署目录

sudo mkdir -p /opt/data/ops/hertzbeat/{data,config,logs,ext-lib}
cd /opt/data/ops/hertzbeat

4.2 先准备 config 目录（关键）

官方镜像的配置优先读取 /opt/hertzbeat/config。为把默认配置与自定义配置一次性持久化，请先从镜像导出默认 application.yml、sureness.yml、logback-spring.xml 到宿主（若你已按《安装指南》备好一份也可直接拷贝）：

docker run --rm --name hb-tmp apache/hertzbeat:1.9.0 tar -C /opt/hertzbeat -cf - config | tar -C /opt/data/ops/hertzbeat -xf -
ls /opt/data/ops/hertzbeat/config

⚠️ 注意：拉取 apache/hertzbeat:1.9.0 首次会较久（几百 MB）。sureness.yml 中 account.credential（默认 hertzbeat）请务必在部署前置为强口令——本文演示口令统一为 q1w2e3r4。

4.3 编写 docker-compose.yaml

将以下内容保存为 /opt/data/ops/hertzbeat/docker-compose.yaml：

# =============================================================================
# Apache HertzBeat 1.9.0 Docker Compose 部署文件
# 官方镜像：apache/hertzbeat
# 使用：cd /opt/data/ops/hertzbeat && docker compose up -d
# 面板：http://<服务器IP>:31157   默认账号 admin
# =============================================================================
services:
  hertzbeat:
    image: apache/hertzbeat:1.9.0        # 官方镜像（含内置 JDK 25）
    container_name: apache-hertzbeat
    restart: unless-stopped
    hostname: hertzbeat

    # ---- 常用环境变量（可覆盖 config/application.yml 中的占位符）----
    environment:
      - TZ=Asia/Shanghai                                  # 时区
      - JAVA_OPTS=-Xms256m -Xmx256m -Xmn128m              # JVM 堆限制 256-512MB 专项
      - HERTZBEAT_OTLP_GRPC_PORT=14317                    # OTLP/gRPC 接入端口
      - HERTZBEAT_COLLECTOR_MYSQL_QUERY_ENGINE=auto       # MySQL 采集查询引擎
      - HERTZBEAT_PUSH_MAX_AUTO_CREATED_MONITORS=10000    # 推送网关上限

    # ---- 常用配置参数（command 追加到 JVM 参数，可覆盖外部 config）----
    # 说明：Spring 主配置在 ./config/application.yml，一般无需 command；
    # 此处仅演示通过 -Dspring.config.additional-location 追加外部配置目录。
    command:
      - --add-opens=java.base/java.nio=ALL-UNNAMED

    # ---- 端口映射：宿主31157 -> 容器1157（面板/API），31158 -> 1158（调度）----
    ports:
      - "31157:1157"
      - "31158:1158"

    # ---- 数据持久化（重要）：内嵌 H2 与 DuckDB 落在宿主 data 目录 ----
    volumes:
      - ./data:/opt/hertzbeat/data
      # ---- 配置文件持久化（重要）：宿主编排 config，启动时覆盖默认 ----
      - ./config:/opt/hertzbeat/config
      # ---- 日志与扩展库持久化 ----
      - ./logs:/opt/hertzbeat/logs
      - ./ext-lib:/opt/hertzbeat/ext-lib

    # ---- 健康检查：轮询管理端口返回码 ----
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:1157/"]
      interval: 30s
      timeout: 5s
      retries: 8
      start_period: 60s

    # ---- 日志大小限制，防止占满数据盘 ----
    logging:
      driver: json-file
      options:
        max-size: "100m"
        max-file: "3"

4.4 启动并验证

cd /opt/data/ops/hertzbeat
docker compose up -d
docker compose ps

预期输出（Up 且 (healthy) 出现即就绪，首次启动需约 30–60 秒加载 37 种采集策略）：

NAME               IMAGE                    COMMAND        SERVICE    STATUS
apache-hertzbeat   apache/hertzbeat:1.9.0   "/entrypoint"   hertzbeat  Up 35 seconds (healthy)

验证端口与面板：

sudo netstat -tlnp | grep -E ':31157|:31158'
curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:31157/

预期输出：面板 HTTP 200。浏览器访问 http://<服务器IP>:31157，用 admin + 口令（前置中已配置，本文为 q1w2e3r4）登录。

五、数据持久化说明

容器 /opt/hertzbeat/data → 宿主 ./data：保存内嵌 H2（hertzbeat.mv.db）与 DuckDB 历史时序库（history.duckdb），销毁/重建容器后监控配置与历史数据保留。
容器 /opt/hertzbeat/config → 宿主 ./config：保存 application.yml、sureness.yml、logback-spring.xml，重启不覆盖你的改动。
容器 /opt/hertzbeat/logs → 宿主 ./logs：运行日志。
容器 /opt/hertzbeat/ext-lib → 宿主 ./ext-lib：第三方驱动扩展（如 oracle/mysql 原生驱动），按需放置。
升级镜像前建议 docker compose exec hertzbeat tar -czf /backup.tgz config data 备份数据目录。

六、常用环境变量表

环境变量	默认值	说明
`TZ`	（镜像默认）	时区，置 `Asia/Shanghai`
`JAVA_OPTS`	（镜像内置）	JVM 附加参数，注入 `-Xms/-Xmx`（JVM 堆 256–512MB 专项）
`HERTZBEAT_OTLP_GRPC_PORT`	`14317`	OTLP/gRPC 采集接入端口
`HERTZBEAT_COLLECTOR_MYSQL_QUERY_ENGINE`	`auto`	MySQL/MariaDB/OceanBase/TiDB SQL 采集引擎（auto/jdbc/r2dbc）
`HERTZBEAT_PUSH_MAX_AUTO_CREATED_MONITORS`	`10000`	推送网关自动创建监控上限
`HERTZBEAT_PUSH_MAX_BODY_BYTES`	`5242880`	推送请求体上限（字节）
`HERTZBEAT_PUSH_MAX_SAMPLES`	`10000`	单次推送最大样本数

💡 全部 HERTZBEAT_* 占位符与各自默认值见镜像内 config/application.yml（OTLP、collector、push 三段），通过 environment: 注入即可覆盖。

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

镜像入口脚本以 java $@ -cp ... 启动主程序，command 中追加的参数会追加到 JVM 命令行。典型用法：

-Xms256m -Xmx256m -Xmn128m：堆（也可走环境变量 JAVA_OPTS）；
--add-opens=java.base/java.nio=ALL-UNNAMED：JDK 9+ 模块开放（1.9.0 需要，脚本默认已带）；
-Dspring.config.additional-location=file:/etc/hertzbeat/：额外加载 Spring 配置目录，实现只覆盖指定配置而不整体替换 config/。

💡 说明：Compose 里修改「配置参数」优先改 ./config/application.yml 后 docker compose restart，command 仅在需要追加 JVM/Spring 开关时使用，避免与默认参数冲突。

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

把 ./config 挂载到 /opt/hertzbeat/config 后：

修改 application.yml（端口/数据库/队列/时序存储/推送网关）→ 保存 → docker compose restart hertzbeat；
修改 sureness.yml（账号口令/认证方式/接口权限）→ 保存 → 重启生效（注意 1.9.0 改密即改 account.credential，无 manager 改密接口）；
若只改个别配置不想整体替换，可关闭 config 挂载、改用 command 追加 -Dspring.config.additional-location 指向一个新挂载目录。

九、等价 docker run 运行方式

docker run -d \
  --name apache-hertzbeat \
  --restart unless-stopped \
  -p 31157:1157 \
  -p 31158:1158 \
  -e TZ=Asia/Shanghai \
  -e JAVA_OPTS="-Xms256m -Xmx256m -Xmn128m" \
  -v /opt/data/ops/hertzbeat/data:/opt/hertzbeat/data \
  -v /opt/data/ops/hertzbeat/config:/opt/hertzbeat/config \
  -v /opt/data/ops/hertzbeat/logs:/opt/hertzbeat/logs \
  -v /opt/data/ops/hertzbeat/ext-lib:/opt/hertzbeat/ext-lib \
  apache/hertzbeat:1.9.0

十、常用运维命令

docker compose -f /opt/data/ops/hertzbeat/docker-compose.yaml ps
docker compose -f /opt/data/ops/hertzbeat/docker-compose.yaml logs -f --tail=200 hertzbeat
docker compose -f /opt/data/ops/hertzbeat/docker-compose.yaml restart hertzbeat
docker compose -f /opt/data/ops/hertzbeat/docker-compose.yaml down        # 停止并移除容器（数据保留在宿主 ./data）
docker compose -f /opt/data/ops/hertzbeat/docker-compose.yaml down -v     # 连同命名卷删除（慎用，会删宿主导出数据卷）
docker compose -f /opt/data/ops/hertzbeat/docker-compose.yaml up -d       # 重建/升级后拉起
docker exec apache-hertzbeat sh -c 'ls /opt/hertzbeat/data'               # 查看内嵌数据文件
docker inspect apache-hertzbeat | grep -A5 '"Health"'                       # 健康状态

十一、常见问题（FAQ）

Q1：Compose 提示端口 1157/1158 被占用？

宿主已有其他进程占 1157/1158。改 ports 左侧映射为非常用端口（本文用 31157:1157/31158:1158）即可，面板地址随之变为宿主映射端口。

Q2：启动后健康检查一直 not-started / unhealthy？

首次需 30–60 秒加载采集策略与 Flyway 迁移。用 docker compose logs hertzbeat | grep -i started 看 Started HertzBeatApplication；若始终失败，追加查看 docker compose logs hertzbeat | tail -100 定位（常见是 config 挂载目录缺 application.yml，按 4.2 补齐）。

Q3：HERTZBEAT_* 环境变量不生效？

这些占位符只在镜像内默认 application.yml 出现；若你用自己的 config/application.yml 整体挂载覆盖，则占位符由你的文件决定，环境变量不会自动注入。要么沿用官方默认配置只做必要覆盖，要么在自备配置里保留 ${HERTZBEAT_*:default} 写法。

Q4：登录用什么账号口令？

镜像默认从 sureness.yml 读取：admin / hertzbeat。本文按规范在 config/sureness.yml 更改为 admin / q1w2e3r4。改后需重启生效。

Q5：如何加入独立采集器（collector）做分布式采集？

在 docker-compose.yaml 增加 hertzbeat-collector 服务（镜像 apache/hertzbeat-collector:1.9.0）。采集器需填写主服务 manager 地址与其注册 token 才能上报，具体配置见项目官方文档「分布式采集运行机制」章节。

十二、参考链接

官方镜像仓库（Docker Hub）：https://hub.docker.com/r/apache/hertzbeat
Docker Compose 官方部署示例：https://hertzbeat.apache.org/docs/start/quick-start/
GitHub（docker 目录与 compose 示例）：https://github.com/apache/hertzbeat/tree/v1.9.0/docker
《Ubuntu 22.04 安装 Apache HertzBeat 1.9.0 指南》篇（等价的非容器部署方式）