Apache HertzBeat 配置参数详解

目标：系统讲解 Apache HertzBeat 1.9.0 的核心配置参数。配置集中于 /opt/hertzbeat/config/application.yml（Spring 主配置）与 config/sureness.yml（认证/账号），本文各参数段均以 1.9.0 发行版实测内容为准，覆盖内嵌 H2 与外接 MySQL/PostgreSQL、时序数据存储、告警、监控采集调度、Prometheus 指标出口、推送网关与 OTLP 等模块，并给出可直接套用的生产配置模板。

一、环境信息

组件版本：Apache HertzBeat 1.9.0（安装目录 /opt/hertzbeat）
配置文件：/opt/hertzbeat/config/application.yml（主）、/opt/hertzbeat/config/sureness.yml（认证）、/opt/hertzbeat/config/logback-spring.xml（日志）
运行时：Temurin JDK 25（/opt/hertzbeat/java），JVM 堆 -Xms256m -Xmx256m
关键端口：Web/API 1157、调度 1158、OTLP/gRPC 14317
内嵌数据库：H2（data/hertzbeat.mv.db）、历史时序库 DuckDB（data/history.duckdb）
演示账号：admin / q1w2e3r4

二、前置条件

已按《Ubuntu 22.04 安装 Apache HertzBeat 1.9.0 指南》完成部署（或等价 Compose 部署）；
修改配置后须重启生效：脚本方式 cd /opt/hertzbeat && ./bin/restart.sh；托管在官方发行包 Compose 环境（见《Apache HertzBeat Docker Compose 部署指南》篇）则按对应重启命令。
涉及数据库/时序切换前请先备份现有 data/ 目录。

三、参数查看与修改方式

运行时生效值查看：日志与 SQL 均可核对。application.yml 已把 spring.profiles.active: prod 激活，prod 配置块只在 spring.config.activate.on-profile: prod 下加载。
修改方式：直接编辑 /opt/hertzbeat/config/application.yml，改后 ./bin/restart.sh（或 ./bin/startup.sh 先停后起）生效；托管于官方发行包 Compose 环境则改已挂载的 ./config/application.yml 后重启生效。
环境变量占位：1.9.0 部分参数支持 ${HERTZBEAT_xxx:默认值} 环境变量注入（如 OTLP 端口、collector 查询引擎、push 网关上限），在系统/Compose 环境变量注入即可覆盖，无需改文件。
参数是否被 Spring 识别：改完可用 jps -v 确认 -Dspring.config.location=/opt/hertzbeat/config/ 生效；服务启动日志出现 Started HertzBeatApplication 即配置加载成功。

四、参数总览

模块	配置前缀	关键键	作用
服务与端口	`server` / `scheduler.server`	`port`	Web 1157 / 调度 1158
应用信息	`spring.application` / `spring.profiles`	`name` / `active`	应用名（含 PID）、激活 profile
数据源	`spring.datasource`	`url` / `driver-class-name` / `username` / `password`	内嵌 H2 或外接 MySQL/PostgreSQL
ORM/迁移	`spring.jpa` / `spring.flyway`	`ddl-auto` / `locations`	建表与版本迁移(sql)
消息队列	`common.queue`	`type`	memory/kafka/redis
时序存储	`warehouse.store`	`duckdb` / `victoria-metrics` / `td-engine` / `greptime` 等	历史指标落库
实时存储	`warehouse.real-time.memory` / `redis`	`enabled`	实时指标
告警	`alerter`	`console-url` / 各 webhook / `inhibit`	告警通知与抑制
认证	`sureness`	`auths` / `jwt` / `account`	认证方式与账号
可观测	`management` / `springdoc`	`endpoints` / `prometheus`	Actuator/指标出口
推送网关	`hertzbeat.push`	`max-*`	/api/push 上限
采集/线程	`hertzbeat.collector` / `hertzbeat.vthreads`	`query-engine` / `mode`	MySQL 查询引擎、虚拟线程

五、核心参数详解

5.1 服务与端口（server / scheduler）

server:
  port: 1157                      # Web 面板与 REST API 端口
scheduler:
  server:
    enabled: true
    port: 1158                    # Netty 采集任务调度端口（内部监控数据流转）

server.port：对外面板/API 端口，改后需同步防火墙与前端访问地址。
scheduler.server.port：内部采集调度 Netty 端口，不用对外开放。

5.2 数据源（spring.datasource）——内嵌 H2 与外接 MySQL/PostgreSQL

内嵌 H2（1.9.0 默认）：

spring:
  datasource:
    driver-class-name: org.h2.Driver
    username: sa
    password: 123456
    url: jdbc:h2:./data/hertzbeat;MODE=MYSQL     # 数据文件 data/hertzbeat.mv.db
    hikari:
      max-lifetime: 120000

MODE=MYSQL：以 MySQL 方言兼容模式运行，H2 文件保存在安装目录 data/hertzbeat.mv.db。
生产建议换 MySQL/PostgreSQL（示例 MySQL，PostgreSQL 同理替换 driver/url）：

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    username: hertzbeat
    password: ${MYSQL_PASSWORD}
    url: jdbc:mysql://<mysql主机>:3306/hertzbeat?useUnicode=true&characterEncoding=utf8
    hikari:
      max-lifetime: 120000

⚠️ 说明：换成外接库前先在目标库创建对应数据库与账号；H2 的字段方言与 MySQL 兼容，PostgreSQL 请对应使用 org.postgresql.Driver 与 jdbc:postgresql://<host>:5432/hertzbeat，并把 Flyway 位置切到 classpath:db/migration/postgresql（默认按 {vendor} 自动选择）。

5.3 ORM 与迁移（spring.jpa / spring.flyway）

spring:
  jpa:
    show-sql: false
    database: h2
    hibernate:
      ddl-auto: update             # 启动自动建表/更新
  flyway:
    enabled: true
    clean-disabled: true
    baseline-on-migrate: true
    baseline-version: 1
    locations:
      - classpath:db/migration/{vendor}

ddl-auto: update：实体变更自动建表，配合 Flyway 做版本迁移。
内置迁移脚本按 db/migration/{vendor}（h2/mysql/postgresql）加载。

5.4 消息队列（common.queue）

common:
  queue:
    type: memory          # memory | kafka | redis
    kafka:
      servers: 127.0.0.1:9092
    redis:
      redis-host: 127.0.0.1
      redis-port: 6379

type: memory：默认进程内队列，单机够用。
type: kafka/redis：高吞吐/多副本时启用；对应段配置集群地址与各 topic/队列名。

5.5 时序数据存储与实时存储（warehouse.store / warehouse.real-time）

历史时序指标（warehouse.store 多择一 enabled 为 true）：

warehouse:
  store:
    duckdb:
      enabled: true                 # 默认落盘到 data/history.duckdb
      expire-time: 90d              # 历史记录保留窗口
      store-path: data/history.duckdb
    victoria-metrics:
      enabled: false
      url: http://localhost:8428
    td-engine:                      # TDengine、greptime、questdb、influxdb、doris 类似
      enabled: false

实时指标（warehouse.real-time）：

warehouse:
  real-time:
    memory:
      enabled: true                 # 默认内存实时存储
      init-size: 16
    redis:
      enabled: false

DuckDB：默认历史库，零依赖、轻量（expire-time 默认 90 天，可改 retention）。
VictoriaMetrics/TDengine/QuestDB/Greptime/InfluxDB/Doris：大规模生产可选，各自开启后填连接串，注意历史/实时各择其一 enabled=true。

5.6 告警（alerter）

alerter:
  console-url: https://console.tancloud.io
  we-work-webhook-url: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=
  ding-talk-webhook-url: https://oapi.dingtalk.com/robot/send?access_token=
  fly-book-webhook-url: https://open.feishu.cn/open-apis/bot/v2/hook/
  telegram-webhook-url: https://api.telegram.org/bot%s/sendMessage
  inhibit:
    ttl: 14400000                 # 告警抑制窗口(默认 4h)
  sms:
    enable: false                 # 短信渠道（tencent/alibaba/aws/twilio 等，按需开启）

各 *-webhook-url：在 webhook 地址末尾补上 token/secret 即接入对应 IM 通知。
inhibit.ttl：抑制重复告警的时间窗（毫秒）。
sms：短信多厂商配置，按需开启并填入密钥。

5.7 认证与账号（sureness）

sureness:
  container: jakarta_servlet
  auths:
    - digest
    - basic
    - jwt
  jwt:
    secret: 'CyaFv0bwq2Eik0jdrKUtsA6bx3sDJeFV643R...'
account:
  - appId: admin
    credential: q1w2e3r4        # 实测按规范修改；默认 hertzbeat
    role: [admin]

auths：启用 digest/basic/jwt 三种认证；REST 请求用 Authorization: Bearer <token>（jwt）或 Basic。
jwt.secret：JWT 签名密钥，生产务必更换。
account：受保护 API 的本地账号来源（appId/credential/role）。1.9.0 无 manager「改密」接口，改密即改 credential 并重启。
接口级访问控制在 sureness.yml 的 resourceRole 段（如 /api/monitor/** 按角色授权、/api/apps/hierarchy 免认证等）。

5.8 可观测与 Prometheus 指标出口（management / springdoc）

management:
  endpoints:
    web:
      exposure:
        include: ['metrics', 'health', 'prometheus']
  prometheus:
    metrics:
      export:
        enabled: true
springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

暴露 metrics/health/prometheus 三个 Actuator 端点；GET /actuator/prometheus 输出 Prometheus 文本格式，可直接被 Prometheus 抓取（1.9.0 实测该端点需登录令牌，见《安装指南》4.7）。
springdoc 默认关闭 OpenAPI/UI，如需调试接口文档可置 true（限 admin 角色访问）。

5.9 推送网关、OTLP 与虚拟线程（hertzbeat.*）

hertzbeat:
  otlp:
    grpc:
      enabled: ${HERTZBEAT_OTLP_GRPC_ENABLED:true}
      host: 0.0.0.0
      port: ${HERTZBEAT_OTLP_GRPC_PORT:14317}   # OpenTelemetry gRPC 接入
  collector:
    mysql:
      query-engine: ${HERTZBEAT_COLLECTOR_MYSQL_QUERY_ENGINE:auto}   # auto/jdbc/r2dbc
  push:
    max-auto-created-monitors: ${HERTZBEAT_PUSH_MAX_AUTO_CREATED_MONITORS:10000}
    max-body-bytes: ${HERTZBEAT_PUSH_MAX_BODY_BYTES:5242880}
    max-samples: ${HERTZBEAT_PUSH_MAX_SAMPLES:10000}
  vthreads:
    enabled: true                 # 虚拟线程开关与各模块模式

/api/push/** 为 Prometheus Pushgateway 兼容写入端点，三个 max-* 控制写入上限与自动建监控上限。
OTLP/gRPC 端口用于接入 OpenTelemetry 数据（缺省 14317）。

5.10 内置 AI/MCP（spring.ai.mcp.server）

spring:
  ai:
    mcp:
      server:
        enabled: true
        streamable-http:
          mcp-endpoint: /api/mcp
        type: SYNC

💡 说明：1.9.0 内嵌一个 MCP 服务端（/api/mcp），供大模型代理以标准 MCP 协议对 HertzBeat 做自然语言监控操作；非 LLM 场景可置 enabled: false 关闭。

六、生产配置模板

适用场景：单机 16 GB 内存、NVMe SSD、约 2000 个监控实例的中等负载。要点：改内嵌 DuckDB 保留策略、开虚拟线程边界、外接 MySQL 做元数据、账号口令置强口令。

server:
  port: 1157
spring:
  application:
    name: hertzbeat-prod
  profiles:
    active: prod
  datasource:                      # 改用真实外接库，避免单机 H2 锁
    driver-class-name: com.mysql.cj.jdbc.Driver
    username: hertzbeat
    password: ${MYSQL_PASSWORD}
    url: jdbc:mysql://<mysql主机>:3306/hertzbeat?useUnicode=true&characterEncoding=utf8
    hikari:
      maximum-pool-size: 20
      max-lifetime: 120000
  jpa:
    show-sql: false
    hibernate:
      ddl-auto: update
common:
  queue:
    type: memory                   # 单机 2000 以内 memory 足够；更高转 kafka/redis
warehouse:
  store:
    victoria-metrics:              # 历史时序上卷到 VictoriaMetrics
      enabled: true
      url: http://127.0.0.1:8428
    duckdb:
      enabled: false
  real-time:
    memory:
      enabled: true
alerter:
  inhibit:
    ttl: 14400000
sureness:
  jwt:
    secret: '<生产环境强随机密钥>'
hertzbeat:
  vthreads:
    enabled: true
    collector:
      mode: LIMIT_AND_REJECT
    manager:
      max-concurrent-jobs: 10

⚠️ 说明：${MYSQL_PASSWORD} 与 <...> 为部署时注入的真实值（可用环境变量/密钥管理注入，避免明文入库）。生产务必替换 sureness.jwt.secret 与账号口令。

七、常见问题（FAQ）

Q1：改端口后服务还能起来吗？

能。改 server.port 后 ./bin/restart.sh 重启，netstat -tlnp 查看新端口；注意 startup.sh 用 SERVER_PORT=1157 变量做端口自检，改端口时把该变量同步改掉（bin/startup.sh 第 39 行）。

Q2：把 H2 换 MySQL 后启动报错？

多数是：未先建库/授权、缺驱动或 Flyway 路径错。MySQL 用 com.mysql.cj.jdbc.Driver、PostgreSQL 用 org.postgresql.Driver；1.9.0 发行包已内置常用驱动，扩展驱动放 ext-lib/。迁移脚本由 {vendor} 自动选，别手写死路径。

Q3：warehouse.store 开了多个引擎，数据重复写？

历史时序 store 下只能有一个 enabled: true 落盘（实时 real-time 同理），否则多写且告警窗口重复。请把其余引擎 enabled: false。

Q4：Prometheus 抓不到 /actuator/prometheus？

该端点受认证保护（实测未带令牌 401）。对接方式：用 Authorization: Bearer <token> 抓取，或按 sureness 配置放行/使用带令牌的 Prometheus HTTP 抓取配置；不要在对外网开放认证。

Q5：改了 sureness.yml 的 credential 仍用旧口令能登录？

说明服务未重启配置未 reload。改配置后必须 ./bin/restart.sh（或托管环境对应重启方式），重启后以新口令登录（实测旧口令返回 Incorrect Account or Password）。

八、参考链接

官方配置说明：https://hertzbeat.apache.org/docs/start/config/
application.yml 官方样例：https://github.com/apache/hertzbeat/tree/v1.9.0/config
认证与账号（Sureness）：https://hertzbeat.apache.org/docs/start/account-modify
数据存储（DuckDB/VictoriaMetrics 等）官方文档：https://hertzbeat.apache.org/docs/warehouse/