1. NanoMQ 项目概述

NanoMQ 是一款轻量级、高性能的 MQTT 消息中间件，专为物联网边缘计算场景设计。作为 EMQ 开源的 MQTT Broker，它能在资源受限的设备上稳定运行，同时支持完整的 MQTT 3.1.1/5.0 协议。我在工业物联网项目中多次使用 NanoMQ 作为边缘消息枢纽，实测单机可支持 10W+ QoS1 消息吞吐，内存占用却不到 10MB。

对于刚接触 MQTT 的开发者，NanoMQ 的极简配置和跨平台特性使其成为理想的入门选择。本教程将带你从零开始，通过四个实战场景（传感器数据采集、规则引擎转发、WebSocket 桥接、Docker 部署），掌握 NanoMQ 的核心使用技巧。所有操作均在 Ubuntu 22.04 实测通过，Windows/macOS 用户只需微调命令即可适配。

2. 环境准备与安装

2.1 硬件与系统要求

• CPU：x86_64/ARMv7+/ARM64（树莓派 3B+ 及以上型号均可）
• 内存：≥ 32MB（QoS0 场景可低至 16MB）
• 存储：≥ 5MB 磁盘空间
• 系统：Linux ≥ 3.10 / Windows 10+ / macOS 10.15+

注意：生产环境建议选择 Linux 发行版以获得最佳性能，我在 Jetson Nano 上实测的时延比 Windows 低 40%

2.2 三种安装方式对比

2.2.1 源码编译安装（推荐开发者）

# 安装构建依赖 sudo apt install -y build-essential cmake git # 克隆源码（建议使用 0.15+ 版本） git clone --depth 1 -b 0.15.0 https://github.com/emqx/nanomq.git cd nanomq # 编译选项说明： # -DENABLE_TLS=ON 启用SSL加密 # -DNNG_ENABLE_SQLITE=ON 启用规则引擎持久化 mkdir build && cd build cmake -G Ninja -DNNG_ENABLE_SQLITE=ON .. ninja sudo ninja install

编译完成后关键文件位置：

• 主程序：/usr/local/bin/nanomq
• 配置文件：/etc/nanomq.conf
• 日志文件：/var/log/nanomq.log

2.2.2 二进制包安装（推荐生产环境）

# Ubuntu/Debian wget https://github.com/emqx/nanomq/releases/download/0.15.0/nanomq-0.15.0-ubuntu20.04-amd64.deb sudo apt install ./nanomq-0.15.0-ubuntu20.04-amd64.deb # CentOS/RHEL wget https://github.com/emqx/nanomq/releases/download/0.15.0/nanomq-0.15.0-el7-amd64.rpm sudo yum install nanomq-0.15.0-el7-amd64.rpm

2.2.3 Docker 快速体验

# 默认配置启动 docker run -d --name nanomq -p 1883:1883 -p 8083:8083 emqx/nanomq:latest # 挂载自定义配置 docker run -d -v /path/to/nanomq.conf:/etc/nanomq.conf -p 1883:1883 emqx/nanomq:latest

3. 核心配置详解

3.1 配置文件结构解析

默认配置文件路径/etc/nanomq.conf主要包含以下区块：

# 基础配置 listener.tcp { bind = "0.0.0.0:1883" max_connections = 102400 backlog = 1024 } # MQTT协议配置 mqtt { protocol_level = 5 # 支持MQTT 5.0 max_packet_size = 10MB client_max_packet_size = 1MB } # WebSocket支持 websocket { bind = "0.0.0.0:8083" tls = false } # 日志配置 log { to = [file, console] level = warn dir = "/var/log/nanomq" file = "nanomq.log" }

3.2 关键参数调优建议

1. 连接数优化：

   • max_connections根据设备内存调整（每连接约占用 5KB）
   • 树莓派等设备建议设为 5000 以下

2. 消息吞吐优化：

   mqtt { max_inflight_messages = 100 # 飞行窗口大小 max_awaiting_rel = 1000 # QoS1/2消息队列长度 retry_interval = 20s # 重试间隔 }

3. 内存控制：

   sys { mem_limit = 100MB # 内存硬限制 mem_high_watermark = 80% # 内存警戒线 }

3.3 安全配置实战

3.3.1 启用 TLS 加密

listener.ssl { bind = "0.0.0.0:8883" keyfile = "/etc/certs/server.key" certfile = "/etc/certs/server.pem" cacertfile = "/etc/certs/ca.pem" verify_peer = false # 生产环境应设为true }

3.3.2 ACL 访问控制

创建acl.conf：

# 用户权限定义 user "admin" { password = "public" allow = ["#"] } user "device" { password = "123456" allow = ["device/${clientid}/#"] }

在nanomq.conf中引用：

mqtt { acl_file = "/etc/nanomq/acl.conf" }

4. 调试与监控技巧

4.1 命令行工具使用

# 启动交互式CLI nanomq_cli # 订阅测试（显示详细消息头） nanomq_cli sub -t "test" -v # 发布QoS2消息 nanomq_cli pub -t "cmd" -m "reboot" -q 2 # 压力测试（1000客户端，每秒500消息） nanomq_bench sub -c 1000 -t bench & nanomq_bench pub -c 1000 -t bench -m 500

4.2 日志分析要点

常见日志模式及含义：

WARN - [SYSTEM] Memory usage exceeds 80% # 内存超过警戒线 ERROR - [MQTT] Client 'dev01' auth failed # 认证失败 INFO - [BRIDGE] Forwarded 120 messages to cloud # 桥接转发

4.3 Prometheus 监控集成

1. 启用指标采集：

http_server { bind = "0.0.0.0:8080" enable_prometheus = true }

2. 采集关键指标：

• nanomq_messages_received_total：接收消息数
• nanomq_clients_connected：当前连接数
• nanomq_subs_count：订阅关系数

5. 四大实战场景

5.1 场景一：传感器数据汇聚

配置示例：

# 启用共享订阅（负载均衡） mqtt { shared_subscription = true } # 设备主题命名规范 # 上行：device/${clientid}/upload # 下行：device/${clientid}/control

Python 订阅代码片段：

import paho.mqtt.client as mqtt def on_message(client, userdata, msg): print(f"收到 {msg.topic}: {msg.payload.decode()}") client = mqtt.Client(protocol=mqtt.MQTTv5) client.username_pw_set("sensor01", "password") client.connect("localhost", 1883) client.subscribe("device/+/upload", qos=1) client.on_message = on_message client.loop_forever()

5.2 场景二：规则引擎转发

配置 SQL 规则：

rule { name = "to_cloud" sql = "SELECT payload FROM 'device/+/upload' WHERE payload.temp > 30" actions = [ { name = "forward_to_cloud" params = { topic = "cloud/alert" server = "tcp://cloud.emqx.io:1883" } } ] }

5.3 场景三：WebSocket 桥接

浏览器端代码：

const client = new Paho.MQTT.Client( "ws://your-server:8083/mqtt", "web_" + Math.random().toString(16).substr(2,8) ); client.connect({ onSuccess: () => { client.subscribe("device/+/status"); }, useSSL: false }); client.onMessageArrived = (msg) => { console.log(msg.destinationName, msg.payloadString); };

5.4 场景四：Docker 集群部署

docker-compose.yml 示例：

version: '3' services: nanomq1: image: emqx/nanomq:latest ports: - "1883:1883" - "8083:8083" volumes: - ./cluster1.conf:/etc/nanomq.conf networks: - nanomq_net nanomq2: image: emqx/nanomq:latest ports: - "1884:1883" volumes: - ./cluster2.conf:/etc/nanomq.conf networks: - nanomq_net networks: nanomq_net: driver: bridge

6. 性能调优实战

6.1 百万连接压测方案

1. 准备配置文件：

listener.tcp { bind = "0.0.0.0:1883" max_connections = 1000000 nodelay = true # 禁用Nagle算法 } sys { mem_limit = 2GB worker_pool_size = 16 # 与CPU核心数相同 }

2. 启动参数优化：

nanomq start --conf /etc/nanomq.conf \ --tcp.sndbuf 1MB \ --tcp.rcvbuf 1MB \ --socket.backlog 65535

3. 客户端模拟命令：

nanomq_bench conn -c 1000000 -i 10 -I 100

6.2 高可用部署架构

推荐拓扑：

[Edge Devices] --> [NanoMQ Cluster] --> [EMQX Enterprise] (3节点) (云端集群)

关键配置：

# 节点1配置 cluster { mode = static nodes = [ "nanomq1:1883", "nanomq2:1883", "nanomq3:1883" ] }

7. 故障排查手册

7.1 常见问题速查表

7.2 网络问题诊断

# 检查端口监听 ss -tulnp | grep nanomq # 测试MQTT连通性 mosquitto_pub -h 127.0.0.1 -t test -m "ping" # 抓包分析（需root） tcpdump -i any port 1883 -w mqtt.pcap

7.3 性能瓶颈分析

1. 生成火焰图：

perf record -F 99 -p $(pgrep nanomq) -g -- sleep 30 perf script | stackcollapse-perf.pl | flamegraph.pl > nanomq.svg

2. 关键指标监控：

watch -n 1 "nanomq_cli stats | grep -E 'clients|messages'"