Java 消息中间件 - ActiveMQ 保姆级全解2026

（概念 → 安装 → 配置 → 使用 → 进阶 → 黑科技 → 踩坑）一步一命令，全文可复制执行。

阶段 0：ActiveMQ 能做什么？一句话定位

Java 生态最老牌 JMS 实现
多协议：JMS、AMQP、MQTT、STOMP 一套 broker 搞定
嵌入式：jar 即启动，开发调试 5 秒完成
企业级：主从+集群+持久化，中小型系统首选

阶段 1：安装前准备------1 分钟环境检查

项	要求	命令
OS	Win/Linux/Mac 任意
JDK	≥ 8（推荐 11）	java -version
内存	开发 512 MB 即可

阶段 2：一键安装------3 命令完成

1.下载（国内镜像快）

bash 复制代码

wget https://mirrors.tuna.tsinghua.edu.cn/apache/activemq/5.17.6/apache-activemq-5.17.6-bin.tar.gz 
tar -xzf apache-activemq-5.17.6-bin.tar.gz 
cd apache-activemq-5.17.6

2.启服务

bash 复制代码

# Linux/Mac 
bin/activemq start 
# Win 
bin\activemq.bat start

3.验证浏览器打开 http://localhost:8161/admin 默认账号/密码：admin/admin 出现控制台即成功。

阶段 3：目录速览------5 个文件夹看懂

目录	作用
bin	启停脚本
conf	核心配置 activemq.xml
data	持久化存储（KahaDB）
lib	依赖 jar
webapps	控制台页面

阶段 4：最小配置------生产必改 3 项

编辑 conf/activemq.xml：

XML 复制代码

<!-- 1. 外网 IP，Docker/NAT 必须 --> 
<transportConnector name="openwire" uri="tcp://0.0.0.0:61616?maximumConnections=1000"/> 
<!-- 2. 持久化开关 --> 
<persistenceAdapter> 
  <kahaDB directory="${activemq.data}/kahadb" enableIndexWriteAsync="true"/> </persistenceAdapter> 
<!-- 3. 控制台密码 --> 
<bean id="securityConstraint" class="org.eclipse.jetty.security.Constraint"> 
  <property name="authenticate" value="true"/> 
</bean>

重启生效：

bash 复制代码

bin/activemq restart

阶段 5：Spring Boot 3 最小可运行代码

依赖：

XML 复制代码

<dependency> 
  <groupId>org.springframework.boot</groupId> 
  <artifactId>spring-boot-starter-activemq</artifactId> 
</dependency>

yml：

XML 复制代码

spring: 
  activemq: 
    broker-url: tcp://localhost:61616 
    user: admin 
    password: admin 
  jms: 
    pub-sub-domain: false # false = 队列（默认）

生产者：

java 复制代码

@RestController 
class ProducerController { 
  @Autowired private JmsTemplate jmsTemplate; 

  @GetMapping("/send") 
  public String send(@RequestParam String msg) { 
     jmsTemplate.send("test.q", session -> session.createTextMessage(msg)); 
     return "ok"; 
  } 
}

消费者（异步，手动 ACK）：

java 复制代码

@Component 
public class TestConsumer { 
  @JmsListener(destination = "test.q") 
  public void receive(TextMessage message, Session session) throws JMSException { 
    System.out.println("收到 = " + message.getText()); 
    message.acknowledge(); // 手动确认 
  } 
}

启动后访问 http://localhost:8080/send?msg=hello 控制台打印即成功。

阶段 6：高阶功能------一条命令开启

功能	开启方式	效果
主题（Pub/Sub）	spring.jms.pub-sub-domain=true	广播消息
事务消息	jmsTemplate.setSessionTransacted(true)	本地事务
延迟/定时	message.setLongProperty("AMQ_SCHEDULED_DELAY", 5000)	5 秒后投递
消息轨迹	broker 段加 <destinationPolicy><policyEntry queue=">" enableAudit="true"/></destinationPolicy>	审计日志
MQTT	transportConnector name="mqtt" uri="mqtt://0.0.0.0:1883"	IoT 设备直连

阶段 7：集群 & 高可用------最小 2 节点

主从配置（共享存储 KahaDB）：

XML 复制代码

<!-- node1 (master) --> 
<broker xmlns="http://activemq.apache.org/schema/core" brokerName="mq-cluster" dataDirectory="${activemq.data}"> 
  <transportConnectors> 
    <transportConnector name="openwire" uri="tcp://0.0.0.0:61616"/>   
  </transportConnectors> 
</broker> 

<!-- node2 (slave) --> 
<broker brokerName="mq-cluster" dataDirectory="/shared/kahadb"> 
  <transportConnectors> 
    <transportConnector name="openwire" uri="tcp://0.0.0.0:61617"/> 
  </transportConnectors> 
  <persistenceAdapter> 
    <kahaDB directory="/shared/kahadb"/> 
  </persistenceAdapter> 
</broker>

故障切换：主节点宕机，slave 自动接管，客户端用 failover://tcp://node1:61616,tcp://node2:61617 无缝重连。

阶段 8：黑科技玩法

嵌入式启动（单元测试秒起） BrokerService broker = new BrokerService(); broker.addConnector("tcp://localhost:61616"); broker.start();
SpringBoot 零配置加 spring-boot-starter-activemq 即可，无 xml。
MQTT 网关手机/传感器 PUBLISH 到 mqtt://ip:1883，ActiveMQ 自动转发到 JMS Queue，IoT → 后端一条线。
日志到队列 Log4j2 JmsAppender → log.q → ELK，无文件锁收集。

阶段 9：性能 & 压测

bash 复制代码

# 官方自带工具 
bin/activemq producer ---destination test.q ---messageCount 100000 ---messageSize 1024 
bin/activemq consumer ---destination test.q ---messageCount 100000

关注 Messages/Sec 和 Memory，> 5000/s 需调大 java.memory 或使用 LevelDB 存储。

阶段 10：踩坑 & 急救

坑	现象	急救
端口被占	启动失败	改 transportConnector 端口
数据库锁	KahaDB 报错	删 data/kahadb/lock 或加 mkdir -p /shared/kahadb 权限
连接泄漏	java.lang.OutOfMemoryError	客户端一定 close() Session/Consumer
消息重复	幂等未做	业务层加唯一键或幂等表
主从脑裂	双 master	用 failover + shared storage 避免

总结口诀（30 秒背完）

"解压即启动，xml 改端口； JMS 模板一句话，事务延迟加属性；集群共享目录，failover 自动切；连接记得关，KahaDB 锁要删！"

照抄 10 阶段，从开发到生产，ActiveMQ 任你拿捏！