消息中间件这块，我踩过的坑比吃过的盐还多。早些年做物联网设备接入，设备端清一色用 MQTT 协议上报数据，后端服务又跑在 JMS 体系上，两边协议对不上，中间得有个桥接层。当时试过不少方案，最后落到 ActiveMQ 上——它原生支持 MQTT 协议，又能跟 JMS 无缝互通，算是把设备侧和后端服务侧粘起来了。但单机版 ActiveMQ 扛不住设备量上来之后的连接数和消息吞吐，必须上集群。而集群部署这件事，用 Docker 来做是最省心的，环境隔离、版本锁定、快速重建，这三点在测试和生产环境里都太重要了。

这篇内容就是把我自己搭 ActiveMQ + MQTT 集群（Docker 版本）的完整过程拆开来讲，从架构选型、网络规划、镜像配置、集群组网、MQTT 接入验证，到后面踩过的坑和排查手法，全部摊开。适合谁看？如果你正在做物联网平台、设备接入网关、或者任何需要 MQTT 协议接入又要跟 JMS 生态打通的场景，这篇能直接抄作业。哪怕你只是刚接触 ActiveMQ 集群，跟着步骤走也能跑起来。我会把每一步为什么这么做讲清楚，参数怎么算、配置为什么这么写，都说明白，不搞那种“照着敲就行”的黑盒教程。

1. 集群架构设计与方案选型

1.1 为什么选 ActiveMQ 而不是别的

先说选型这件事。MQTT Broker 市面上不少，但我们的约束条件比较特殊：后端有一批老服务跑在 JMS 上，用的是 ActiveMQ 的队列和主题，短期内不可能全部重写。如果引入一个纯 MQTT Broker，就得在中间再加一层协议转换，多一个组件就多一个故障点，运维成本也上去了。ActiveMQ 自带 MQTT 协议支持（基于 MQTT 3.1.1），设备端直接连上来就能发消息，后端 JMS 消费者通过 Virtual Topic 或者 Network Connector 就能拿到数据，链路短、组件少。

另一个考量是持久化和消息可靠性。ActiveMQ 支持 KahaDB 和 JDBC 两种持久化方式，集群模式下配合共享存储或者网络桥接，能做到消息不丢。MQTT 的 QoS 1 和 QoS 2 在 ActiveMQ 上都有对应实现，虽然性能上不如一些专用 Broker，但对于中等规模的设备接入（几千到几万连接）完全够用。我实测下来，单节点 ActiveMQ 在 4 核 8G 的机器上，MQTT 连接数稳定在 8000 左右，消息吞吐在 QoS 1 下大概每秒 3000 到 5000 条，集群横向扩展后能线性提升。

还有一点是社区和文档。ActiveMQ 虽然不算最时髦的，但它的集群方案成熟，Network of Brokers 这套东西用了十几年，坑都被踩得差不多了，遇到问题搜一下基本都有答案。相比之下，一些新兴 Broker 的集群方案还在快速迭代，生产环境用起来心里没底。

1.2 集群模式怎么选：Network of Brokers 还是主从

ActiveMQ 的集群主要有两种玩法：Network of Brokers（Broker 网络）和Master-Slave（主从）。这两者解决的是不同问题，很多人一开始会搞混。

Network of Brokers 的核心是多个 Broker 互相连接，消息可以在 Broker 之间流转。客户端连到任意一个 Broker，消息都能被路由到目标消费者所在的 Broker。这种模式解决的是负载均衡和横向扩展问题——连接数分散到多个节点，消息吞吐也能分摊。但它本身不解决高可用，如果某个 Broker 挂了，连在它上面的客户端会断连（需要重连到其他节点）。

Master-Slave 的核心是主节点对外服务，从节点实时同步数据，主节点挂了从节点接管。这种模式解决的是高可用问题，但同一时刻只有一个节点在干活，扩展性有限。

实际生产里，这两种模式经常组合使用：每个 Master-Slave 对作为一个高可用单元，多个单元之间再用 Network of Brokers 组网。但这样架构复杂度上来了，运维成本也高。对于我们这种中等规模场景，我选择的是纯 Network of Brokers 模式，配合客户端的自动重连机制来兜底。理由很简单：设备端 MQTT 客户端本身就带重连逻辑，Broker 挂掉后设备重连到其他节点，消息在 QoS 1 下由客户端重发，业务上能接受短暂的消息延迟。这样架构简单，扩展性好，运维负担小。

提示：如果你的业务对消息零丢失有硬性要求，且不能接受任何重连窗口，那就得上 Master-Slave + 共享存储（JDBC 或 LevelDB 复制），代价是架构复杂度和运维成本大幅上升。选型时一定要结合业务的实际容忍度来定，别为了“高可用”三个字过度设计。

1.3 Docker 化部署的考量

用 Docker 部署 ActiveMQ 集群，核心要解决三个问题：网络互通、配置管理、数据持久化。

网络互通方面，多个 Broker 容器之间需要互相发现和通信，用 Docker 的自定义 bridge 网络最合适，容器之间可以通过容器名直接解析。配置管理方面，ActiveMQ 的配置文件（activemq.xml、jetty.xml 等）需要针对每个节点做差异化调整（比如 brokerName、端口），我采用的方式是挂载宿主机目录，每个节点一份独立配置，避免容器内修改丢失。数据持久化方面，KahaDB 的数据目录必须挂载到宿主机，否则容器重建数据就没了。

镜像选择上，官方apache/activemq-classic镜像就够用，版本锁定在 5.18.x（写这篇时 5.18 是稳定版）。不建议用 latest 标签，生产环境版本必须锁死，不然某天拉下来一个新版本，配置不兼容就麻烦了。

2. 环境准备与基础配置

2.1 宿主机环境与目录规划

我用的测试环境是三台虚拟机，每台 4 核 8G，CentOS 7 系统，Docker 版本 20.10 以上。三台机器分别跑一个 Broker 节点，组成一个三节点的 Network of Brokers。为什么是三节点？两个节点的话，挂一个就剩单点，三个节点挂一个还剩两个，集群还能正常运转，这是最小的高可用组网规模。

目录规划上，每台机器上建一个统一的工作目录，结构如下：

/opt/activemq-cluster/ ├── node1/ │ ├── conf/ │ │ ├── activemq.xml │ │ ├── jetty.xml │ │ └── login.config │ └── data/ └── docker-compose.yml

conf目录放该节点的配置文件，data目录挂载 KahaDB 数据。三台机器上目录结构一致，只是 node 编号不同。这样规划的好处是，配置和数据分离，迁移或者备份的时候直接打包目录就行，容器本身是无状态的。

注意：data目录的权限要设好，ActiveMQ 容器内默认以 uid 1000 运行，宿主机目录如果权限不对，容器启动会报错“Permission denied”。我一般直接chown -R 1000:1000 /opt/activemq-cluster/node1/data，省得后面排查。

2.2 Docker 网络规划

三台机器跨主机组网，Docker 默认的 bridge 网络只能单机内容器互通，跨主机不行。这里有两个选择：一是用 Docker Swarm 的 overlay 网络，二是用宿主机的 host 网络模式。我选的是host 网络模式，理由很直接：ActiveMQ 的 Network Connector 需要 Broker 之间建立 TCP 连接，用 host 模式的话，容器直接使用宿主机 IP 和端口，配置里写宿主机 IP 就行，不用折腾 overlay 网络的端口映射和 MTU 问题。而且 host 模式下网络性能损耗最小，对消息吞吐有好处。

用 host 模式要注意端口冲突。每个 Broker 节点需要占用这几个端口：61616（OpenWire，JMS 用）、1883（MQTT）、8161（Web 控制台）、61613（STOMP，可选）。三台机器各跑一个节点，端口不冲突，因为 IP 不同。但如果单机上想跑多个节点做测试，就得改端口了，这个后面会讲。

2.3 镜像拉取与版本锁定

docker pull apache/activemq-classic:5.18.3

拉完之后打个本地标签，方便引用：

docker tag apache/activemq-classic:5.18.3 activemq-cluster:5.18.3

版本锁定这件事我要多嘴一句。ActiveMQ 5.17 到 5.18 之间有一些配置项的变化，比如 Web 控制台的认证配置方式调整过。如果你不锁版本，某天 CI/CD 流水线拉了个新版本，启动直接报配置解析错误，排查起来很浪费时间。生产环境必须锁死到具体的小版本号。

3. 核心配置文件拆解

3.1 activemq.xml 的关键改动

ActiveMQ 的核心配置都在activemq.xml里。默认配置文件直接拿来用也能跑，但要组集群、要开 MQTT，得改几个地方。我以 node1 为例，把关键段落拆开讲。

broker 标签的 brokerName 和 persistent 属性：

<broker xmlns="http://activemq.apache.org/schema/core" brokerName="broker-node1" dataDirectory="${activemq.data}" persistent="true">

brokerName每个节点必须唯一，这是集群里识别节点的标识。persistent="true"开启持久化，KahaDB 会把消息写到磁盘，Broker 重启后消息不丢。如果设成 false，消息只在内存里，重启就没了，生产环境绝对不能这么干。

KahaDB 持久化配置：

<persistenceAdapter> <kahaDB directory="${activemq.data}/kahadb" journalMaxFileLength="32mb" checkpointInterval="5000"/> </persistenceAdapter>

journalMaxFileLength默认是 32mb，我保持默认。这个值调大能减少文件切换频率，但恢复时间会变长；调小则相反。checkpointInterval是检查点间隔，默认 5000ms，意思是每 5 秒把内存里的索引刷到磁盘。这个值影响消息写入的可靠性，调小更安全但性能略降，5000 是个平衡点。

MQTT 协议传输通道：

<transportConnectors> <transportConnector name="openwire" uri="tcp://0.0.0.0:61616"/> <transportConnector name="mqtt" uri="mqtt://0.0.0.0:1883"/> <transportConnector name="ws" uri="ws://0.0.0.0:61614"/> </transportConnectors>

mqtt://0.0.0.0:1883这行是开 MQTT 支持的关键。0.0.0.0表示监听所有网卡，host 网络模式下这样写没问题。如果只想监听特定网卡，改成对应 IP 即可。注意 MQTT 的 URI scheme 是mqtt://，不是tcp://，写错了启动会报协议不支持。

Network Connector 集群组网：

<networkConnectors> <networkConnector name="nc-to-node2" uri="static:(tcp://192.168.1.12:61616)" duplex="true" networkTTL="2"/> <networkConnector name="nc-to-node3" uri="static:(tcp://192.168.1.13:61616)" duplex="true" networkTTL="2"/> </networkConnectors>

这是集群的核心。uri里写其他节点的地址，static:前缀表示静态配置（也可以用multicast:做自动发现，但生产环境建议静态配置，可控性强）。duplex="true"表示双向连接，node1 连 node2 的同时，node2 也能通过这条连接把消息推给 node1，这样只需要在一个方向配 connector 就行，不用两边都配。networkTTL="2"是消息在网络里转发的最大跳数，三节点集群设 2 足够，设大了可能导致消息在网络里绕圈。

提示：duplex="true"虽然方便，但要注意如果两个节点互相都配了 duplex connector，会建立两条连接，造成重复。我的做法是只在“编号小的节点”上配到“编号大的节点”的连接，比如 node1 配到 node2 和 node3，node2 配到 node3，node3 不配。这样连接关系是单向发起的，但因为是 duplex，消息双向都能走，不会重复。

3.2 jetty.xml 与 Web 控制台

Web 控制台默认端口 8161，默认账号密码是 admin/admin。生产环境必须改密码，改的地方在jetty.xml和jetty-realm.properties。jetty.xml里控制端口和绑定地址：

<bean id="jettyPort" class="org.apache.activemq.web.WebConsolePort"> <property name="host" value="0.0.0.0"/> <property name="port" value="8161"/> </bean>

jetty-realm.properties里改账号：

admin: NewPassword123, admin

格式是用户名: 密码, 角色。改完重启生效。Web 控制台在排查集群状态时很有用，能看到各节点的连接数、队列深度、消费者情况，建议每个节点都开着，用不同端口或者不同 IP 访问。

3.3 单机多节点测试配置

如果手头只有一台机器，想跑三个节点做测试，就得改端口。每个节点的端口分配如下：

对应的activemq.xml里 transportConnector 的端口要改，jetty.xml里 Web 端口也要改。Network Connector 的 uri 里写tcp://宿主机IP:对应端口。这种配置只适合测试，生产环境还是建议多机部署，避免单机资源竞争。

4. 集群搭建实操全流程

4.1 编写 docker-compose.yml

我用 docker-compose 来管理容器，虽然跨主机部署时 compose 不能直接跨机器编排，但每台机器上跑一个 compose 文件管理本机节点，配合统一的配置模板，操作起来很顺手。node1 的 compose 文件如下：

version: '3.8' services: activemq-node1: image: activemq-cluster:5.18.3 container_name: activemq-node1 network_mode: host volumes: - /opt/activemq-cluster/node1/conf:/opt/apache-activemq/conf - /opt/activemq-cluster/node1/data:/opt/apache-activemq/data environment: - TZ=Asia/Shanghai restart: unless-stopped logging: driver: json-file options: max-size: "50m" max-file: "3"

几个关键点说明。network_mode: host让容器直接用宿主机网络，省去端口映射的麻烦。volumes把配置和数据挂载出来，容器重建不丢数据。restart: unless-stopped保证容器异常退出后自动拉起，但手动 stop 的不会自动重启，这个策略比always更可控。日志限制大小，防止磁盘被日志撑爆——ActiveMQ 的日志量不小，不限制的话几天就能写满几十 G。

node2 和 node3 的 compose 文件类似，只是container_name和挂载路径不同。三台机器上分别执行docker-compose up -d，容器就起来了。

4.2 启动顺序与集群验证

启动顺序有讲究。先启动 node1，等它完全起来（日志里出现 “ActiveMQ Console ready” 之类的字样），再启动 node2，最后 node3。为什么？因为 Network Connector 在启动时会尝试连接配置里的其他节点，如果目标节点还没起来，连接会失败并重试。虽然 ActiveMQ 有重连机制，但启动顺序对了能减少日志里的报错噪音，排查问题时更清爽。

三个节点都起来后，验证集群是否正常。最直接的方式是看 Web 控制台。访问 node1 的 8161 端口，进 Connections 页面，应该能看到来自 node2 和 node3 的连接（Network Connector 建立的连接会显示为 “Network” 类型的连接）。再看 node2 和 node3 的控制台，确认连接关系对称。

另一个验证方式是发消息测试。在 node1 上创建一个队列test.cluster，用控制台的 “Send” 功能发一条消息，然后在 node2 上查看同一个队列，如果消息能出现（取决于消费者位置和消息路由），说明集群路由正常。更严谨的验证是起一个消费者连 node2，往 node1 发消息，看消费者能不能收到——这个后面用 MQTT 客户端做完整验证。

4.3 MQTT 接入验证

MQTT 接入验证我用的是mosquitto_pub和mosquitto_sub这两个命令行工具，轻量好用。先起一个订阅者，连到 node2 的 1883 端口：

mosquitto_sub -h 192.168.1.12 -p 1883 -t "sensor/temperature" -q 1 -v

-q 1指定 QoS 1，-v打印主题名。然后往 node1 发消息：

mosquitto_pub -h 192.168.1.11 -p 1883 -t "sensor/temperature" -m "25.6" -q 1

如果订阅者能收到sensor/temperature 25.6，说明消息从 node1 的 MQTT 通道进来，经过 Network Connector 路由到 node2，再推给订阅者，整条链路通了。这一步验证的是 MQTT 协议接入 + 集群消息路由的组合，是最关键的验证点。

注意：MQTT 主题在 ActiveMQ 里默认映射为 Topic（不是 Queue）。如果你希望 MQTT 消息进队列，需要在activemq.xml里配置mqtt传输通道的topic转queue策略，或者用 Virtual Topic。默认的 Topic 语义下，订阅者必须先在线才能收到消息（除非用持久订阅）。设备接入场景一般用持久订阅（cleanSession=false），这样设备离线期间的消息会在重连后补发。

5. 常见问题与排查实录

5.1 集群连接建立失败

最常见的问题是 Network Connector 连不上。日志里会出现Could not connect to broker之类的报错。排查顺序是这样的：先在宿主机上telnet 目标IP 61616，确认端口通不通；端口通了但还连不上，检查目标节点的activemq.xml里 transportConnector 是否监听了正确的地址（0.0.0.0还是特定 IP）；再检查防火墙规则，CentOS 默认的 firewalld 可能挡了 61616 端口。

还有一种隐蔽的情况：容器用 host 网络模式，但activemq.xml里 transportConnector 写的是tcp://localhost:61616，这样只监听回环地址，其他机器连不进来。必须写0.0.0.0或者宿主机实际 IP。

5.2 消息在集群里不路由

消息发了但消费者收不到，可能的原因有几个。一是 Network Connector 的networkTTL设太小，消息跳数不够。三节点集群里，消息从 node1 到 node3 需要 2 跳，如果 TTL 设成 1，就到不了。二是 durable subscription 的问题，MQTT 持久订阅在集群里的行为需要确认订阅关系是否同步到了所有节点。三是消息的 destination 类型不匹配，生产者发到 Topic，消费者监听 Queue，自然收不到。

排查时先看 Web 控制台的队列/主题深度，确认消息到底进了哪个 destination；再看 Network Connector 的状态，确认连接是 active 的；最后用activemq browse命令直接查看队列里的消息内容，定位问题在哪一环。

5.3 容器启动报权限错误

前面提过，data目录权限不对会报Permission denied。除了 chown 到 1000，还有一种情况是宿主机开了 SELinux，即使权限对了，容器也访问不了挂载目录。临时验证可以setenforce 0关掉 SELinux，但生产环境不建议直接关，正确的做法是给目录打上 SELinux 标签：chcon -Rt svirt_sandbox_file_t /opt/activemq-cluster/node1/data。

5.4 常见问题速查表

5.5 几个踩过的坑

第一个坑是KahaDB 锁文件。容器异常退出后，KahaDB 目录里可能残留lock文件，下次启动报 “KahaDB is locked”。解决方法是删掉data/kahadb/lock文件再启动。但要注意，这个操作只能在确认没有其他进程在用这个数据目录时做，否则可能损坏数据。

第二个坑是MQTT 客户端 ID 冲突。两个设备用同一个 clientId 连上来，后连的会把先连的踢掉，表现为设备频繁掉线。排查时看 Broker 日志里的 “Client already connected” 警告。解决方法是确保每个设备的 clientId 唯一，一般用设备序列号或者 MAC 地址。

第三个坑是Network Connector 的 duplex 重复连接。前面提过，如果两个节点互相都配了 duplex connector，会建立两条连接，消息可能重复投递。我一开始没注意，配了双向的，结果消费者收到重复消息，排查了半天才发现是连接重复。后来改成单向发起，问题消失。

6. 性能调优与生产建议

6.1 内存与流控参数

ActiveMQ 默认的内存限制是 64MB，这个值在生产环境肯定不够。在activemq.xml的 broker 标签里加 systemUsage 配置：

<systemUsage> <systemUsage> <memoryUsage> <memoryUsage percentOfJvmHeap="70"/> </memoryUsage> <storeUsage> <storeUsage limit="20gb"/> </storeUsage> <tempUsage> <tempUsage limit="10gb"/> </tempUsage> </systemUsage> </systemUsage>

percentOfJvmHeap="70"表示消息在内存里最多占 JVM 堆的 70%，超过后消息会刷到磁盘（KahaDB），消费者消费时再从磁盘读。这个值设太高容易 OOM，设太低会导致频繁刷盘影响性能，70% 是个经验值。storeUsage限制 KahaDB 磁盘占用，tempUsage限制临时文件占用，防止磁盘被写满。

JVM 堆大小在容器启动时通过环境变量设置，compose 文件里加：

environment: - ACTIVEMQ_OPTS=-Xms2g -Xmx2g -XX:+UseG1GC

-Xms和-Xmx设成一样大，避免堆动态调整带来的性能波动。G1 GC 在大堆场景下比 CMS 更稳，停顿时间可控。

6.2 MQTT 连接数调优

MQTT 连接数上来之后，需要调整传输层的参数。在 mqtt transportConnector 上加属性：

<transportConnector name="mqtt" uri="mqtt://0.0.0.0:1883?maximumConnections=10000&amp;wireFormat.maxFrameSize=104857600"/>

maximumConnections限制最大连接数，默认是 1000，设备量大的话要调大。wireFormat.maxFrameSize限制单帧最大字节数，默认 100MB，一般够用，但如果设备上报大 payload 需要调大。这两个参数要根据实际设备量和消息大小来定，不是越大越好——连接数设太大，内存和文件句柄消耗也大。

6.3 生产环境的高可用补充

纯 Network of Brokers 模式在节点挂掉时，连在该节点上的客户端需要重连。为了减少重连带来的影响，客户端侧要配好重连策略。以 Java 的 Paho MQTT 客户端为例，设置automaticReconnect=true和maxReconnectDelay，让客户端在断连后自动重连到其他节点。设备端固件里也要实现类似的逻辑，断连后按指数退避重试。

如果业务确实不能接受重连窗口，那就得上 Master-Slave。ActiveMQ 的 JDBC Master-Slave 方案用共享数据库做锁，主节点持有锁对外服务，从节点等待锁。主节点挂了，从节点抢到锁接管。这个方案需要额外部署数据库，架构复杂度上升，但能做到秒级切换。具体选哪种，还是回到业务对可用性的实际要求上来定。

6.4 监控与告警

生产环境必须配监控。ActiveMQ 暴露了 JMX 接口，可以用 Prometheus 的 JMX Exporter 采集指标，重点关注这几个：队列深度（queue size）、消费者数量（consumer count）、消息入队/出队速率（enqueue/dequeue rate）、连接数（connection count）。队列深度持续增长说明消费能力不足，消费者数量掉零说明消费者挂了，这些都要配告警。

Web 控制台也能看这些指标，但它是人工看的，不能做自动化告警。JMX Exporter 的配置稍微麻烦点，要写 YAML 定义采集哪些 MBean，但配好之后一劳永逸。我一般把队列深度超过 10000 和消费者数量为 0 这两个作为一级告警，响应要快。

7. 我个人的几点实操体会

搭这套集群的过程中，最大的感受是配置的对称性和差异性要分清。三个节点的配置，大部分是一样的（持久化、传输通道、内存参数），但 brokerName、Network Connector 的目标地址、端口（单机测试时）必须差异化。我一开始图省事，直接复制配置文件改了个 brokerName，结果 Network Connector 的地址没改，三个节点都连到自己身上，集群根本没组起来。后来养成的习惯是，配置文件用模板加变量生成，每个节点的差异项单独列出来核对，避免手误。

另一个体会是验证要分层做。先验证单节点的 MQTT 接入通不通，再验证两个节点的 Network Connector 通不通，最后验证三节点的消息路由通不通。每层验证用最简单的工具（telnet、mosquitto_pub/sub），不要一上来就上完整业务链路，出了问题定位不到是哪一层。分层验证虽然前期多花点时间，但排查问题时省的时间更多。

还有就是日志和监控要提前配。ActiveMQ 的日志默认级别是 INFO，集群连接、客户端连接这些关键事件都有记录，排查问题时先看日志。但日志量大了之后，grep 效率低，建议上 ELK 或者至少用journalctl配合过滤。监控的话，哪怕不上 Prometheus，至少把 Web 控制台的几个关键指标定期看一眼，心里有数。

最后说个小的：Docker 的日志驱动一定要限制大小。我见过不止一次因为容器日志没限制，把宿主机磁盘写满导致整个集群挂掉的情况。compose 文件里那几行max-size和max-file的配置，看着不起眼，关键时刻能救命。