Mosquitto 完全指南：从安装到生产实践

目录

  1. Mosquitto 概述
  2. 安装 Mosquitto
  3. 基础配置
  4. 服务管理
  5. 安全认证：密码配置
  6. 权限控制：ACL 配置
  7. TLS 加密配置（进阶）
  8. 桥接配置
  9. 性能优化
  10. 故障排除
  11. 最佳实践总结

一、Mosquitto 概述

1.1 什么是 Mosquitto

Mosquitto 是一个开源的、轻量级的 MQTT Broker，由 Eclipse 基金会维护，采用 C 语言编写。

特性说明
轻量级二进制文件小，运行时内存占用低
高性能单节点可处理数万并发连接
跨平台支持 Linux、Windows、macOS
标准合规完整实现 MQTT 3.1.1 和 MQTT 5.0

1.2 适用场景

  • 物联网设备数据采集
  • 智能家居控制中心
  • 工业自动化消息总线
  • 移动应用推送服务

二、安装 Mosquitto

2.1 系统要求

部署规模CPU内存磁盘
开发测试1核256 MB1 GB
小型生产（<1k 设备）1核512 MB5 GB
中型生产（1k-10k 设备）2核2 GB20 GB

2.2 Ubuntu/Debian 安装（推荐）

# 更新软件包列表
sudo apt update

# 安装 Mosquitto Broker 和客户端工具
sudo apt install mosquitto mosquitto-clients -y

# 验证安装
mosquitto -h 2>&1 | head -1

2.3 其他安装方式

方式一：官方 PPA（获取最新版本）

sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa -y
sudo apt update
sudo apt install mosquitto mosquitto-clients -y

方式二：Docker 安装

docker run -d \
  --name mosquitto \
  -p 1883:1883 \
  -v ~/mosquitto/config:/mosquitto/config \
  eclipse-mosquitto:latest

2.4 安装验证

# 检查服务状态
sudo systemctl status mosquitto

# 测试连通性（需要两个终端）
# 终端1：订阅
mosquitto_sub -h localhost -t "test" -v

# 终端2：发布
mosquitto_pub -h localhost -t "test" -m "Hello MQTT!"

三、基础配置

3.1 配置文件位置

文件/目录用途
/etc/mosquitto/mosquitto.conf主配置文件
/etc/mosquitto/conf.d/附加配置目录（推荐）
/etc/mosquitto/passwd密码文件（需创建）
/etc/mosquitto/aclfileACL 权限文件（需创建）

3.2 基础配置示例

# 创建独立配置文件
sudo tee /etc/mosquitto/conf.d/basic.conf << 'EOF'
# 监听端口
listener 1883 0.0.0.0

# 允许匿名（测试用，生产环境请关闭）
allow_anonymous true

# 日志配置
log_dest file /var/log/mosquitto/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information
EOF

# 创建日志文件
sudo touch /var/log/mosquitto/mosquitto.log
sudo chown mosquitto:mosquitto /var/log/mosquitto/mosquitto.log

# 重启服务
sudo systemctl restart mosquitto

3.3 配置语法检查

# 每次修改配置后建议先检查语法
sudo mosquitto -c /etc/mosquitto/mosquitto.conf --test-check

四、服务管理

4.1 Systemd 管理命令

操作命令
启动服务sudo systemctl start mosquitto
停止服务sudo systemctl stop mosquitto
重启服务sudo systemctl restart mosquitto
重新加载配置sudo systemctl reload mosquitto
查看状态sudo systemctl status mosquitto
查看日志sudo journalctl -u mosquitto -f
开机自启sudo systemctl enable mosquitto

4.2 调试模式

# 停止服务，前台运行查看详细日志
sudo systemctl stop mosquitto
sudo mosquitto -c /etc/mosquitto/mosquitto.conf -v

五、安全认证：密码配置

5.1 为什么需要认证

默认情况下，Mosquitto 允许匿名连接（任何人都可以连接）。生产环境必须启用认证。

5.2 创建密码文件

# 创建密码文件并添加第一个用户（-c 表示创建新文件）
sudo mosquitto_passwd -c /etc/mosquitto/passwd admin

# 添加更多用户（不需要 -c 参数）
sudo mosquitto_passwd /etc/mosquitto/passwd sensor_001
sudo mosquitto_passwd /etc/mosquitto/passwd mobile_app

# 设置安全权限
sudo chmod 600 /etc/mosquitto/passwd
sudo chown mosquitto:mosquitto /etc/mosquitto/passwd

# 查看密码文件内容（密码是加密的）
sudo cat /etc/mosquitto/passwd

5.3 启用密码认证

sudo tee /etc/mosquitto/conf.d/auth.conf << 'EOF'
allow_anonymous false
password_file /etc/mosquitto/passwd
EOF

sudo systemctl restart mosquitto

5.4 测试带认证的连接

# 订阅（需要提供用户名和密码）
mosquitto_sub -h localhost -t "test" -u admin -P 你的密码 -v

# 发布
mosquitto_pub -h localhost -t "test" -m "hello" -u admin -P 你的密码

六、权限控制：ACL 配置

6.1 什么是 ACL

ACL（Access Control List，访问控制列表）用于控制每个用户能对哪些主题进行什么操作。

核心公式：

谁（User）能对什么（Topic）做什么（Read/Write）

6.2 ACL 语法基础

# 格式
topic [read|write|readwrite|deny] <主题过滤器>

# read      - 订阅权限
# write     - 发布权限
# readwrite - 发布和订阅权限
# deny      - 拒绝访问（优先级最高）

6.3 创建 ACL 文件

sudo nano /etc/mosquitto/aclfile
# ============================================
# 系统安全：禁止任何人访问系统主题
# ============================================
topic deny $SYS/#

# ============================================
# 管理员：拥有全部权限
# ============================================
user admin
topic readwrite #

# ============================================
# 传感器设备：只能发布数据，不能订阅
# ============================================
user sensor_001
topic write sensors/001/data

user sensor_002
topic write sensors/002/data

# ============================================
# 手机 App：发布命令 + 接收响应
# ============================================
user mobile_app
topic write cmd/+/set
topic read telemetry/+/status

# ============================================
# 使用 pattern 动态匹配（高级用法）
#  %u = 用户名, %c = 客户端ID
# ============================================
pattern write devices/%u/telemetry
pattern read devices/%u/command

6.4 启用 ACL

# 在配置文件中添加 ACL 文件路径
sudo tee /etc/mosquitto/conf.d/acl.conf << 'EOF'
acl_file /etc/mosquitto/aclfile
EOF

# 重启服务
sudo systemctl restart mosquitto

6.5 ACL 规则优先级

  1. deny 规则优先级最高，匹配到则直接拒绝
  2. 特定用户规则优先于匿名规则
  3. 先匹配到的规则生效

6.6 通配符与 pattern 详解

语法说明示例
topic read sensors/+单层通配，匹配 sensors/temp批量授权
topic write sensors/#多层通配，匹配 sensors/temp/01/data授权子树
pattern write %u/data动态匹配，%u 替换为用户名用户专属主题
pattern read %c/command动态匹配，%c 替换为客户端ID设备专属主题

6.7 常见场景配置示例

# 场景1：设备只上报数据
user device_001
topic write devices/device_001/telemetry

# 场景2：设备只接收命令
user device_002
topic read devices/device_002/command/#

# 场景3：App 既发命令又收响应
user app_user
topic write cmd/+
topic read rsp/+

# 场景4：访客只读公开主题
user guest
topic read public/#

# 场景5：批量设备动态授权
pattern write sensors/%c/data
pattern read sensors/%c/config

七、TLS 加密配置（进阶）

7.1 为什么需要 TLS

  • 密码认证只能验证身份，不能加密传输内容
  • 公网环境下，用户名/密码可能被截获
  • TLS 提供传输加密，防止中间人攻击

7.2 生成自签名证书

# 创建证书目录
sudo mkdir -p /etc/mosquitto/certs
cd /etc/mosquitto/certs

# 生成 CA 私钥和证书
sudo openssl genrsa -out ca.key 2048
sudo openssl req -new -x509 -days 365 -key ca.key -out ca.crt \
  -subj "/CN=MQTT-CA"

# 生成服务器私钥和证书
sudo openssl genrsa -out server.key 2048
sudo openssl req -new -key server.key -out server.csr \
  -subj "/CN=mqtt.example.com"
sudo openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key \
  -CAcreateserial -out server.crt -days 365

# 设置权限
sudo chmod 600 server.key

7.3 配置 TLS

sudo tee /etc/mosquitto/conf.d/tls.conf << 'EOF'
listener 8883 0.0.0.0
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
cafile /etc/mosquitto/certs/ca.crt
tls_version tlsv1.2
EOF

sudo systemctl restart mosquitto

7.4 客户端 TLS 连接测试

mosquitto_sub -h mqtt.example.com -p 8883 \
  -t "test" \
  --cafile /etc/mosquitto/certs/ca.crt

7.5 双向 TLS（客户端也提供证书）

listener 8884 0.0.0.0
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
cafile /etc/mosquitto/certs/ca.crt
require_certificate true
use_identity_as_username true

八、桥接配置

8.1 什么是桥接

桥接用于连接两个 MQTT Broker，实现跨 Broker 的消息转发。

8.2 桥接配置示例

# /etc/mosquitto/conf.d/bridge.conf
connection bridge_to_cloud
address mqtt.cloud.example.com:1883

# 启动类型：自动重连
start_type automatic

# 清会话
cleansession true

# 远程认证
remote_username bridge_user
remote_password bridge_pass

# 主题映射：本地 topic 转发到云端
topic # out 0 edge/ cloud/
topic command/# in 0

九、性能优化

9.1 系统参数优化

# 增加文件描述符限制
sudo tee /etc/security/limits.d/mosquitto.conf << 'EOF'
mosquitto soft nofile 65535
mosquitto hard nofile 65535
EOF

# 内核参数优化
sudo tee /etc/sysctl.d/99-mosquitto.conf << 'EOF'
net.core.somaxconn = 1024
net.ipv4.tcp_max_syn_backlog = 2048
EOF
sudo sysctl -p /etc/sysctl.d/99-mosquitto.conf

9.2 Mosquitto 配置优化

# /etc/mosquitto/conf.d/performance.conf
max_connections 10000
max_inflight_messages 20
max_queued_messages 1000
memory_limit 256
persistence true
autosave_interval 300
autosave_on_changes false
socket_recv_buffer 65536
socket_send_buffer 65536

十、故障排除

10.1 常见问题及解决方案

问题可能原因解决方案
Address already in use端口被占用sudo netstat -tlnp | grep 1883 查找并停止冲突进程
Connection Refused服务未运行sudo systemctl status mosquitto
Not authorised认证失败检查 allow_anonymous 和 password_file 配置
Permission denied文件权限问题sudo chown mosquitto:mosquitto <文件>

10.2 调试检查清单

# 1. 检查服务状态
sudo systemctl status mosquitto

# 2. 检查端口监听
sudo ss -tlnp | grep mosquitto

# 3. 检查配置文件语法
sudo mosquitto -c /etc/mosquitto/mosquitto.conf --test-check

# 4. 查看错误日志
sudo journalctl -u mosquitto -n 50 --no-pager

# 5. 查看 Mosquitto 日志
sudo tail -f /var/log/mosquitto/mosquitto.log

10.3 防火墙配置

# UFW（Ubuntu）
sudo ufw allow 1883/tcp
sudo ufw allow 8883/tcp

# Firewalld（CentOS/RHEL）
sudo firewall-cmd --permanent --add-port=1883/tcp
sudo firewall-cmd --reload

十一、最佳实践总结

11.1 安全配置检查清单

检查项推荐配置
匿名访问allow_anonymous false
密码认证password_file 配置且权限 600
ACL 权限遵循最小权限原则
公网部署必须启用 TLS
监听地址避免 0.0.0.0，按需绑定内网 IP

11.2 生产环境配置示例

# /etc/mosquitto/mosquitto.conf
# 基础配置
user mosquitto
connection_messages true

# 监听器
listener 1883 192.168.1.10
listener 8883 0.0.0.0

# TLS
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
cafile /etc/mosquitto/certs/ca.crt

# 安全
allow_anonymous false
password_file /etc/mosquitto/passwd
acl_file /etc/mosquitto/aclfile

# 性能
max_connections 5000
persistence true

# 日志
log_dest file /var/log/mosquitto/mosquitto.log
log_type error
log_type warning

11.3 日常运维命令速查

# 查看连接数
mosquitto_sub -t '$SYS/broker/clients/connected' -C 1 -W 1

# 查看版本
mosquitto -h 2>&1 | grep version

# 重新加载配置
sudo systemctl reload mosquitto

# 备份配置
sudo tar -czf mosquitto_backup.tar.gz /etc/mosquitto/

# 监控日志
sudo tail -f /var/log/mosquitto/mosquitto.log

结语

本文涵盖了 Mosquitto 从安装到生产部署的核心内容：

章节核心要点
安装apt install mosquitto mosquitto-clients
配置使用 /etc/mosquitto/conf.d/ 拆分配置
认证mosquitto_passwd + allow_anonymous false
授权ACL 文件 + topic/read/write 规则
加密TLS 证书 + listener 8883
运维systemctl + 日志监控

按此指南操作，即可部署一个安全、可用的 Mosquitto MQTT Broker。

作者

老丹

关注我
其他文章