Apache BifroMQ 3.3.5 配置参数详解

目标：系统梳理 Apache BifroMQ 3.3.5 单机版的全部配置入口与参数：conf/standalone.yml（主配置）、启动脚本环境变量（堆与 JVM）、运行时 Setting（租户级动态参数）、系统属性（内部引擎调优），并给出生产模板与常见问题。所有默认值均取自实测环境（Ubuntu 22.04.5 + OpenJDK 17.0.20.1 + 3.3.5 standalone）启动时自动 dump 到 logs/info.log 的「Consolidated Config(YAML)」与「BifroMQ system properties」，为一手数据。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64），12 核，31GB 内存
• Apache BifroMQ：3.3.5（standalone 发行包）
• Java：OpenJDK 17.0.20.1
• 配置文件：/usr/share/bifromq/conf/standalone.yml
• 观察手段：logs/info.log 启动时全量 dump 整合配置（服务进程启动后合并了默认值与用户覆盖值的最终生效结果），是核对配置是否生效的第一手依据

二、前置条件

• 已按《Apache BifroMQ 3.3.5 安装指南》完成安装并能正常启动
• 了解 YAML 基本语法；修改配置后需重启进程生效（./bin/standalone.sh restart 或 systemctl restart bifromq）

三、参数查看与修改方式

💡 官方明示：standalone.yml 中只需写要覆盖默认值的项，未写的项使用内置默认；最终生效值以 info.log 的整合 dump 为准。3.3.x 各版本间配置项可能变化，升级时以 dump 为基准比对。

四、standalone.yml 主配置详解

4.1 服务引导与插件（文件级参数）

出厂文件（注释态）与实测整合值对照：

# 是否负责集群引导；3.3.0 起已废弃（deprecated），保留兼容
bootstrap: true

# 自定义鉴权提供器（实现 IAuthProvider 的插件类 FQN）
# 不配置时使用 DEV ONLY 演示实现
authProviderFQN: "com.baidu.demo.plugin.AllowAllAuthProvider"   # 出厂注释态
resourceThrottlerFQN: null   # 租户级资源限流提供器，null 用 DEV ONLY
settingProviderFQN: null     # 租户级动态设置提供器，null 用 DEV ONLY

说明：

• authProviderFQN：接入自建鉴权（认证 + PUB/SUB 授权）的入口。自带 demo 插件提供了基于 webhook 的演示实现 com.baidu.demo.plugin.DemoAuthProvider，需配合启动参数 -Dplugin.authprovider.url=http://<webhook地址>/ 提供回调（/auth、/check、/register）；未配置 webhook 时其兜底行为是拒绝所有检查请求。
• 三个 FQN 均通过 pf4j 扩展点解析：实现类必须位于 plugins/ 下插件 jar 内，并以 @Extension 注解注册（插件 jar 的 META-INF/extensions.idx 中列有实现类全名）。

4.2 集群配置（clusterConfig）

💡 单机模式无需改动本节；bootstrap: true + 空 seedEndpoints 即自引导单节点集群（内置 basekv 存储以单副本运行）。

4.3 MQTT 服务配置（mqttServerConfig）

实测整合值（12 核机器）：

4.4 四类监听器

tcpListener:            # MQTT over TCP
  enable: true
  host: "0.0.0.0"
  port: 1883
tlsListener:            # MQTT over TLS
  enable: false         # 默认关闭
  host: "0.0.0.0"
  port: 1884
  sslConfig: null       # 开启时需配 keystore/truststore
wsListener:             # MQTT over WebSocket
  enable: true
  host: "0.0.0.0"
  port: 8080
  wsPath: "/mqtt"
wssListener:            # MQTT over WSS
  enable: false         # 默认关闭
  host: "0.0.0.0"
  port: 8443
  wsPath: "/mqtt"
  sslConfig: null

实测要点：tcpListener.host 整合值为 0.0.0.0（全网卡监听）；8080 的 WebSocket 路径固定为 /mqtt。

4.5 管理 API（apiServerConfig）

接口清单（参数走 HTTP Header，非 JSON body）：POST /pub、POST /retain、GET /session、DELETE /session、DELETE /kill、PUT /sub、DELETE /unsub。

4.6 内部 RPC 与存储（一般无需改动）

各 store 通用引擎参数：manualCompaction、compactMinTombstoneKeys（200000）、compactMinTombstoneRanges（100000）、compactTombstoneRatio（0.3）、asyncWALFlush: true、fsyncWAL: false。

五、启动脚本环境变量（JVM 与目录）

实读 bin/bifromq-start.sh 归纳：

⚠️ 堆推导的优先级：显式 JVM_HEAP_OPTS > MEM_LIMIT 推导 > 本机总内存推导。31GB 内存的机器默认会拿 22GB 堆（实测 -Xms11217m -Xmx22435m），小规格务必显式约束。

六、运行时 Setting（租户级动态参数）

启动时全量 dump 在 info.log（Setting: <名>=<值>），可用 -D<名>=<值> 覆盖默认值。常用项（实测值）：

覆盖示例（追加到 EXTRA_JVM_OPTS 或 systemd 环境变量）：

EXTRA_JVM_OPTS="-DMaximumQoS=1 -DMaxUserPayloadBytes=65536 -DMsgPubPerSec=50"

七、系统属性（内部引擎调优，-D）

info.log 中「BifroMQ system properties」段全量 dump，核心项（实测值）：

八、生产配置模板

conf/standalone.yml（按需裁剪）：

mqttServerConfig:
  connTimeoutSec: 20
  maxMsgByteSize: 1048576        # 放宽到 1MB，按业务定
  defaultKeepAliveSec: 120
  tcpListener:
    enable: true
    host: "0.0.0.0"
    port: 1883
  # 生产建议启用 TLS
  # tlsListener:
  #   enable: true
  #   port: 8883
  #   sslConfig: { keystorePath: /etc/bifromq/server.p12, keystorePassword: "***" }

clusterConfig:
  env: "PROD"                    # 与其他环境隔离
  host: 192.168.1.11             # 显式指定本机地址
  port: 11000                    # seed 节点固定端口
  # 多节点时在其余节点配置:
  # seedEndpoints: "192.168.1.11:11000"

apiServerConfig:
  enable: true
  host: "0.0.0.0"                # 允许 127.0.0.1 访问
  httpPort: 8091
  # httpsListenerConfig:
  #   enable: true
  #   port: 8090

# 生产接入自建鉴权插件
authProviderFQN: "com.example.bifromq.plugin.MyAuthProvider"

配套 systemd（堆 256-512MB）：

[Service]
Environment="JVM_HEAP_OPTS=-Xms256m -Xmx512m"
Environment="EXTRA_JVM_OPTS=-DMaximumQoS=1 -Dingress_slowdown_heap_memory_usage=0.85"

九、常见问题

9.1 改了 standalone.yml 不生效

• 是否重启进程（该文件不支持热加载）；
• YAML 层级/缩进是否正确（如 mqttServerConfig.tcpListener.port 是两层嵌套）；
• 以 info.log 中「Consolidated Config(YAML)」dump 为准核对生效值，dump 里是什么就是什么。

9.2 8091 用 127.0.0.1 访问不通

apiServerConfig.host 默认取 site-local 地址。改 host: "0.0.0.0" 重启即可。

9.3 堆参数与预期不符

• 确认没有同时设置 JVM_HEAP_OPTS 和 MEM_LIMIT 造成理解混淆（前者精确、后者推导）；
• systemd 下 Environment= 值含空格必须整体加双引号，否则空格后内容被丢弃（实测 jps -v 只剩 -Xms）；
• 核对手段：jps -v | grep StandaloneStarter。

9.4 Setting 覆盖不生效

Setting 是 JVM 系统属性，要放在 -D 后（如 -DMaximumQoS=1），且随启动参数传入；检查 info.log 的 Setting: dump 段确认。

9.5 集群组不起来

• env 不一致（必须完全相同）；
• seedEndpoints 格式错误（应为 IP:PORT 逗号分隔，指向已固定 port 的种子节点）；
• 防火墙未放行 clusterConfig.port 与内部 RPC 端口（自动分配模式下重启会变，seed 节点务必固定端口）。

十、参考链接

• 配置手册：https://bifromq.io/docs/3.3.x/admin_guide/configuration/config_file_manual/
• Tuning 指南：https://bifromq.io/docs/3.3.x/admin_guide/tuning/
• Setting Provider：https://bifromq.io/docs/3.3.x/plugin/setting_provider/