RocketMQ 5.x是唯一受官方维护的主线版本，4.x已停止更新；启动失败主因是默认JVM堆内存过低，需手动调大runserver.sh和runbroker.sh中的-Xms/-Xmx参数，并确保namesrvAddr配置为客户端可达的真实IP，否则Producer/Consumer无法连接。
直接上结论：RocketMQ 5.x（如 5.3.2/5.3.4）是当前唯一受官方维护的主线版本，4.x 已停止更新，不建议新部署使用；单机测试可跳过编译，用 bin-release 包解压即用，但必须手动调大 runserver.sh 和 runbroker.sh 中的 JVM 堆内存，否则启动必失败。
为什么 RocketMQ 启动后立刻退出或日志里报 java.lang.OutOfMemoryError
根本原因是 RocketMQ 自带的 runserver.sh 和 runbroker.sh 默认堆内存配置极低（-Xms2g -Xmx2g），而实际运行时 NameServer 至少需 1G，Broker 轻量模式也需 2G+。Linux 服务器若只有 4G 内存，不改参数就必然 OOM 或被系统 kill。
- 打开
bin/runserver.sh，把JVM_OPTS行改成：-Xms1g -Xmx1g -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=320m - 打开
bin/runbroker.sh，把JVM_OPTS行改成：-Xms2g -Xmx2g -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=320m - 若机器内存 ≥ 8G，可进一步设为
-Xms4g -Xmx4g，但注意不要超过物理内存的 75% - 改完保存，再启动——否则
tail -f ~/logs/rocketmqlogs/namesrv.log只能看到半行启动日志就中断
namesrvAddr 配置错误导致 Producer/Consumer 连不上 Broker
namesrvAddr 不是“填 localhost 就行”，它必须是客户端网络可达的真实 IP。常见错误是服务端 broker.conf 里写 namesrvAddr=localhost:9876，但客户端在另一台机器上，根本解析不到这个地址。
- 先确认 NameServer 是否真在运行：
ps aux | grep mqnamesrv，再看netstat -tuln | grep 9876是否监听0.0.0.0:9876（不是127.0.0.1:9876） - Broker 启动时必须显式指定
-n参数，例如：sh bin/mqbroker -n 192.168.1.100:9876 -c conf/broker.conf -
broker.conf中必须设置brokerIP1=192.168.1.100（不能是localhost或内网不可达地址），否则 Consumer 拉消息时会连向一个无效 IP - 客户端代码或环境变量中设
NAMESRV_ADDR=192.168.1.100:9876，而非localhost
用 mqadmin 查不到 Topic 或 ConsumerGroup？
mqadmin 是 RocketMQ 自带的命令行工具，但它默认读取的是本地 NAMESRV_ADDR 环境变量；如果没设或设错，所有查询都返回空，不是没数据，而是连错了地方。
- 先执行：
export NAMESRV_ADDR=192.168.1.100:9876（和 Broker 启动时用的地址一致） - 再查 Topic：
sh bin/mqadmin topicList -n $NAMESRV_ADDR，首次运行可能返回空——因为默认autoCreateTopicEnable=false，需手动创建或改为 true - 若要自动建 Topic，启动 Broker 时加参数：
-c conf/broker.conf -n 192.168.1.100:9876，且确保conf/broker.conf中有：autoCreateTopicEnable=true - 查消费者组：
sh bin/mqadmin consumerProgress -n $NAMESRV_ADDR -g test-consumer-group，注意-g后必须是真实存在的 Group 名，大小写敏感
Java SDK 测试发消息失败，报 No route info of this topic
这不是代码问题，是 Topic 根本没注册到 NameServer。RocketMQ 不像 Kafka 那样自动建 Topic，它依赖 Broker 主动上报，而上报的前提是 Broker 已连上 NameServer 且配置无误。
- 检查
broker.conf是否包含：namesrvAddr=192.168.1.100:9876（和启动参数一致） - 检查 Broker 日志：
tail -f ~/logs/rocketmqlogs/broker.log，搜索register broker to name server，应看到成功注册记录 - 若无注册记录，大概率是
namesrvAddr地址不通，或防火墙拦了 9876 端口（NameServer）和 10911 端口（Broker 默认通信端口） - 临时放行：
firewall-cmd --permanent --add-port=9876/tcp && firewall-cmd --permanent --add-port=10911/tcp && firewall-cmd --reload
最易被忽略的一点：RocketMQ 5.x 的 broker.conf 默认不启用自动 Topic 创建，也不监听外网地址，所有配置项必须显式写出；靠“默认值”跑通的概率几乎为零。每次改完配置，务必重启 Broker 并检查日志里的注册动作是否成功。
