BlazingMQ 0.95.20 配置参数详解

目标：逐项讲清 BlazingMQ 消息代理 bmqbrkr 的三张配置面——bmqbrkrcfg.json（代理自身）、clusters.json（集群与存储）、domains/*.json（域/队列策略）——并给出每一类参数的实测验证方法。全部参数值与回显均在 Ubuntu 22.04 + BlazingMQ v0.95.20 单节点环境实测取得（部署形态见 《Ubuntu 22.04 部署 BlazingMQ 0.95.20 指南》，版本与选型背景见 《BlazingMQ 介绍与选型指南》）。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（宿主与部署基准）；
• 软件版本：BlazingMQ v0.95.20（2026-08-24 官方 git tag，2026-10-23 查询；运行时 bmqbrkr -v 因官方示例配置中 brokerVersion: 999999 而显示 BLP_LIB_BMQBRKR_99.99.99，实际版本以构建所用 tag 为准）；
• 部署形态：官方单节点 compose 模板（服务 bmqbrkr + bmqtool），代理配置目录挂载到 /etc/local/bmq，数据目录 /var/local/bmq；
• 组件：bmqbrkr（消息代理）、bmqtool（官方 CLI）；
• 端口：30114（BMQP 协议端口，宿主侧映射 8134）；
• 配置来源：官方仓库 docker/single-node/config/ 下的三个配置面，本文全部参数均为该目录实测文件原值。

二、前置条件

• 已按部署篇完成单节点 bmqbrkr 运行（bmqbrkr 进程存在、30114 端口监听）；
• 会修改配置文件并重启代理（配置修改统一通过「编辑 JSON → 重启 bmqbrkr → 观察启动日志中的 Configuration 回显」闭环验证）；
• 了解 JSON 基本语法（配置文件全部为 JSON，语法错误会导致代理启动失败并在日志中报解析错误）。

三、参数查看与修改方式

3.1 配置目录结构

bmqbrkr 启动命令为 /usr/local/bin/bmqbrkr /etc/local/bmq——末尾参数即配置目录，代理从中读取三部分内容（实测目录清单）：

$ ls /etc/local/bmq/
bmqbrkrcfg.json
clusters.json
domains
$ ls /etc/local/bmq/domains/
bmq.demo.persistent.workqueue.json          # 本文实测自建的演示域
bmq.test.mem.broadcast.json
bmq.test.mem.fanout.json
bmq.test.mem.priority.json
bmq.test.persistent.fanout.json
bmq.test.persistent.fanout.sc.json
bmq.test.persistent.priority.json
bmq.test.persistent.priority.sc.json

三张配置面的分工：

3.2 修改与生效闭环（实测）

以日志级别为例（loggingVerbosity: INFO → DEBUG）：

1. 编辑 bmqbrkrcfg.json，将 taskConfig.logController.loggingVerbosity 改为 DEBUG；
2. 重启代理（部署篇 compose 形态执行 docker compose restart bmqbrkr；原生部署则重启对应进程）；
3. 启动日志会完整回显生效后的 Configuration（节选实测）：

23OCT2026_12:17:22.466 (136866141149056) INFO m_bmqbrkr_task.cpp:318 No memory allocation limit set!
    "loggingVerbosity": "DEBUG",

4. 效果对比：同为一分钟的运行日志行数，DEBUG 级别实测 616 行（INFO 基线约 30~40 行），日志级别修改即时可感知；
5. 验证完毕改回 INFO 并重启。

⚠️ 注意：启动日志中的 Configuration 回显是核对配置是否生效的第一手段——所有子键都会原样打印，改错位置（如改了别的层级同名键）会立刻暴露。

四、参数总览

bmqbrkrcfg.json 顶层两棵树：taskConfig（任务/日志基础设施）与 appConfig（代理应用配置）；clusters.json 顶层为 myClusters（集群数组）与 proxyClusters（代理节点集群，本环境为空数组）；域参数在 domains/*.json 的 definition.parameters 下。下表给出实测环境的关键参数速览：

4.1 内存上限参数的实测发现

示例配置带 allocatorType: STACKTRACETEST 与 allocationLimit: 34359738368（32GB）。启动日志实测：

23OCT2026_11:55:51.320 (124200649848704) INFO m_bmqbrkr_task.cpp:318 No memory allocation limit set!

同时启动头打印：

   ####################################
   # USING STACK TRACE TEST ALLOCATOR #
   ####################################

说明：STACKTRACETEST 是带栈回溯的调试型分配器；allocationLimit 在该组合下未实际启用（日志明示未设置内存上限）。生产部署建议将 allocatorType 调整为默认分配器并按需设置 allocationLimit，调试内存问题时再启用 STACKTRACETEST。

4.2 hostName 的解析要求

官方部署文档明确 hostName 必须是本机可解析的名字（localhost 亦可，任意编造值不行——代理会解析该名字）。实测环境 bmqbrkrcfg.json 中为 earth，而官方 compose 模板将容器主机名设为 gallifrey，单节点模式下代理正常启动（集群节点端点 clusters.json 里写的是 tcp://localhost:30114，与 hostName 解耦）；但在多节点集群中每台机器的 hostName 必须与实际主机名（或用 -h 覆盖值）一致且可解析，否则组网失败。选型建议：保持 hostName 与机器主机名一致，避免歧义。

五、核心参数分类详解（bmqbrkrcfg.json）

5.1 taskConfig.logController——日志系统

实测原值（节选）：

"logController": {
    "fileName": "/var/local/bmq/logs/logs.%T.%p",
    "fileMaxAgeDays": 10,
    "rotationBytes": 268435456,
    "logfileFormat": "%d (%t) %s %F:%l %m\n\n",
    "consoleFormat": "%d (%t) %s %F:%l %m\n",
    "loggingVerbosity": "INFO",
    "consoleSeverityThreshold": "INFO",
    "categories": [
        "BMQBRKR:INFO:green",
        "BMQ*:INFO:green",
        "MQB*:INFO:green"
    ],
    "syslog": {
        "enabled": false,
        "appName": "BMQ",
        "logFormat": "%d (%t) %s %F:%l %m\n\n",
        "verbosity": ""
    }
}

逐项说明：

• fileName：日志落盘模板，%T 展开为时间戳、%p 为进程号。实测生成 /var/local/bmq/logs/logs.20261023_115551.1，并伴随软链接 logs.last 指向当前日志；
• rotationBytes：268435456 = 256MB，单文件达到即轮转；
• fileMaxAgeDays：10 天，过期日志由内置清理任务删除（启动日志可见 bmqtsk_logcleaner 的清理记录：Cleaning files matching '/var/local/bmq/logs/logs.*.*' older than ... completed, 0 file(s) deleted）；
• logfileFormat/consoleFormat：BDE 日志格式串，%d 时间、%t 线程、%s 严重级别、%F:%l 文件:行号、%m 消息体；实测日志行样式：

23OCT2026_11:55:51.345 (124200649848704) INFO mqbnet_transportmanager.cpp:494 Creating new cluster 'local' ...

• loggingVerbosity：全局日志级别；改 DEBUG 的生效实测见第三章；
• consoleSeverityThreshold：控制台输出阈值（compose 形态下控制台即容器 stdout，docker logs 可见）；
• categories：分模块级别与颜色，BMQBRKR:INFO:green 表示代理核心模块 INFO 级绿色显示，通配 BMQ*、MQB* 覆盖客户端库与集群模块；
• syslog.enabled：是否转发 syslog（实测 false）；启用后 appName: BMQ 作为 syslog 标识。

5.2 appConfig.dispatcherConfig——内部调度器

实测原值（节选，三组同构）：

"dispatcherConfig": {
    "sessions": { "numProcessors": 4,
      "processorConfig": { "queueSizeLowWatermark": 100000,
                           "queueSizeHighWatermark": 200000,
                           "queueSize": 500000 } },
    "queues":   { "numProcessors": 8, "processorConfig": { ... 同上 } },
    "clusters": { "numProcessors": 4, "processorConfig": { ... 同上 } }
}

• numProcessors：会话/队列/集群三个事件类别的调度线程数（4/8/4）。队列事件线程最多（8），对应消息投递路径最重；
• queueSize*：调度队列的水位与上限（10 万/20 万/50 万条），高水位触发的背压与降速逻辑依赖这两个阈值；
• 调优方向：多队列高扇出场景可增大 queues.numProcessors；一般部署保持官方默认即可。

5.3 appConfig.stats——统计输出

实测原值：

"stats": {
    "snapshotInterval": 1,
    "printer": {
        "printInterval": 60,
        "file": "/var/local/bmq/logs/stat.%T.%p",
        "maxAgeDays": 3,
        "rotateBytes": 268435456,
        "rotateDays": 1
    }
}

• snapshotInterval: 1：每 1 秒做一次统计快照；
• printInterval: 60：每 60 秒打印一次统计表到 stat.%T.%p 文件（实测生成 stat.20261023_115551.1 与对应 .json 文件），统计表含 DOMAINQUEUES、CLIENTS、CLUSTERS、TCP CHANNELS 四大块（Put/Push/Ack/Confirm/Nack 计数与延迟）；
• maxAgeDays: 3/rotateBytes/rotateDays：统计文件保留 3 天、256MB 或 1 天轮转。

5.4 appConfig.networkInterfaces——网络与心跳

实测原值（节选）：

"networkInterfaces": {
    "heartbeats": {
        "client": 10, "downstreamBroker": 10,
        "upstreamBroker": 10, "clusterPeer": 10
    },
    "tcpInterface": {
        "name": "TCPInterface",
        "port": 30114,
        "ioThreads": 4,
        "maxConnections": 10000,
        "lowWatermark": 4194304,
        "highWatermark": 1073741824,
        "nodeLowWatermark": 5242880,
        "nodeHighWatermark": 10485760,
        "heartbeatIntervalMs": 3000
    }
}

逐项说明：

• heartbeats.*：四类链路（客户端、下游代理、上游代理、集群伙伴）的心跳间隔单位数（内部按心跳周期换算），均为 10；
• port: 30114：BMQP 监听端口，实测 /proc/net/tcp 中 00000000:75A2（0x75A2 = 30114）处于 LISTEN 状态；改动后记得同步修改 clusters.json 中的节点端点与宿主侧防火墙/映射；
• ioThreads: 4：网络 IO 线程数；
• maxConnections: 10000：最大并发连接；
• lowWatermark/highWatermark：写出缓冲水位（4MB/1GB），超过高水位会触发会话级流控；
• nodeLowWatermark/nodeHighWatermark：集群节点间链路水位（5MB/10MB）；
• heartbeatIntervalMs: 3000：TCP 层心跳间隔 3 秒。

六、核心参数分类详解（clusters.json）

6.1 集群与节点定义

实测原值（节选）：

"myClusters": [
    {
        "name": "local",
        "clusterAttributes": { "isCSLModeEnabled": false, "isFSMWorkflow": false },
        "nodes": [
            {
                "id": 0, "dataCenter": "UNSPECIFIED", "name": "localhost",
                "transport": { "tcp": { "endpoint": "tcp://localhost:30114" } }
            }
        ]
    }
]

• name：集群名；官方集群示例用 planets 等名字，队列 URI 中的第一段是域名而不是集群名，二者不要混淆；
• clusterAttributes.isCSLModeEnabled：是否启用集群状态账本（CSL）持久化模式；单节点示例为 false（实测数据目录仍生成了 bmq_csl_*.bmq_csl 文件用于状态账本）；
• nodes[].id：节点编号，多节点集群必须唯一且连续规划；
• nodes[].name：节点名，多节点场景须与其他机器 hostName 一致；
• nodes[].transport.tcp.endpoint：节点间通信端点，端口须与 tcpInterface.port 一致。

6.2 partitionConfig——分区与持久化

实测原值（节选）：

"partitionConfig": {
    "name": "local",
    "flushAtShutdown": true,
    "location": "/var/local/bmq/storage",
    "maxArchivedFileSets": 0,
    "maxDataFileSize": 268435456,
    "maxJournalFileSize": 67108864,
    "maxQlistFileSize": 8388608,
    "maxCSLFileSize": 8388608,
    "numPartitions": 1,
    "preallocate": false,
    "prefaultPages": false,
    "archiveLocation": "/var/local/bmq/storage/archive",
    "syncConfig": { "fileChunkSize": 0, "masterSyncMaxDurationMs": 0, "...": "其余同步参数全 0" }
}

• location：分区数据目录。实测启动后生成四个文件：

-rw-r--r-- 1 bmq bmq 268435456 ... bmq_0.20261023_115551.bmq_data     # 数据文件（256MB，与 maxDataFileSize 一致）
-rw-r--r-- 1 bmq bmq  67108864 ... bmq_0.20261023_115551.bmq_journal  # 事件日志（64MB）
-rw-r--r-- 1 bmq bmq   8388608 ... bmq_0.20261023_115551.bmq_qlist    # 队列表（8MB）
-rw-r--r-- 1 bmq bmq   8388608 ... bmq_csl_20261023_115551_5BE9F65DDE.bmq_csl  # 状态账本（8MB）

四个文件按 maxDataFileSize/maxJournalFileSize/maxQlistFileSize/maxCSLFileSize 预创建（preallocate: false 时按需增长、文件大小仍以上限为界——实测文件创建即为上限大小，是 BlazingMQ 存储文件的初始形态而非已占满）；

• flushAtShutdown: true：停机时刷盘（实测停机日志出现 Executing GRACEFUL_SHUTDOWN_V2，保证数据落盘）；
• numPartitions: 1：分区数；多分区可并行承载更多队列，域配置可将队列映射到指定分区；
• maxArchivedFileSets：归档文件集保留数（0 = 不归档）；archiveLocation 为归档目录；
• preallocate/prefaultPages：预分配与预缺页，均为 false，适合开发环境；生产可开启以稳定尾延迟；
• syncConfig：副本同步参数（文件块大小、各类超时），全 0 表示使用内部默认值。

6.3 elector——选举参数

实测原值（节选）：

"elector": {
    "electionResultTimeoutMs": 4000,
    "heartbeatBroadcastPeriodMs": 2000,
    "heartbeatCheckPeriodMs": 1000,
    "heartbeatMissCount": 10,
    "initialWaitTimeoutMs": 8000,
    "leaderSyncDelayMs": 80000,
    "maxRandomWaitTimeoutMs": 3000,
    "quorum": 0
}

单节点启动时选举一蹴而就（实测日志序列：DORMANT → FOLLOWER → CANDIDATE → 成为 leader，并输出 afterPartitionPrimaryAssignment: Partition [0]: new primary: [localhost, 0], primary status: E_ACTIVE）。多节点场景这几个超时共同决定故障切换速度：心跳 2 秒广播、1 秒检查、10 次未收到判定失联，即最坏约 20 秒感知节点故障；quorum: 0 表示由集群节点数推算法定人数。

6.4 queueOperations——队列操作超时

实测原值（节选）：

"queueOperations": {
    "ackWindowSize": 500,
    "assignmentTimeoutMs": 15000,
    "openTimeoutMs": 300000,
    "configureTimeoutMs": 300000,
    "closeTimeoutMs": 300000,
    "consumptionMonitorPeriodMs": 30000,
    "keepaliveDurationMs": 1800000,
    "reopenMaxAttempts": 10,
    "reopenRetryIntervalMs": 5000,
    "reopenTimeoutMs": 43200000,
    "shutdownTimeoutMs": 20000,
    "stopTimeoutMs": 10000
}

• ackWindowSize: 500：确认窗口，影响生产端在途确认的批量粒度；
• openTimeoutMs/configureTimeoutMs/closeTimeoutMs：三类队列操作超时均 5 分钟；
• keepaliveDurationMs: 1800000：30 分钟无活动队列的保活窗口；
• reopen*：客户端会话断线后队列重开策略（最多 10 次、间隔 5 秒、总上限 12 小时）；
• shutdownTimeoutMs/stopTimeoutMs：停机阶段各类收尾超时（20 秒/10 秒）。

6.5 clusterMonitorConfig 与 messageThrottleConfig

"clusterMonitorConfig": {
    "maxTimeLeader": 60, "maxTimeMaster": 120,
    "maxTimeNode": 120, "maxTimeFailover": 240,
    "thresholdLeader": 30, "thresholdMaster": 60,
    "thresholdNode": 60, "thresholdFailover": 120
},
"messageThrottleConfig": {
    "lowThreshold": 2, "highThreshold": 4,
    "lowInterval": 1000, "highInterval": 3000
}

• clusterMonitorConfig：集群状态机在各状态（leader/master/node/failover）的最大驻留时间与阈值（秒），用于健康监测与状态翻转判定；
• messageThrottleConfig：消息节流的双阈值（低 2/高 4，间隔 1 秒/3 秒），触发后对投递进行降速保护。

七、核心参数分类详解（domains/*.json——域与队列策略）

每个域一个 JSON 文件，文件名即域名。以官方预置的持久化优先级域 bmq.test.persistent.priority.json 为例（实测原值）：

{
    "definition": {
        "location": "local",
        "parameters": {
            "maxDeliveryAttempts": 0,
            "deduplicationTimeMs": 300000,
            "consistency": { "eventual": {} },
            "storage": {
                "config": { "fileBacked": {} },
                "domainLimits": {
                    "bytes": 2097152, "messages": 2000,
                    "bytesWatermarkRatio": 0.8, "messagesWatermarkRatio": 0.8 },
                "queueLimits": {
                    "bytes": 1048576, "messages": 1000,
                    "bytesWatermarkRatio": 0.8, "messagesWatermarkRatio": 0.8 }
            },
            "messageTtl": 300,
            "maxProducers": 0, "maxConsumers": 0, "maxQueues": 0, "maxIdleTime": 0,
            "mode": { "priority": {} }
        }
    }
}

逐项说明：

• 域名 = 文件名：bmq.test.persistent.priority.json → 队列 URI bmq://bmq.test.persistent.priority/<队列名>。实测自建域 bmq.demo.persistent.workqueue（内容将 mode 改为 {"priority": {}}、storage.config 用 fileBacked），重启代理后直接开队列收发成功：

<-- session.openQueueSync() => SUCCESS ([ queueId = [ uri = bmq://bmq.demo.persistent.workqueue/demoq ...
Unconfirmed message listing: 1 messages
  #  1  [400000000000773A77DABC7D89F46E62] Queue: '...' = 'hello workqueue domain'

• mode：路由模式，可选 priority（优先级队列）/ fanout（扇出，可带 appIDs 列表）/ broadcast（广播，至多一次）。官方预置的 fanout 域带 "appIDs": ["foo","bar","baz"]，fanout 队列须按 appId 订阅；
• storage.config：fileBacked（持久化落盘）或 inMemory（内存域，官方预置 bmq.test.mem.* 三个内存域）；内存域重启后消息消失，选型时注意；
• consistency：eventual（最终一致）或 strong（强一致，写多数派才确认）；官方另预置 .sc.json 后缀的强一致版本域（如 bmq.test.persistent.priority.sc.json）供对照；
• maxDeliveryAttempts：毒丸消息的最大投递次数（0 = 不限制，配合代理内置 poison pill 检测）；
• deduplicationTimeMs: 300000：生产者去重窗口 5 分钟；
• messageTtl: 300：消息默认存活 300 秒；
• domainLimits/queueLimits：域级与队列级容量限额（字节数、消息数、80% 高水位比）；超限后生产端会被拒绝（NACK）；
• maxProducers/maxConsumers/maxQueues：并发上限（0 = 不限）；把 maxConsumers 设为 1 即得到「工作队列」语义（多消费者争抢、逐条投递）；
• maxIdleTime：队列最大空闲时间（0 = 不限）。

💡 技术拓展：BlazingMQ 的「队列类型」由域参数组合决定，而不是像 RabbitMQ 那样在声明队列时选类型：mode.priority + maxConsumers>1 = 多消费者优先级队列；mode.priority + maxConsumers=1 = 工作队列（争抢）；mode.fanout = 扇出（各 appId 独立游标）；mode.broadcast = 广播（不落盘不缓冲）；storage.config=inMemory = 内存域（重启即失）。同一代理可以并存任意组合的域，按数据流重要性分别配置。

八、生产配置模板

适用场景：8~16GB 内存、SSD 磁盘、单节点验证/小规模生产（日均百万级消息、峰值数千连接）。在官方单节点配置基础上的推荐调整（均可在本文对应章节找到实测依据）：

// bmqbrkrcfg.json 关键项
"taskConfig": {
    "allocatorType": "DEFAULT",                       // 关闭调试分配器（实测 STACKTRACETEST 会在启动横幅告警）
    "logController": {
        "fileName": "/var/local/bmq/logs/logs.%T.%p",
        "loggingVerbosity": "INFO",                    // 排障时临时 DEBUG（实测日志量约 20 倍）
        "rotationBytes": 268435456,
        "fileMaxAgeDays": 10
    }
},
"appConfig": {
    "networkInterfaces": {
        "tcpInterface": {
            "port": 30114, "ioThreads": 4, "maxConnections": 10000
        }
    }
}

// clusters.json 关键项
"partitionConfig": {
    "location": "/var/local/bmq/storage",
    "numPartitions": 1,
    "preallocate": true,                               // 生产开启预分配，稳定尾延迟
    "flushAtShutdown": true
}

域策略模板：核心交易/状态类数据用 strong + fileBacked；日志类高吞吐数据用 eventual + 独立域名（如 bmq.app1.persistent.log）；广播类实时推送用 broadcast（接受消息丢失换最低延迟）。

九、常见问题

Q1：改了配置为什么没生效？ 配置只在启动时读取。按第三章闭环操作：编辑 → 重启代理 → 在启动日志的 Configuration 回显里核对实际生效值（该回显是完整 JSON 原文，所见即所得）。

Q2：启动日志报 ALARM [PLUGIN_MISSING] No plugin is enabled at all. 是错误吗？ 实测启动即出现该条：mqbplug_pluginmanager.cpp:318 ALARM [PLUGIN_MISSING] No plugin is enabled at all. Please double check if this is intended.。这是官方镜像未启用任何插件（如 Prometheus 插件）的提醒而非故障，单节点功能不受影响；需要监控插件时用 bin/build-ubuntu.sh --plugins prometheus 构建并在配置中启用。

Q3：bmqbrkr --help 为什么直接 PANIC？ 实测输出：The string "help" does not match any long tag. ... PANIC [STARTUP] Failed to parse command line，随后打印 usage。bmqbrkr 不支持 --help 长选项，查看用法直接运行 bmqbrkr（无参数）或看本专栏命令详解篇。

Q4：存储目录里的 .bmq_data 文件为什么一开始就是 256MB？ 这是按 maxDataFileSize 预创建的分区文件形态，不是已写满；实际占用以文件系统 du 为准。BlazingMQ 对消息做标记删除，整个文件集轮换回收（详见第七章/官方对比文档的存储模型说明）。

Q5：域文件加了但队列打开报域名不存在？ 确认三点：文件名与 URI 中域名完全一致；JSON 语法有效（一个多余的逗号都会导致解析失败）；修改后已重启代理（域文件在启动时加载，实测新增域重启后即可 open）。

十、参考链接

• 官方配置文档《Configuration》：https://bloomberg.github.io/blazingmq/docs/installation/configuration/
• 官方部署文档《Deployment》：https://bloomberg.github.io/blazingmq/docs/installation/deployment/
• 官方仓库单节点示例配置：https://github.com/bloomberg/blazingmq/tree/main/docker/single-node/config
• 本专栏部署篇：《Ubuntu 22.04 部署 BlazingMQ 0.95.20 指南》
• 本专栏命令篇：《BlazingMQ 0.95.20 常用 CLI 命令详解》
• 本专栏认知篇：《BlazingMQ 介绍与选型指南》