Apache HertzBeat 常用 CLI 命令与工具详解

Apache HertzBeat 1.9.0 常用 CLI 命令与工具详解——bin/startup.sh(含 status)、shutdown.sh、restart.sh、jps/ps/netstat 进程端口排障、curl 面板与 REST API（登录、监控增删查、Prometheus 指标）、H2 Shell 只读查询与日志 tail，所有命令与真实回显均在 /opt/hertzbeat 实测

Apache HertzBeatApache HertzBeatApache系统监控运维2026/10/11

Apache HertzBeat 常用 CLI 命令与工具详解

目标：系统整理 Apache HertzBeat 1.9.0 在 Linux 下最常用的命令行操作与配套工具，覆盖启停脚本、进程/端口/JVM 排障、REST API 的 curl 调用、内嵌 H2 只读查询与日志查看。本文所有命令与真实回显均在 /opt/hertzbeat（1.9.0）实测通过。

一、环境信息

  • 组件版本：Apache HertzBeat 1.9.0（安装目录 /opt/hertzbeat，JDK 25）
  • Web 端口 1157（面板/REST API）、调度端口 1158
  • 启动目录：/opt/hertzbeat（脚本 bash ./bin/xx.sh 均在部署根目录执行）
  • 日志目录：/opt/hertzbeat/logs/（主日志 startup.log）
  • 数据目录：/opt/hertzbeat/data/（内嵌 H2 + DuckDB）
  • 演示账号：admin / q1w2e3r4（本机启动实例 PID 以实际为准）

二、工具概览

工具/命令来源用途
bin/startup.sh发行包自带启动服务，子命令 status 查状态
bin/shutdown.sh发行包自带优雅停止服务
bin/restart.sh发行包自带重启服务
jps -l -vJDK 自带查看 Java 进程与真实 JVM 参数
netstat -tlnpnet-tools查看端口监听
ps -ef系统查看进程
curl系统面板与 REST API 调用、Prometheus 指标采集
java org.h2.tools.ShellH2 驱动内嵌 H2 只读查询
tail系统日志查看

三、前置条件

  • 已按《Ubuntu 22.04 安装 Apache HertzBeat 1.9.0 指南》完成部署；
  • 终端能以 root 执行 /opt/hertzbeat/bin/*.sh；
  • 查询/调用 REST API 需已登录拿到 token（见 4.5）。

四、工具详解

4.1 bin/startup.sh（启动 / 状态）

启动（部署根目录执行）：

cd /opt/hertzbeat
./bin/startup.sh

实测输出（已内置 JDK 25，走 Use the inner package jdk to start 分支）：

You can review logs at hertzbeat/logs
Starting the HertzBeat hertzbeat-startup ...
Use the inner package jdk to start
...
...
...
Service Start Success!
Service PID: 23221

status 子命令（运行中）：

./bin/startup.sh status

实测输出：

The HertzBeat hertzbeat-startup is running...!
PID: 23221

status 子命令（停止时）：

# 在服务停止状态下
./bin/startup.sh status

实测输出：

The HertzBeat hertzbeat-startup is stopped

正在运行时再次启动会提示已启动（实测：ERROR: The HertzBeat hertzbeat-startup already started!）。

4.2 bin/shutdown.sh（优雅停止）

cd /opt/hertzbeat
./bin/shutdown.sh

实测输出（先发 kill <pid>，随后打印停止成功）：

kill 1793
Shutdown Apache HertzBeat hertzbeat-startup Success!

4.3 bin/restart.sh（重启）

cd /opt/hertzbeat
./bin/restart.sh

实测输出（末尾打印 Restart Success！Spend <秒> seconds）：

Current Time is：2026-10-11 06:01:45 Restart Success！Spend 2 seconds

💡 提示：restart.sh 内部为「先停后起」，修改配置后用它代替手动两步最省事。若脚本从非部署根目录调用存在路径依赖，建议统一 cd /opt/hertzbeat 后执行。

4.4 进程 / 端口 / JVM 排障（jps、ps、netstat）

查看 Java 进程与真实 JVM 参数（确认堆限制生效）：

/opt/hertzbeat/java/bin/jps -l -v | grep -i hertzbeat

实测输出（可见 -Xms256m -Xmx256m -Xmn128m）：

23221 org.apache.hertzbeat.startup.HertzBeatApplication -Duser.timezone=Asia/Shanghai -Dfile.encoding=UTF-8 -Doracle.jdbc.timezoneAsRegion=false --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED -Xms256m -Xmx256m -Xmn128m ...

查看进程树与父进程（PID 1 = 常驻）：

ps -ef | grep -v grep | grep java

查看端口监听（Web 1157 / 调度 1158）：

netstat -tlnp | grep -E ':1157|:1158'

实测输出：

tcp6       0      0 :::1157                 :::*                    LISTEN      23221/./java/bin/jav
tcp6       0      0 :::1158                 :::*                    LISTEN      23221/./java/bin/jav

4.5 面板与 REST API（curl）

面板首页（HTTP 200）：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:1157/

实测输出：HTTP 200。

登录拿 token：

curl -s -X POST http://127.0.0.1:1157/api/account/auth/form \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"admin","credential":"q1w2e3r4"}' \
  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p'

实测输出（一段 JWT，变化值）：

eyJhbGciOiJIUzUxMiIsInppcCI6IkRFRiJ9.eJwt...（45 字符后省略）

定一下 token 并查询监控列表：

TOKEN=$(curl -s -X POST http://127.0.0.1:1157/api/account/auth/form \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"admin","credential":"q1w2e3r4"}' \
  | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
curl -s "http://127.0.0.1:1157/api/monitors?pageIndex=0&pageSize=5" \
  -H "Authorization: Bearer $TOKEN"

实测输出（节选）：code:0，content 为监控数组，totalElements:1（含本机 LocalHTTP 与实例 127.0.0.1:1157）。

{"code":0,"data":{"content":[{"id":693131799233280,"name":"LocalHTTP","app":"api","instance":"127.0.0.1:1157","status":1,...}],"totalElements":1,...},"msg":null}

监控详情：

curl -s http://127.0.0.1:1157/api/monitor/693131799233280 -H "Authorization: Bearer $TOKEN"

实测输出（节选）：metrics:[summary, header]、monitor.status:1。

删除监控：

curl -s -X DELETE http://127.0.0.1:1157/api/monitor/693131799233280 -H "Authorization: Bearer $TOKEN"

Prometheus 指标出口（需令牌）：

curl -s http://127.0.0.1:1157/actuator/prometheus -H "Authorization: Bearer $TOKEN" | head -n 5

实测输出（Prometheus 文本格式，如）：

jvm_memory_committed_bytes{application="04d566dd179a23221",area="heap",environment="prod",id="PS Eden Space"} 1.00663296E8

4.6 内嵌 H2 只读查询

需要先停止服务（避免文件锁），再用 H2 Shell 只读核查表结构（账号 sa/口令 123456）：

cd /opt/hertzbeat && ./bin/shutdown.sh
/opt/hertzbeat/java/bin/java -cp /opt/hertzbeat/lib/h2-2.2.224.jar \
  org.h2.tools.Shell \
  -url 'jdbc:h2:/opt/hertzbeat/data/hertzbeat' \
  -user sa -password 123456 \
  -sql 'SHOW TABLES;'

实测输出（节选，38 组表）：

TABLE_NAME                              | TABLE_SCHEMA
HZB_ALERT_DEFINE                        | PUBLIC
HZB_AUTH_TOKEN                          | PUBLIC
HZB_MONITOR                             | PUBLIC
HZB_STATUS_PAGE_COMPONENT               | PUBLIC
...
flyway_schema_history                   | PUBLIC
(38 rows, 25 ms)

查看某监控实体的行：

cd /opt/hertzbeat && /opt/hertzbeat/java/bin/java -cp /opt/hertzbeat/lib/h2-2.2.224.jar \
  org.h2.tools.Shell \
  -url 'jdbc:h2:/opt/hertzbeat/data/hertzbeat' \
  -user sa -password 123456 \
  -sql 'SELECT ID,NAME,APP,STATUS,INTERVALS FROM HZB_MONITOR'

⚠️ 注意：H2 Shell 直改数据有风险，本文只建议只读查询排障；改配置走 config/sureness.yml/config/application.yml，勿直接改表。

4.7 日志查看（tail）

tail -n 50 /opt/hertzbeat/logs/startup.log
grep -iE 'Started HertzBeatApplication|ERROR|Exception' /opt/hertzbeat/logs/startup.log

常用的关键日志标记：Started HertzBeatApplication in ...seconds（启动完成）、CollectStrategyFactory - Registered 37 collect strategies（采集策略就绪）、WARN/ERROR（排障点）。

五、注意事项

  • 所有 .sh 均在部署根目录 /opt/hertzbeat 下执行（脚本内部 cd \dirname $0`` 依赖位置）。
  • REST 修改类接口一律带 Authorization: Bearer <token>；不带认证的 /api/apps/hierarchy 等只读接口除外。
  • H2/DuckDB 数据文件被进程独占，查 H2 前先 ./bin/shutdown.sh。
  • JVM 堆参数以 jps -v 实看为准，改完 restart.sh 后再 jps -v 复核。

六、常见问题（FAQ）

Q1：netstat 查不到 1157/1158？

未安装 net-tools：apt-get install -y net-tools。也可能服务未启动，先 ./bin/startup.sh status 确认，或 ps -ef | grep java。

Q2：curl 调用 /actuator/prometheus 返回 401？

该端点受认证保护，需在请求头发 Authorization: Bearer <token>；先按 4.5 登录拿 token。

Q3：jps 看不到 HertzBeat 进程？

可能服务已停，或 jps 与进程用户不一致导致无法枚举。用 ps -ef | grep -v grep | grep java 复核；确认以服务启动用户执行 jps。

Q4：./bin/startup.sh 刷 netstat: command not found 但仍起服务？

是未装 net-tools，脚本端口自检失败但不影响 nohup 后台启动。装完后重启一次可得到干净回显 Service Start Success!。

Q5：查询 HZB_* 表报锁/占用错误？

服务仍在运行占用了 H2 文件。先 ./bin/shutdown.sh 再查（只读排障用）。

七、参考链接