Apache BifroMQ 3.3.5 常用 CLI 命令与工具详解

目标：汇总 Apache BifroMQ 3.3.5 日常运维最常用的命令与工具：官方启停脚本、systemd 服务管理、mosquitto 客户端联调、curl 调用管理 REST API、Prometheus 指标观测、进程/端口/日志诊断。全部命令与回显均在 Ubuntu 22.04.5 + OpenJDK 17.0.20.1 真实环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• Apache BifroMQ：3.3.5（standalone，安装于 /usr/share/bifromq）
• Java：OpenJDK 17.0.20.1（openjdk-17-jdk-headless）
• 客户端工具：mosquitto-clients 2.0.11、curl、net-tools（netstat）、procps（jps）
• 端口：MQTT 1883、WebSocket 8080、HTTP API 8091、Prometheus 9090

二、工具概览

三、前置条件

• 已按《Apache BifroMQ 3.3.5 安装指南》完成安装；
• 若安装 jps：apt-get install -y procps；若安装 mosquitto 客户端：apt-get install -y mosquitto-clients；若安装 netstat：apt-get install -y net-tools。

四、工具详解

4.1 standalone.sh 服务管理

cd /usr/share/bifromq
./bin/standalone.sh start

Using Java Version 17.0.20.1 locating at 'java'
Total Memory: 31 GB

com.baidu.bifromq.starter.StandaloneStarter process started: 4256

./bin/standalone.sh stop

Find StandaloneStarter process 4256, and stopping it
StandaloneStarter process 4256 was stopped

./bin/standalone.sh restart   # 停止后立即拉起
./bin/standalone.sh start -fg # 前台模式（日志直出终端，Ctrl+C 退出），调试用

要点：

• 用法为 {start|stop|restart} [-fg]，不带参数会打印 USAGE；
• stop 按进程名 StandaloneStarter 匹配 PID（ps | grep java）；
• 停止后可用 pgrep -af StandaloneStarter | wc -l 确认为 0；
• 堆与 JVM 参数通过环境变量传入（JVM_HEAP_OPTS、MEM_LIMIT 等，详见配置篇），如：

JVM_HEAP_OPTS="-Xms256m -Xmx512m" ./bin/standalone.sh start

4.2 systemd 服务管理（生产推荐）

按安装篇 4.8 节配置 /etc/systemd/system/bifromq.service 后：

systemctl start bifromq
systemctl is-active bifromq
systemctl restart bifromq
systemctl status bifromq --no-pager
systemctl enable bifromq    # 开机自启
journalctl -u bifromq -n 50 # 服务输出

实测回显：

active

配合 jps -v 核对堆参数：

jps -v | grep StandaloneStarter | grep -oE "\-Xms[0-9]+m \-Xmx[0-9]+m"

-Xms256m -Xmx512m

4.3 mosquitto_pub / mosquitto_sub MQTT 联调

基本收发（先订阅后发布）：

# 终端 1（订阅，-v 打印主题名）
mosquitto_sub -h 127.0.0.1 -p 1883 -t "demo/#" -v

# 终端 2（发布）
mosquitto_pub -h 127.0.0.1 -p 1883 -t demo/hello -m "hello-bifromq"

订阅端收到：

demo/hello hello-bifromq

QoS1 与 PUBACK 调试（-d）：

mosquitto_pub -h 127.0.0.1 -p 1883 -t demo/q1 -m "ack-test" -q 1 -d

Client (null) sending CONNECT
Client (null) received CONNACK (0)
Client (null) sending PUBLISH (d0, q1, r0, m1, 'demo/q1', ... (8 bytes))
Client (null) received PUBACK (Mid: 1, RC:0)
Client (null) sending DISCONNECT

保留消息（-r）与新订阅者重投递（-C 1 收一条即退）：

mosquitto_pub -h 127.0.0.1 -p 1883 -t demo/ret -m "last-state" -q 1 -r
mosquitto_sub -h 127.0.0.1 -p 1883 -t "demo/ret" -C 1 -W 4

last-state

MQTT 5.0（-V mqttv5，可看到失败原因码）：

mosquitto_sub -h 127.0.0.1 -p 1883 -t "demo/5" -V mqttv5 -d

正常订阅 Subscribed (mid: 1): 0（0 即成功；若见 128 为 Not authorized，需排查 /tmp noexec 等问题，见安装篇常见问题 6.1）。

带用户名/密码与固定客户端 ID：

mosquitto_sub -h 127.0.0.1 -p 1883 -u testuser -P testpass -i my-client-01 -t "demo/u" -v

WebSocket 接入（8080，路径 /mqtt）：

mosquitto_pub -h 127.0.0.1 -p 8080 --protocol-version websockets -t demo/ws -m "via-ws"

4.4 curl 调用管理 REST API（8091）

⚠️ 两个实测要点：① 3.3.x 的接口参数走 HTTP Header（req_id、tenant_id、topic、qos、client_type 必需，client_meta_* 至少一个），报文体即消息 payload，不是 JSON body；② 8091 默认绑定 site-local 地址，先用 ip addr 确认本机地址，或把 apiServerConfig.host 改为 0.0.0.0。

发布消息（POST /pub）：

curl -X POST http://172.17.0.3:8091/pub \
  -H "req_id: 710000031" -H "tenant_id: bifromq" -H "topic: rest/verify" \
  -H "qos: 0" -H "client_type: curl" -H "client_meta_lang: zh" \
  --data-binary "rest-pub-works"

NO_MATCH

HTTP 200 + NO_MATCH = 发布成功但无匹配订阅者（有订阅者时返回 OK）。

设置/清除保留消息（POST /retain）：

curl -X POST http://172.17.0.3:8091/retain \
  -H "req_id: 710000032" -H "tenant_id: bifromq" -H "topic: rest/ret" \
  -H "qos: 1" -H "client_type: curl" -H "client_meta_lang: zh" \
  --data-binary "retained-via-rest"
# 清除保留消息：body 置空（--data-binary ""）

查询会话（GET /session）：

curl -s -o /dev/null -w "%{http_code}\n" -X GET "http://172.17.0.3:8091/session" \
  -H "tenant_id: bifromq" -H "user_id: u1" -H "client_id: not-exist"

404

404 = 该 user/client 无会话（服务存活探测常用此接口）。查存在的会话返回 200。

批量过期会话（DELETE /session）：header tenant_id 必带，expiry_seconds 可选（0 表示清理租户下全部会话，慎用）。

断开客户端连接（DELETE /kill）：按 tenant_id（+可选 user_id、client_id）踢下线，需 client_type 与 client_meta_*。

为已存在会话增删订阅（PUT /sub、DELETE /unsub）：headers 需 tenant_id、user_id、client_id、topic_filter、sub_qos（unsub 无 sub_qos）。对不存在的会话实测返回：

404

（语义：No session found for the given user and client ID。）

4.5 Prometheus 指标观测（9090）

curl -s http://127.0.0.1:9090/metrics | head -3

# HELP basekv_balance_scheduled_total
# TYPE basekv_balance_scheduled_total counter

常用指标过滤：

curl -s http://127.0.0.1:9090/metrics | grep -E "basecluster_health|basecluster_agent_members"
curl -s http://127.0.0.1:9090/metrics | grep -E "mqtt_|inbox_" | head -10

要点：

• 指标由内置 demo 插件导出（插件日志 Prometheus exporter started on port 9090）；
• 关键指标：basecluster_healthScore（成员健康分）、basecluster_agent_members（各服务成员数，单机应为 1）、basekv_le_ranges（存储 range）、ppln_error_count_total（RPC 管道错误）。

4.6 进程、端口与日志诊断

进程与 JVM 参数：

jps -l                    # 列出 JVM 进程主类
jps -v | grep Standalone  # 完整 JVM 参数（核对堆/GC/系统属性）
pgrep -af StandaloneStarter

15597 com.baidu.bifromq.starter.StandaloneStarter

端口监听：

netstat -lntp | grep java

tcp6  0  0 :::9090          :::*  LISTEN  15597/java
tcp6  0  0 172.17.0.3:8091  :::*  LISTEN  15597/java
tcp6  0  0 :::8080          :::*  LISTEN  15597/java
tcp6  0  0 :::1883          :::*  LISTEN  15597/java

日志文件速查：

cd /usr/share/bifromq/logs
grep -E "MQTT broker started|API server started" info.log   # 启动完成标志
grep -c ERROR error.log                                     # 错误计数
tail -f info.log                                            # 实时主日志
ls basekv/                                                  # 内置存储组件日志

info.log 两个高价值 dump 段（启动时输出一次）：

• Consolidated Config(YAML): —— 全部配置最终生效值；
• Setting: / BifroMQSysProp: —— 全部运行时参数与系统属性。

OOM 排障：默认 GC 参数带 -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=<logs 目录> 与 -Xlog:gc:file=<logs>/gc-%t.log，堆转储与 GC 日志都在 logs/ 下。

五、注意事项

• standalone.sh 需在其安装目录执行或用绝对路径调用（脚本内部按 $0 推导 BASE_DIR）；
• stop 依赖进程名匹配，多实例部署在同一机器时注意会连带停止；
• -fg 前台模式用于调试，生产用 systemd（Type=forking）；
• REST API 的 req_id 建议传 int64 自增值便于服务端日志追踪；
• 9090/8091 端口由 demo 插件与 API 服务提供，若 plugins/ 下插件变更，端口行为可能不同。

六、常见问题

6.1 jps 命令不存在

未装 procps：apt-get install -y procps。若用 JRE-only 环境（无 JDK），jps 缺失，可用 ps aux | grep StandaloneStarter 替代。

6.2 standalone.sh stop 报找不到进程但服务仍在

脚本是按 ps | grep StandaloneStarter | grep java 找 PID；若启动时改过主类（如直接调 bifromq-start.sh -c 其他类）会匹配不到，此时用 pgrep -af java 手工定位后 kill <pid>。

6.3 curl 8091 返回 000 / Connection refused

8091 绑定的是 site-local 地址不是 127.0.0.1（netstat 可见 172.17.0.3:8091）。改用本机实际 IP，或在 standalone.yml 设 apiServerConfig.host: "0.0.0.0" 重启。

6.4 mosquitto_sub 订阅返回 128

多为内部 dist 子系统异常。先看 stdout.log 是否有 netty 原生库 cannot be executed ... "noexec" flag 告警：/tmp 若以 noexec 挂载，mount -o remount,exec /tmp 后重启即可（实测根因，详见安装篇 6.1）。

6.5 REST 发布返回 400

参数必须全部放 Header：缺 tenant_id、topic、qos、client_type 或 client_meta_* 之一都会 400；报文体不要包 JSON。

6.6 启动卡在存储引导后才可连接

启动后 30~60 秒内 inbox/retain/dist 引导完成前，连接可能失败或订阅受限；以 info.log 出现 MQTT broker started 为准再联调。

七、参考链接

• 官网文档（3.3.x）：https://bifromq.io/docs/3.3.x/
• HTTP API Reference：https://bifromq.io/docs/3.3.x/user_guide/api/api_reference/
• Observability：https://bifromq.io/docs/3.3.x/admin_guide/observability/