Linux 编译安装与配置 Mosquitto

Mosquitto 是一个轻量级的 MQTT Broker，常用于物联网、消息推送、设备通信等场景。本文整理了在 Ubuntu / Debian 系统下源码编译安装 Mosquitto、配置访问控制以及以 systemd 方式管理服务的常用步骤。

1. 编译安装前准备

在编译前，先安装依赖项：

sudo apt update
sudo apt install -y \
  libssl-dev libwebsockets-dev uuid-dev libcjson-dev \
  libc-ares-dev xsltproc docbook-xsl docbook-xml \
  build-essential cmake git

2. 编译并安装 cJSON

Mosquitto 在某些功能开启时会依赖 cJSON，因此先编译并安装它：

git clone https://github.com/DaveGamble/cJSON.git
cd cJSON
make && sudo make install

3. 编译并安装 Mosquitto

git clone https://github.com/eclipse/mosquitto.git
cd mosquitto
mkdir build && cd build
cmake \
  -DWITH_SRV=yes \
  -DWITH_CJSON=yes \
  -DWITH_WEBSOCKETS=yes \
  -DWITH_TLS=yes \
  -DWITH_BUNDLED_DEPS=yes \
  -DWITH_DOCS=yes \
  ..
make && sudo make install

安装完成后，可以先准备服务文件：

sudo cp ../service/systemd/mosquitto.service.simple /etc/systemd/system/mosquitto.service

此外，建议创建一个专用系统用户来运行 Mosquitto：

sudo useradd -r -m -s /bin/bash mosquitto

将默认配置目录移动到 /etc/mosquitto：

sudo mv /usr/local/etc/mosquitto /etc/mosquitto

并建立命令软链接：

sudo ln -s /usr/local/sbin/mosquitto /usr/sbin/mosquitto

4. 创建认证文件

创建管理员账号并设置密码：

sudo mosquitto_passwd -c /etc/mosquitto/pwfile admin

如果后续要添加其他用户，可以使用：

sudo mosquitto_passwd /etc/mosquitto/pwfile user

5. 配置 ACL（访问控制列表）

认证完成后，我们通常还需要对不同用户的主题权限做细分，以提高安全性。

例如创建一个 aclfile：

# admin 用户可以发布和订阅全部 topic
user admin
topic readwrite #

# user 用户只能访问 /iot/user/ 相关主题
user user
topic /iot/user/+

这意味着：

• admin 可以对所有主题执行读写操作
• user 只能读写 /iot/user/ 下的相关主题

6. 配置 Mosquitto 主配置文件

常用配置示例：

# 关闭匿名访问
allow_anonymous false

# 密码文件
password_file /etc/mosquitto/pwfile

# ACL 文件
acl_file /etc/mosquitto/aclfile

# 日志输出到文件
log_dest file /var/log/mosquitto/mosquitto.log

# 运行用户
user mosquitto

# MQTT 监听端口
listener 1883 0.0.0.0
protocol mqtt

# WebSocket 监听端口
listener 8083 0.0.0.0
protocol websockets

# 最大连接数
max_connections -1

说明：如果没有提前创建日志目录，需先生成并授权对应目录。

7. 创建 systemd 服务文件

sudo vim /etc/systemd/system/mosquitto.service

示例内容：

[Unit]
Description=Mosquitto MQTT Broker
Documentation=man:mosquitto.conf(5) man:mosquitto(8)
After=network.target
Wants=network.target

[Service]
Type=simple
NotifyAccess=main
ExecStart=/usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
ExecStartPre=/bin/mkdir -m 740 -p /var/log/mosquitto
ExecStartPre=/bin/chown mosquitto:mosquitto /var/log/mosquitto
ExecStartPre=/bin/mkdir -m 740 -p /run/mosquitto
ExecStartPre=/bin/chown mosquitto:mosquitto /run/mosquitto

[Install]
WantedBy=multi-user.target

8. 启动与管理服务

重新加载 systemd 服务列表：

sudo systemctl daemon-reload

启动 Mosquitto：

sudo systemctl start mosquitto

查看状态：

sudo systemctl status mosquitto

开机自启：

sudo systemctl enable mosquitto

9. 常见问题与排查

1）无法连接 broker

先检查服务状态：

sudo systemctl status mosquitto

如果服务未正常启动，再查看日志：

sudo journalctl -u mosquitto -n 50

2）认证失败

确认：

• password_file 路径是否正确
• 用户是否已在 pwfile 中创建
• allow_anonymous 是否设为 false

3）ACL 权限不生效

检查：

• acl_file 路径是否正确
• 主题规则是否写法准确
• 用户名是否与 pwfile 中一致

10. 实用建议

• 在生产环境中，建议始终关闭匿名访问（allow_anonymous false）
• ACL 应尽量细化，避免用户拥有过大范围的 topic 权限
• 对 MQTT 端口和 WebSocket 端口进行必要的防火墙限制
• 日志建议单独落到文件，方便后续排查

11. 总结

Mosquitto 的部署与配置可以分为四个关键步骤：

1. 安装依赖并编译 Mosquitto
2. 创建用户与密码文件
3. 配置 ACL 和监听端口
4. 通过 systemd 管理服务

对于物联网和消息总线场景，Mosquitto 是一个非常适合的轻量级 Broker 方案。