📚 课程目录第3章 Mosquitto安装与配置

3. Mosquitto 安装与配置：在 Ubuntu/Docker 中安装 Mosquitto、基础配置文件解析、启动与停止服务

好，咱们正式开始动手了。这一章的目标很明确——把 Mosquitto 跑起来。我见过不少新手在配置上栽跟头，其实说白了，MQTT Broker 本身没那么复杂，关键是安装方式和配置文件里的几个坑要避开。

本章核心脉络：两种安装方式（原生 vs Docker）→ 配置文件逐行拆解 → 启动/停止/验证。你跟着走一遍，后面所有安全通信的实验都基于这个环境。

3.1 两种安装方式，你选哪种？

我个人习惯是：学习阶段用 Ubuntu 原生安装，生产环境用 Docker。为什么？原生安装能让你看到所有日志文件、配置目录的物理位置，理解 Mosquitto 到底在系统里放了什么。Docker 虽然方便，但屏蔽了太多细节。

3.1.1 Ubuntu 原生安装（推荐学习用）

Ubuntu 20.04/22.04 的官方源里就有 Mosquitto，版本可能不是最新，但足够稳定。

# 更新包索引
sudo apt update

# 安装 Mosquitto 服务端 + 客户端工具
sudo apt install -y mosquitto mosquitto-clients

# 检查安装结果
mosquitto -h
# 你应该能看到版本号，比如 "mosquitto version 2.0.11"

装完以后，Mosquitto 会自动以系统服务启动。我记得第一次装的时候，没注意它已经跑起来了，结果自己又手动启动了一次，端口冲突报错。嗯，这里要注意：apt 安装后服务默认是启动的。

小技巧：安装 mosquitto-clients 会附带 mosquitto_pub 和 mosquitto_sub 两个命令行工具，后面测试通信全靠它们。别只装服务端忘了客户端。

3.1.2 Docker 安装（推荐生产用）

如果你已经在用 Docker 环境，或者想快速拉起一个干净的实例，Docker 方式更合适。

# 拉取官方镜像（Eclipse Mosquitto）
docker pull eclipse-mosquitto:2

# 快速启动一个测试容器
docker run -d --name mosquitto-test \
  -p 1883:1883 \
  -p 9001:9001 \
  eclipse-mosquitto:2

这里我暴露了两个端口：1883 是标准的 MQTT 端口，9001 是 WebSocket 端口。如果你不需要 WebSocket 支持，只映射 1883 就够了。

注意：Docker 方式启动的容器，默认配置文件在容器内部的 /mosquitto/config/mosquitto.conf。如果你想自定义配置，建议挂载宿主机目录：

docker run -d --name mosquitto-custom \
  -v /path/to/your/mosquitto.conf:/mosquitto/config/mosquitto.conf \
  -v /path/to/your/data:/mosquitto/data \
  -v /path/to/your/log:/mosquitto/log \
  -p 1883:1883 \
  eclipse-mosquitto:2

不挂载的话，容器重启后配置和数据都会丢失——我曾经因为这个吃过亏，调试了一下午的配置，容器一重启全没了。

3.2 基础配置文件解析

配置文件是 Mosquitto 的灵魂。默认路径在 /etc/mosquitto/mosquitto.conf（Ubuntu 原生安装）或容器内的 /mosquitto/config/mosquitto.conf。

咱们挑几个最常用的配置项来拆解。你想想看，一个 MQTT Broker 最需要关心什么？无非就是：监听端口、允许谁连接、日志怎么记、数据存哪里。

配置项	默认值	说明	我的建议
`listener 1883`	无（默认监听所有接口）	设置 MQTT 监听端口和绑定的 IP 地址	生产环境务必绑定内网 IP，如 `listener 1883 192.168.1.100`
`allow_anonymous`	true	是否允许匿名连接（无用户名密码）	学习时可以先开着，生产必须设为 false
`password_file`	无	指定密码文件路径	配合 `mosquitto_passwd` 工具生成
`log_dest`	stderr	日志输出目标：`stderr` / `syslog` / `file`	调试时用 `file` 写到固定路径
`persistence`	false	是否持久化消息到磁盘	建议开启，防止 Broker 重启丢消息
`persistence_location`	/var/lib/mosquitto/	持久化数据存储目录	确保目录存在且有写权限

下面是一个我常用的最小化配置模板，适合学习阶段使用：

# /etc/mosquitto/conf.d/local.conf
# 这是一个最小化安全配置示例

# 监听所有接口的 1883 端口
listener 1883

# 允许匿名连接（学习阶段先开着）
allow_anonymous true

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

# 开启持久化
persistence true
persistence_location /var/lib/mosquitto/

# 自动保存间隔（秒）
autosave_interval 1800

关键点：Mosquitto 会读取 /etc/mosquitto/conf.d/ 目录下所有 .conf 文件。我习惯把自定义配置放在这个目录里，而不是直接修改主配置文件。这样升级 Mosquitto 时不会覆盖你的配置。

3.3 启动与停止服务

配置写好了，怎么让它生效？分两种情况说。

3.3.1 系统服务方式（Ubuntu 原生安装）

# 启动服务
sudo systemctl start mosquitto

# 停止服务
sudo systemctl stop mosquitto

# 重启服务（修改配置后常用）
sudo systemctl restart mosquitto

# 查看运行状态
sudo systemctl status mosquitto

# 设置开机自启
sudo systemctl enable mosquitto

用 systemctl status 能看到类似这样的输出：

● mosquitto.service - Mosquitto MQTT Broker
     Loaded: loaded (/lib/systemd/system/mosquitto.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2024-01-15 10:30:45 CST; 2h 15min ago
   Main PID: 12345 (mosquitto)
      Tasks: 1 (limit: 2345)
     Memory: 3.2M
        CPU: 1.234s
     CGroup: /system.slice/mosquitto.service
             └─12345 /usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf

看到 active (running) 就说明服务正常。如果启动失败，用 journalctl -u mosquitto -n 50 查看最近的日志，大部分配置错误都能在这里找到线索。

3.3.2 前台运行方式（Docker 或调试用）

有时候你需要在前台看日志输出，特别是调试配置的时候：

# 前台运行（Ctrl+C 停止）
mosquitto -c /etc/mosquitto/mosquitto.conf -v

# -v 参数会输出更详细的日志
# 你会看到类似这样的信息：
# 1705311234: mosquitto version 2.0.11 starting
# 1705311234: Config loaded from /etc/mosquitto/mosquitto.conf.
# 1705311234: Opening ipv4 listen socket on port 1883.
# 1705311234: mosquitto version 2.0.11 running

调试技巧：我每次修改配置后，都会先用 mosquitto -c your.conf -v 前台跑一下。如果配置有语法错误，Mosquitto 会直接报错退出，并告诉你哪一行有问题。确认无误后再切回 systemd 服务模式。

3.3.3 验证服务是否正常运行

服务跑起来了，怎么确认它真的在工作？用客户端工具做一次简单的发布/订阅测试：

# 终端 1：订阅 test/topic
mosquitto_sub -h localhost -t "test/topic" -v

# 终端 2：发布一条消息
mosquitto_pub -h localhost -t "test/topic" -m "Hello MQTT"

# 终端 1 应该会输出：
# test/topic Hello MQTT

如果能看到这条消息，恭喜你，Mosquitto 已经成功跑起来了。如果收不到，先检查防火墙是否放行了 1883 端口：

sudo ufw status
# 如果防火墙开启，放行 1883
sudo ufw allow 1883/tcp

常见踩坑点：

端口被占用：用 sudo lsof -i :1883 检查，如果有其他进程占用了，先杀掉或改端口。
配置文件权限：Mosquitto 以 mosquitto 用户运行，确保日志目录和数据目录对该用户可写。
Docker 网络模式：如果用 Docker，客户端在宿主机上连接时用 localhost 可能不行，试试 127.0.0.1 或容器 IP。

好了，到这里你已经完成了 Mosquitto 的安装、配置和启动验证。后面的章节我们会在这个基础上逐步加入 TLS 加密、认证授权、ACL 访问控制等安全机制。每一步我都会把当年踩过的坑提前告诉你，让你少走弯路。