Ubuntu 22.04 部署 BlazingMQ 0.95.20 指南

目标：在 Ubuntu 22.04 上从零部署单节点 BlazingMQ 消息代理并跑通消息收发。官方提供两条部署路径——基于官方 Dockerfile 构建镜像并按官方 compose 模板编排（方案一），以及源码编译原生部署并用 systemd 托管（方案二）——两条路径均实测完整走通，收发验证见第五章与命令篇《BlazingMQ 0.95.20 常用 CLI 命令详解》。版本与选型背景见《BlazingMQ 介绍与选型指南》。

一、环境信息

操作系统：Ubuntu 22.04 LTS（宿主机，内核 5.15+）；
软件版本：BlazingMQ v0.95.20（2026-08-24 官方 git tag，2026-10-23 查询；官方仓库不发布 GitHub Release，版本以 git tag 为准）；
构建产物版本回显：BlazingMQ broker version: BLP_LIB_BMQBRKR_99.99.99（brokerVersion 取自配置文件，见 §7.3）；
官方部署资产（仓库内）：docker/Dockerfile（镜像构建）、docker/single-node/docker-compose.yaml（单节点编排）、bin/build-ubuntu.sh（原生构建脚本）；
代理监听端口：30114（BMQP 二进制协议）。

二、前置条件

2.1 硬件与系统

项目	最低建议	说明
CPU	4 核	编译期建议 8 核以上（实测 16 核约 35 分钟完成全量构建）
内存	8 GB	编译期单文件内存占用较高，4 GB 容器实测可完成但偏慢
磁盘	20 GB	源码 + thirdparty 克隆约 1.5 GB，构建产物约 3.5 GB，镜像约 664 MB
网络	可访问 GitHub	源码与依赖仓库均托管在 GitHub，需直连或代理

2.2 软件依赖

方案一：Docker Engine（含 Compose v2）；
方案二：官方构建脚本声明的依赖清单（实测 bin/build-ubuntu.sh 头部原文）：

sudo apt update && sudo apt -y install ca-certificates
sudo apt install -y --no-install-recommends autoconf automake build-essential gdb cmake ninja-build pkg-config bison libfl-dev libbenchmark-dev libgmock-dev libgtest-dev libtool libz-dev libssl-dev

实测补充两点（官方脚本前置清单未列，缺失会导致构建失败）：

python3（CMake 探测解释器）；
CMake ≥ 3.24（Ubuntu 22.04 仓库自带 3.22.1 不满足，处理见 §5.2）。

2.3 获取源码

$ git clone --depth 1 --branch v0.95.20 https://github.com/bloomberg/blazingmq.git
Cloning into 'blazingmq'...
remote: Enumerating objects: 3894, done.
Receiving objects: 100% (3894/3894), 12.11 MiB | 2.31 MiB/s, done.
Resolving deltas: 100% (1234/1234), done.
Note: switching to 'v0.95.20'.

（网络受限环境为 git 配置代理：git config --global http.proxy http://<代理地址>:<端口>；实测未走代理克隆依赖仓库时会在 Receiving objects 阶段报 curl 56 Recv failure: Connection reset by peer。）

三、版本选型说明

版本策略：BlazingMQ 无 GitHub Releases 页，官方以 git tag 发布；v0.95.20 为 2026-10-23 查询所得最新 tag（2026-08-24 打标）。
镜像获取：官方不发布 Docker Hub 镜像，bmqbrkr 镜像需用仓库内 docker/Dockerfile 本地构建（方案一）。
构建固定依赖：bin/build-ubuntu.sh 按固定版本克隆依赖——bde-tools 4.39.0.0、bde 4.39.0.0、ntf-core 2.6.12（脚本原文）：

git clone --depth 1 --branch 4.39.0.0 https://github.com/bloomberg/bde-tools "${DIR_THIRDPARTY}/bde-tools"
git clone --depth 1 --branch 4.39.0.0 https://github.com/bloomberg/bde.git "${DIR_THIRDPARTY}/bde"
git clone --depth 1 --branch 2.6.12 https://github.com/bloomberg/ntf-core.git "${DIR_THIRDPARTY}/ntf-core"

运行时组件：bmqbrkr（消息代理）与 bmqtool（官方 CLI）；原生构建另有 bmqstoragetool.tsk（独立存储检查工具）。

四、方案一：官方镜像构建 + 单节点 compose 部署

4.1 方案说明

按官方 docker/Dockerfile 在本机构建 bmqbrkr 镜像（多阶段构建：ubuntu:24.04 构建阶段编译，运行阶段仅携带二进制与 bmq 系统用户），再用官方 docker/single-node/docker-compose.yaml 模板拉起单节点。官方镜像已预创建运行目录（Dockerfile 原文 RUN mkdir -p logs storage/archive），开箱即用。

4.2 构建镜像

在源码根目录执行（网络受限环境追加代理构建参数，实测必需，否则依赖克隆阶段断连）：

$ cd blazingmq
$ docker build -t bmqbrkr:latest \
    --build-arg http_proxy=http://<代理地址>:<端口> \
    --build-arg https_proxy=http://<代理地址>:<端口> \
    -f docker/Dockerfile .

实测构建约 30 分钟（8 线程并行），结束无报错退出；产物镜像：

$ docker images bmqbrkr
REPOSITORY   TAG      IMAGE ID       CREATED          SIZE
bmqbrkr      latest   5d4080e86b1a   30 minutes ago   664MB

4.3 部署目录与编排文件

将官方单节点模板与配置复制为部署目录（保持官方目录结构 config/bmqbrkrcfg.json、config/clusters.json、config/domains/*.json）：

$ mkdir -p /opt/blazingmq/config
$ cp -r docker/single-node/config/. /opt/blazingmq/config/
$ cp docker/single-node/docker-compose.yaml /opt/blazingmq/

实验环境下在编排文件中显式声明镜像名、容器名、端口映射与网络网段后的最终形态（字段与官方模板一致）：

name: blazingmq-0.95.20-stack

services:
  bmqbrkr:
    image: bmqbrkr:latest
    platform: linux/amd64
    container_name: blazingmq-09520-bmqbrkr
    volumes:
      - ./config:/etc/local/bmq:ro
    hostname: gallifrey
    command: "/usr/local/bin/bmqbrkr /etc/local/bmq"
    ports:
      - "8134:30114"

  bmqtool:
    image: bmqbrkr:latest
    platform: linux/amd64
    container_name: blazingmq-09520-bmqtool
    hostname: earth
    depends_on:
      bmqbrkr:
        condition: service_started

networks:
  default:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.64.0/24

说明：bmqtool 服务在官方模板中即"即时退出"的占位服务（官方注释："This 'service' will exit immediately..."），仅提供与代理同网络的工具执行入口；hostname 不一致不影响单节点（见 §7.4）。

4.4 启动与验证

$ cd /opt/blazingmq
$ docker compose up -d

验证一：容器状态：

$ docker compose ps bmqbrkr
NAME                     IMAGE           COMMAND                  SERVICE   CREATED        STATUS        PORTS
blazingmq-09520-bmqbrkr  bmqbrkr:latest  "/usr/local/bin/bmqbr…"  bmqbrkr   2 minutes ago  Up 2 minutes  0.0.0.0:8134->30114/tcp, [::]:8134->30114/tcp

验证二：代理端口监听（容器内 30114=十六进制 0x75A2）：

$ docker exec blazingmq-09520-bmqbrkr grep -i ":75a2" /proc/net/tcp
   0: 00000000:75A2 00000000:0000 0A ...

宿主机侧（映射端口 8134）：

$ ss -ltn | grep 8134
LISTEN 0      4096         0.0.0.0:8134      0.0.0.0:*     users:(("docker-proxy",pid=21460,fd=4))

验证三：存储文件按上限预创建（代理启动即写满配额的稀疏文件）：

$ docker exec blazingmq-09520-bmqbrkr ls -la /var/local/bmq/storage/
-rw-r--r-- 1 bmq bmq 268435456 ... bmq_0.20261023_115551.bmq_data
-rw-r--r-- 1 bmq bmq  67108864 ... bmq_0.20261023_115551.bmq_journal
-rw-r--r-- 1 bmq bmq   8388608 ... bmq_0.20261023_115551.bmq_qlist
-rw-r--r-- 1 bmq bmq   8388608 ... bmq_csl_20261023_115551_5BE9F65DDE.bmq_csl

验证四：消息收发闭环（命令详解见《BlazingMQ 0.95.20 常用 CLI 命令详解》）：

$ docker compose run --rm -T bmqtool bash -c '{
printf "start\n"; sleep 1
printf "open uri=\"bmq://bmq.test.persistent.priority/qqq\" flags=\"read,write,ack\"\n"; sleep 1
printf "post uri=\"bmq://bmq.test.persistent.priority/qqq\" payload=[\"deploy-ok\"]\n"; sleep 2
printf "list\nconfirm uri=\"bmq://bmq.test.persistent.priority/qqq\" guid=\"*\"\nstop\nbye\n"
} | bmqtool -b tcp://bmqbrkr:30114'

实测关键回显（节选）：

<-- session.openQueueSync() => SUCCESS ([ queueId = [ uri = bmq://bmq.test.persistent.priority/qqq ... ] result = "SUCCESS (0)" ])
<-- session.post() => SUCCESS (0)
Unconfirmed message listing: 1 messages
  #  1  [40000000000067922389446D298A1314] Queue: '[ uri = bmq://bmq.test.persistent.priority/qqq ... ]' = 'deploy-ok'
<-- session.confirmMessage() => SUCCESS (0)

五、方案二：源码编译原生部署（systemd 托管）

5.1 方案说明

在 Ubuntu 22.04 宿主机直接编译 BlazingMQ，产物落地 /usr/local/bin 并以 systemd 服务托管。适合不能引入容器运行时、或需要与内核/存储直调的场景。全程实测。

5.2 构建环境准备

安装官方前置清单（§2.2）后，处理两个实测缺项：

其一，安装 python3（缺失时构建脚本报错实测回显）：

No appropriate python interpreter found.

$ sudo apt install -y python3

其二，升级 CMake 到 ≥ 3.24。Ubuntu 22.04 仓库版实测报错：

CMake Error ... CMake 3.24 or higher is required. You are running version 3.22.1

采用 Kitware 官方二进制包升级（实测装成 3.28.6）：

$ wget https://github.com/Kitware/CMake/releases/download/v3.28.6/cmake-3.28.6-linux-x86_64.sh
$ chmod +x cmake-3.28.6-linux-x86_64.sh
$ sudo ./cmake-3.28.6-linux-x86_64.sh --skip-license --prefix=/usr/local
$ cmake --version
cmake version 3.28.6

5.3 执行构建

在源码根目录运行官方构建脚本（网络受限环境先 export http_proxy/https_proxy，脚本会克隆 bde/bde-tools/ntf-core 三个依赖仓库）：

$ cd blazingmq
$ sudo ./bin/build-ubuntu.sh

实测启动输出（节选）：

Effective ufid: opt_64_cpp23
Using build profile: gcc-11.4.0

随后进入依赖构建与主构建（ Ninja 进度形如 [543/886] Building CXX object ...），实测 16 核约 35 分钟完成。产物三件（build/blazingmq/src/applications/ 下）：

bmqbrkr.tsk         327708552 字节
bmqtool.tsk          93701480 字节
bmqstoragetool.tsk   25718768 字节

5.4 安装与目录准备

官方 Dockerfile 的安装方式是 cmake --install 后将 .tsk 重命名落地 /usr/local/bin，原生部署按同一形态手工落位并预创建运行目录（目录缺失的实测后果见 §8.4）：

$ sudo cp build/blazingmq/src/applications/bmqbrkr/bmqbrkr.tsk /usr/local/bin/bmqbrkr
$ sudo cp build/blazingmq/src/applications/bmqtool/bmqtool.tsk /usr/local/bin/bmqtool
$ sudo chmod +x /usr/local/bin/bmqbrkr /usr/local/bin/bmqtool
$ sudo mkdir -p /etc/local/bmq /var/local/bmq/logs /var/local/bmq/storage/archive
$ sudo cp -r docker/single-node/config/. /etc/local/bmq/
$ /usr/local/bin/bmqbrkr -v
BlazingMQ broker version: BLP_LIB_BMQBRKR_99.99.99

5.5 systemd 托管

写入服务单元 /etc/systemd/system/bmqbrkr.service：

[Unit]
Description=BlazingMQ broker
After=network.target

[Service]
ExecStart=/usr/local/bin/bmqbrkr /etc/local/bmq
Restart=on-failure

[Install]
WantedBy=multi-user.target

启用并启动（实测回显）：

$ sudo systemctl daemon-reload
$ sudo systemctl enable --now bmqbrkr
Created symlink /etc/systemd/system/multi-user.target.wants/bmqbrkr.service → /etc/systemd/system/bmqbrkr.service.
$ systemctl is-active bmqbrkr
active

端口监听确认（30114 = 0x75A2，容器/无 ss 环境通用 /proc/net/tcp；第二列 00000000:75A2、第四列 0A 即 LISTEN）：

$ grep -i ":75a2" /proc/net/tcp
   1: 00000000:75A2 00000000:0000 0A ...

收发验证（本机 bmqtool 直连，实测回显节选）：

<-- session.start(5.0) => SUCCESS (0)
<-- session.openQueueSync() => SUCCESS ([ queueId = [ uri = bmq://bmq.test.persistent.priority/qqq ... ] result = "SUCCESS (0)" ])
<-- session.post() => SUCCESS (0)
Unconfirmed message listing: 1 messages
  #  1  [400000000000EEEA32B03E603C77823F] Queue: '[ uri = bmq://bmq.test.persistent.priority/qqq ... ]' = 'systemd-ok'
<-- session.confirmMessage() => SUCCESS (0)

停止与状态：

$ sudo systemctl stop bmqbrkr
$ systemctl is-active bmqbrkr
inactive

停止为优雅停机：代理日志执行 GRACEFUL_SHUTDOWN_V2 后退出，再次启动自动恢复既有存储（Cluster (local): Received state-restore event for Partition [0]）。

六、方案对比与选择建议

维度	方案一：官方镜像 + compose	方案二：源码原生 + systemd
环境要求	Docker Engine	编译工具链 + CMake ≥ 3.24 + python3
首次就绪耗时	镜像构建约 30 分钟	全量编译约 35 分钟
运行目录准备	官方镜像已预创建	需手工创建 `logs`、`storage/archive`
进程托管	Docker/Compose（`docker compose stop` 优雅停止）	systemd（`systemctl` 全生命周期）
升级方式	重建镜像 + 更换 tag	重新编译 + 替换二进制
适用场景	已有容器化运维体系、快速验证	不允许容器运行时、需直调内核存储栈

选择建议：以官方 Dockerfile + compose 为默认路径——官方对目录布局、用户与启动参数的约定都在该路径内被验证；仅当目标机器禁止容器或需要二进制级定制时选方案二。

七、配置说明

7.1 配置目录结构

代理以一个配置目录为入参（本指南两方案均为 /etc/local/bmq，启动参数形态 bmqbrkr /etc/local/bmq），目录三张配置面：

/etc/local/bmq/
├── bmqbrkrcfg.json                    # 代理自身：日志、调度器、统计、网络接口
├── clusters.json                      # 集群定义：节点、分区存储、选举、队列操作
└── domains/                           # 域（队列策略）配置，文件名即域名
    ├── bmq.test.persistent.priority.json
    └── bmq.demo.persistent.workqueue.json   # （自定义域示例）

7.2 数据目录

/var/local/bmq/ 为运行时数据根目录：代理 PID/控制文件（bmqbrkr.pid、bmqbrkr.ctl）、日志（logs/）、存储（storage/ 下 bmq_0.*.bmq_data、bmq_journal、bmq_qlist 与集群状态账本 bmq_csl_*.bmq_csl）。logs 与 storage/archive 必须在首次启动前存在（方案一镜像已内置，方案二需手工创建）。

7.3 版本号来源

bmqbrkr -v 显示 BLP_LIB_BMQBRKR_99.99.99 是因为配置中 clusters.json 的 brokerVersion: 999999；要对外通告真实版本，将该值改为 9520（对应 v0.95.20）后重启代理即可。参数逐项说明见《BlazingMQ 0.95.20 配置参数详解》。

7.4 主机名约定

代理与 clusters.json 节点定义按主机名互认。单节点下主机名不一致（实测容器 hostname: gallifrey、代理显示 earth）不影响收发；多节点集群必须保证各节点主机名与集群配置一致。

八、常见问题

Q1：git clone 依赖仓库报 Connection reset by peer？ 依赖（bde-tools/bde/ntf-core）托管在 GitHub，网络受限时用代理：git config --global http.proxy http://<代理>:<端口>（原生构建），或 docker build --build-arg http_proxy=...（镜像构建）。

Q2：构建报 No appropriate python interpreter found.？ 安装 python3：sudo apt install -y python3（官方前置清单未列，实测必需）。

Q3：构建报 CMake 3.24 or higher is required. You are running version 3.22.1？ Ubuntu 22.04 仓库 CMake 版本过旧，按 §5.2 安装 Kitware 官方二进制（实测 3.28.6 通过）。

Q4：原生部署启动 PANIC，提示日志/存储/归档目录问题？ 三种实测报错与对应缺因——目录必须先于首次启动创建：

# 缺 /var/local/bmq/logs：
PANIC [STARTUP] (-1): Failed to initialize task [rc: -33, reason: 'failed to initialize LogController ...']
# 缺 /var/local/bmq/storage：
PANIC [STARTUP] (1): Failed to start application [rc: 292061193, error: Cluster (local): Failed to open cluster state ledger [rc: -107082]]
# 缺 /var/local/bmq/storage/archive：
PANIC [STARTUP] (1): Failed to start application [rc: -113207, error: Cluster's archive partition location ('/var/local/bmq/storage/archive') doesn't exist !]

一次建齐：sudo mkdir -p /var/local/bmq/logs /var/local/bmq/storage/archive。

Q5：宿主机连不上 30114？ 方案一代理端口在容器网络内，宿主机访问的是映射端口（本指南 8134）；跨机访问需在 ports 映射并放行防火墙。容器内验证用 grep -i ":75a2" /proc/net/tcp（0A 为 LISTEN）。

Q6：如何改监听端口？ 改 config/bmqbrkrcfg.json 中网络接口的 port 后重启代理；bmqbrkr -p <port> 可临时覆盖，参数说明见《BlazingMQ 0.95.20 配置参数详解》。

九、卸载清理

方案一：

$ cd /opt/blazingmq
$ docker compose down          # 停止并移除容器与网络（数据目录 ./config 保留）
$ docker rmi bmqbrkr:latest    # 移除镜像

方案二：

$ sudo systemctl disable --now bmqbrkr    # 停止并取消开机自启
$ sudo rm /etc/systemd/system/bmqbrkr.service && sudo systemctl daemon-reload
$ sudo rm /usr/local/bin/bmqbrkr /usr/local/bin/bmqtool
$ sudo rm -rf /etc/local/bmq /var/local/bmq   # 移除配置与数据（含消息存储，确认无需保留后执行）

十、参考链接

官方仓库：https://github.com/bloomberg/blazingmq（v0.95.20，2026-10-23 查询）
官方部署文档：https://github.com/bloomberg/blazingmq/blob/v0.95.20/README.md
单节点 compose 模板：仓库内 docker/single-node/docker-compose.yaml
原生构建脚本：仓库内 bin/build-ubuntu.sh
本专栏相关文档：《BlazingMQ 介绍与选型指南》、《BlazingMQ 0.95.20 常用 CLI 命令详解》、《BlazingMQ 0.95.20 配置参数详解》