Eclipse Mosquitto 的 Snap 包安装、测试与配置完整指南

• 物联网
• 消息队列
• 后端

Snap 是 Linux 发行版上分发与运行 Mosquitto MQTT 代理（broker）的一种便捷方式。本文将基于仓库中的官方 Snap 打包配置（snapcraft.yaml）与使用文档，完整讲解如何通过 Snap 安装 Mosquitto、验证其默认行为、用mosquitto_pub/mosquitto_sub做连通性测试，以及如何通过 Snap 特有的/var/snap/mosquitto/common/数据目录自定义配置（监听器、认证、TLS 等）。读完本文，你将掌握 Snap 版 Mosquitto 从零到可上线的完整操作路径，并理解其与普通安装方式在配置层面的关键差异。

一、Snap 版 Mosquitto 的安装

在支持 Snap 的 Linux 系统（如 Ubuntu、Debian、Fedora、Arch 等启用了 snapd 的发行版）上，安装 Mosquitto Snap 包有两种途径：

• 通过系统的图形化软件安装器搜索mosquitto并安装；
• 或直接在终端执行：

snap install mosquitto

安装完成后，Mosquitto 代理即以后台服务（daemon）的方式自动运行。从仓库中的 snapcraft.yaml 可以看到该 Snap 包的实际形态：

• confinement: strict—— 使用严格隔离模式，Snap 内的 Mosquitto 只能访问它被明确授予的目录与接口；
• grade: stable—— 属于稳定通道发布；
• base: core20—— 基于 Ubuntu 20.04 核心构建；
• 服务以daemon: simple、restart-condition: always方式托管，崩溃后会由 snapd 自动拉起；
• 申请了home、network、network-bind三个接口（plugs），其中network-bind使代理可以监听网络端口，network使客户端工具可以发起连接，home允许访问用户家目录下的文件。

同时该 Snap 包还一并提供了mosquitto_pub（pub）、mosquitto_sub（sub）、mosquitto_rr（请求/响应工具）、mosquitto_ctrl（代理控制工具）以及mosquitto_passwd（密码文件工具）等多个命令行程序，它们的可执行文件均被打包进 Snap（见 snapcraft.yaml），这为后续测试与运维提供了完整的工具链。

二、安装后的默认行为

安装完成后，代理以默认配置运行，其行为要点如下：

• 监听本机（localhost）的1883端口，仅接受来自本机的 MQTT 连接；
• 不对外网开放监听，因此其他计算机无法直接连入。

如果你希望允许其他计算机连接，就必须自定义配置：先配置一个明确的listener，再配置对应的认证方式。这一点在 Snap 环境下与普通安装完全一致——自 Mosquitto 2.0 起，未显式配置认证策略时默认拒绝匿名外部连接，必须显式选择密码文件、认证插件或匿名访问三种方案之一（详见认证方式文档）。

Snap 版默认配置的来源可以从仓库源码中直接证实：打包时内置的 default_config.conf 只有两行：

persistence false user root

即关闭持久化、以 root 运行；而启动包装脚本 launcher.sh 在没有自定义配置时会把$SNAP/default_config.conf作为-c参数传给代理进程。同时，Snap 构建时也会把仓库根目录的完整示例配置 mosquitto.conf 一并打包进去，作为用户日后自定义配置的参照模板（详见下文第四节）。

三、快速连通性测试：发布与订阅

Snap 包内自带的mosquitto_pub与mosquitto_sub是验证代理是否正常工作的最佳工具。mosquitto_pub用于向代理发布消息，mosquitto_sub用于订阅并接收消息，二者都支持大量选项，可胜任多种测试场景。这里先用最简单的方式做一轮端到端验证。

3.1 订阅消息

打开第一个终端，订阅snap/example主题上的所有消息：

mosquitto_sub -h localhost -t 'snap/example' -v

参数说明：

• -h localhost：指定 MQTT 代理所在主机。如果代理不在本机，请把localhost替换为代理的实际主机名或 IP 地址；
• -t 'snap/example'：指定要订阅的主题。该选项可以重复多次以同时订阅多个主题；
• -v：以 verbose 模式输出，即同时打印消息所属的主题与消息负载（payload）。

从源码 sub_client.c 可以看到，-t被明确定义为"mqtt topic to subscribe to. May be repeated multiple times"，而-v的作用是 "print published messages verbosely"，与文档描述一致。

3.2 发布消息

打开第二个终端，向同一主题发布一条消息：

mosquitto_pub -h localhost -t 'snap/example' -m 'Hello from mosquitto_pub'

参数说明：

• -t 'snap/example'：指定发布目标主题；
• -m 'Hello from mosquitto_pub'：指定要发布的消息负载（payload）。

-m选项在源码 pub_client.c 中被定义为 "message payload to send"。此外，同源的-n可发送空（零长度）消息，-f可把文件内容作为消息，-l与-s则分别按行或整体从标准输入读取消息（见 pub_client.c），便于扩展测试。

3.3 验证结果

如果一切正常，第一个终端中mosquitto_sub会打印出：

snap/example Hello from mosquitto_pub

即"主题 + 空格 + 负载"的格式。这一简单的发布/订阅闭环足以验证代理的核心消息路由功能是否正常。

3.4 更多测试玩法

除上述基础测试外，你还可以尝试：

• 通配符订阅：MQTT 支持#（匹配任意层级，须位于主题末尾）与+（匹配单层）两种通配符。例如订阅snap/#可接收snap/下所有主题的消息；

• 订阅$SYS/#：代理会持续发布关于自身运行状态的统计信息，主题以$SYS/开头。在源码 sys_tree.c 中可以看到这些指标的实际定义，例如：

  • $SYS/broker/clients/total、$SYS/broker/clients/connected、$SYS/broker/clients/disconnected
  • $SYS/broker/messages/received、$SYS/broker/messages/sent
  • $SYS/broker/bytes/received、$SYS/broker/bytes/sent
  • $SYS/broker/subscriptions/count、$SYS/broker/retained messages/count
  • $SYS/broker/heap/current、$SYS/broker/heap/maximum

  订阅$SYS/#即可观察这些实时指标，是判断代理健康状态最直接的手段。

特别注意 Shell 引号问题：命令行中的#在 Shell 里是注释起始符，而$SYS会被当作环境变量展开。因此在终端中执行通配符或$SYS订阅时，必须用单引号将主题包裹起来（如'snap/#'、'$SYS/#'），否则命令行为与预期完全不符。

四、自定义配置：Snap 版与普通安装的关键差异

完成基础测试后，生产环境通常需要配置加密连接（TLS）、认证、桥接（bridge，让不同代理间共享主题）以及其他众多选项。在 Snap 版中，这一切都通过提供新的配置文件来完成，其机制与普通安装有以下关键差异：

4.1 Snap 的数据目录：/var/snap/mosquitto/common/

Snap 采用严格隔离（strict confinement），代理在运行期间只能访问/var/snap/mosquitto/common/这一个目录。因此：

• Snap 包自带一份完整的示例配置文件，位于：

/var/snap/mosquitto/common/mosquitto_example.conf

该文件内容与 mosquitto.conf（即 man 手册mosquitto.conf(5)对应的配置说明）风格一致，覆盖了通用配置、监听器、TLS/PSK、持久化、日志、安全、桥接、代理控制、外部配置目录等全部配置段，是绝佳的参考模板。

• 创建你自己的配置时，把示例文件复制为实际生效的配置文件再编辑：

cp /var/snap/mosquitto/common/mosquitto_example.conf /var/snap/mosquitto/common/mosquitto.conf

然后按需修改mosquitto.conf即可。Snap 版只认mosquitto.conf这个名字作为用户自定义配置。

• 配置中引用的所有附加文件（如 TLS 证书、私钥等）也必须放在/var/snap/mosquitto/common/目录内，可以按需放进新建的子文件夹中。这是 Snap 版 Mosquitto 唯一可读写的持久化位置。

4.2 启动脚本的配置加载逻辑

为什么复制成mosquitto.conf就会被自动加载？答案在启动包装脚本 launcher.sh 中：

• 脚本根据运行用户决定"公共数据目录"的路径：若以 root 运行（即作为系统守护进程），使用$SNAP_COMMON（即/var/snap/mosquitto/common/）；若由非 root 用户运行，则使用$SNAP_USER_COMMON；
• 首次启动时，若公共目录下不存在mosquitto_example.conf，脚本会把 Snap 内置的 mosquitto.conf 复制过去作为示例（见 launcher.sh）；
• 若检测到$COMMON/mosquitto.conf存在，则以其作为-c参数启动代理；否则回退到 Snap 内置的 default_config.conf（见 launcher.sh）。

这意味着你无需修改 Snap 本身，只要在数据目录里放置mosquitto.conf，重启服务（或由 snapd 触发）后即自动生效。

4.3 配置内容的实操要点

自定义配置时，以下配置项与本文场景直接相关（完整参数说明以仓库根目录的 mosquitto.conf 示例为准）：

• 监听器（listener）：要让外部计算机可连接，必须显式定义监听器。例如：

listener 1883

默认情况下，未定义任何listener时代理仅监听本机 1883 端口并允许本地匿名连接；一旦显式定义了监听器，就需要同时明确安全策略。

• 认证（authentication）：Mosquitto 2.0 起必须显式选择认证方式。三种方案（详见认证方式文档）：

  • 密码文件：password_file <路径>，配合mosquitto_passwd工具生成；
  • 认证插件：2.0 及以上用plugin <路径>（旧版接口用auth_plugin）；
  • 匿名访问：allow_anonymous true，仅在明确需要时使用。

  若要为不同监听器配置不同认证方式，可在配置中设置per_listener_settings true，此时认证选项必须写在对应的listener行之后，例如：

listener 1883 password_file /var/snap/mosquitto/common/password_file

在 Snap 环境下，密码文件同样必须放在/var/snap/mosquitto/common/内。

• TLS 加密：通过cafile、certfile、keyfile等选项启用证书加密（推荐端口 8883），证书与密钥文件同样放置于/var/snap/mosquitto/common/下的子目录中。

• 桥接（bridge）：通过connection、address、topic等选项连接其他代理实现主题共享，配置方式与其他安装方式完全一致。

五、Snap 版之外：与其他安装方式的一致性

除配置文件的存放位置这一差异外，Snap 版 Mosquitto 的运行行为、配置语义与其他安装方式完全一致：

• 配置文件语法与 mosquitto.conf 示例、以及mosquitto.conf(5)man 手册完全兼容；
• mosquitto_pub、mosquitto_sub、mosquitto_passwd、mosquitto_ctrl、mosquitto_rr等工具的参数与行为与其他发行版一致；
• 代理支持 MQTT 5.0、3.1.1 与 3.1 协议版本（见 snapcraft.yaml 的描述），并内置了mosquitto_dynamic_security.so动态安全插件（见 snapcraft.yaml），可直接在配置中以plugin加载。

因此，从 Snap 版迁移到原生安装（或反之）时，只需迁移配置与数据目录中的证书/密码文件即可。仓库的文档索引中还汇总了 man 手册（mosquitto、mosquitto.conf、mosquitto_pub、mosquitto_sub 等）、认证方式、动态安全插件等资料，可作为深入配置的参考。

六、小结

Snap 版 Mosquitto 的核心使用路径可归纳为：

1. snap install mosquitto安装并自动启动，默认仅本机 1883 端口可用；
2. 用mosquitto_sub -h localhost -t 'snap/example' -v与mosquitto_pub -h localhost -t 'snap/example' -m '...'验证发布/订阅闭环；
3. 订阅'$SYS/#'（注意单引号）观察代理运行指标；
4. 将/var/snap/mosquitto/common/mosquitto_example.conf复制为/var/snap/mosquitto/common/mosquitto.conf并编辑，配置监听器、认证与 TLS；
5. 将证书、密钥、密码文件等全部置于/var/snap/mosquitto/common/目录内。

掌握上述流程后，你就可以在任意支持 Snap 的 Linux 系统上快速部署一个安全、可配置的 Mosquitto MQTT 代理。仓库中的 launcher.sh、snapcraft.yaml 与 mosquitto.conf 是理解其内部机制与深入自定义的第一手资料。

• 物联网
• 消息队列
• 后端