Mosquitto Docker：如何使用 Docker 与 Docker Compose 设置 Eclipse Mosquitto MQTT 代理

从零开始搭建一个 MQTT 代理，不该耗费数小时在配置和排错上。

Eclipse Mosquitto 是一款开源 MQTT 代理，支持 MQTT v5、3.1.1 和 3.1 协议，非常适合物联网设备、家庭自动化系统、云应用，以及任何以消息驱动的架构。但将 Mosquitto 直接安装并配置在您的系统上，往往会遇到依赖冲突、权限问题和平台特定的麻烦，严重挤占开发时间。您最终会把更多精力花在环境折腾上，而不是构建真正的应用。

Docker 通过提供一致且隔离的运行环境，帮助在任何平台上运行 Mosquitto，消除这些痛点。几分钟内，您就能让一个功能完备的 MQTT 代理运行起来，并带有自定义配置、身份验证和持久化。

本指南将带您使用 Docker 和 Docker Compose 部署 Eclipse Mosquitto，配置身份验证与日志，设置数据持久化，并用真实的 MQTT 客户端测试代理。

完全不熟悉 Docker？我建议先学习我们的Docker 入门课程，先掌握基础知识。

什么是 Mosquitto，以及为何在 Docker 中使用它

当您只想要设备间快速可靠的通信时，并不需要笨重的消息系统。

MQTT 是一种轻量级的发布/订阅协议，适用于带宽受限且可靠性重要的场景。比如物联网传感器、移动应用，或任何需要设备快速交换小消息、且无需持续轮询的场景。

Mosquitto 充当发布者与订阅者之间的中间人——也就是“代理”。 

发布者将消息发送到特定主题；订阅者监听这些主题。Mosquitto 负责路由，确保消息送达正确的位置，而发布者和订阅者彼此无需感知对方。

以下是 Docker 让 Mosquitto 部署更出色的原因：

• 跨平台一致性：无论 Windows、macOS 还是 Linux——Docker 容器的运行方式都完全一致。无需再寻找平台特定的安装包或处理依赖冲突。
• 版本管理简单：您可以通过镜像标签锁定特定 Mosquitto 版本，若出问题可快速回退，还能在不触碰宿主系统的前提下测试新版本。
• 真正的可移植性：同一套 Docker Mosquitto 设置可用于开发、预发布与生产。您的本地环境与服务器上运行的版本一致。

Mosquitto 有两个版本：开源版（覆盖大多数用例）和 Cedalo 的商业 Pro 版，后者提供诸如集群与增强安全等高级特性。对大多数项目而言，开源版已能满足需求。

接下来，我会先介绍先决条件，然后开始安装 Mosquitto。

先决条件

在部署 Mosquitto 之前，您需要先在系统上安装并运行 Docker。

Docker Desktop最适合 Windows 和 macOS 用户，因为它将所有必须组件打包在一起。Linux 用户可以通过包管理器或 Docker 官方仓库直接安装Docker CLI。

不一定必须用 Docker Compose，但它能让多容器管理更轻松。大多数 Docker Desktop 安装默认包含 Compose。若您使用 Linux，可能需要单独安装。

您还需要基本的命令行技能。不必复杂，只要能运行命令、切换目录并编辑文本文件即可。

分步搭建

运行 Mosquitto Docker 需要三步：创建目录、运行容器，以及可选地设置 Docker Compose 以便于管理。

创建所需目录

Mosquitto 需要为配置、数据和日志提供有序存储。

请先创建这些目录：

mkdir mosquitto-docker
cd mosquitto-docker
mkdir config data logs技术支持

这样即可为 Mosquitto 的配置文件、持久化数据和日志输出准备好有序的文件夹。

每个目录的作用如下：

• /mosquitto/config 存放 mosquitto.conf 及其他配置文件
• /mosquitto/data 保存持久化的消息数据与订阅信息
• /mosquitto/log 包含 Mosquitto 的日志文件，便于调试与监控

这些目录会作为卷挂载到 Docker 容器中，因此您的设置与数据在容器重启后仍能保留。

使用 Docker 运行 Mosquitto

基础的 Docker 命令即可通过正确的端口映射与卷挂载来运行 Mosquitto。

docker run -d \
  --name mosquitto \
  -p 1883:1883 \
  -v $(pwd)/mosquitto/config:/mosquitto/config \
  -v $(pwd)/mosquitto/data:/mosquitto/data \
  -v $(pwd)/mosquitto/log:/mosquitto/log \
  eclipse-mosquitto:latest技术支持

图 1 - 使用 Docker 运行 Mosquitto

下面解释一下这些参数：

• -d 以后台（分离）模式运行容器
• --name mosquitto 为容器指定易于引用的名称
• -p 1883:1883 将宿主机的 1883 端口映射到容器的 1883 端口
• -v 将本地目录作为卷挂载到容器中

Mosquitto 2.0+ 默认以本地模式运行。这意味着它只接受来自本地主机的连接，除非您进行相应的配置。您需要创建一个配置文件以允许外部连接。

使用 Docker Compose

使用 Mosquitto 的 Docker Compose 能显著简化安装管理，尤其在您要运行多个服务时。

创建一个 docker-compose.yml 文件，并粘贴以下内容：

services:
  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"    # MQTT
      - "8883:8883"    # MQTTS (secure)
      - "9001:9001"    # WebSockets
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log技术支持

用以下命令启动：

docker-compose up -d技术支持

图 2 - 使用 Docker Compose 运行 Mosquitto

卷挂载的工作方式与 Docker 命令一致，但 Compose 会处理底层复杂性。端口配置涵盖所有常见的 MQTT 协议：标准 MQTT（1883）、安全的 MQTTS（8883）以及 WebSocket 连接（9001）。

在多服务场景下，Compose 的优势尤为明显。例如，当您与 Home Assistant、Node-RED 或其他 IoT 工具一同运行 Mosquitto 时，您可以在一个文件中定义全部服务，并一次性启动。

接下来我们深入配置部分。

更高级的 Docker 概念是否让您困惑？我们的 Docker 进阶 课程会在基础之上带您更进一步。

配置 Mosquitto

Mosquitto 默认不接受外部连接，您需要通过配置文件启用。

基本配置（mosquitto.conf）

在 mosquitto/config 目录下创建 mosquitto.conf 文件，并添加以下内容：

# Basic listener configuration
listener 1883
allow_anonymous true

# WebSocket listener
listener 9001
protocol websockets
allow_anonymous true

# Persistence
persistence true
persistence_location /mosquitto/data/

# Logging
log_dest file /mosquitto/log/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information技术支持

allow_anonymous true 允许客户端在无凭据的情况下连接。此设置适用于开发或内部网络，但在生产环境应禁用。当您将 allow_anonymous 设为 false 时，每个客户端都必须使用用户名和密码进行身份验证。

9001 端口上的 WebSocket 监听器可启用基于浏览器的 MQTT 客户端。Web 应用可以使用 Paho MQTT 等 JavaScript 库直接连接代理。

设置身份验证

进行身份验证需要创建密码文件并更新配置。

在容器内生成密码文件：

docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd username技术支持

图 3 - Mosquitto 身份验证

该命令会创建一个新的密码文件，并提示您输入密码。若要添加其他用户，移除 -c 标志：

docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwd another_user技术支持

现在，更新 mosquitto.conf 以强制启用身份验证：

# Disable anonymous access
allow_anonymous false

# Point to password file
password_file /mosquitto/config/passwd

# Basic MQTT listener
listener 1883

# WebSocket listener
listener 9001
protocol websockets

# Persistence
persistence true
persistence_location /mosquitto/data/

# Logging
log_dest file /mosquitto/log/mosquitto.log
log_type error
log_type warning
log_type notice
log_type information技术支持

密码文件保存在您挂载的配置卷中，因此在容器重启后仍会保留。

启用 TLS/SSL

TLS 加密可保护您的 MQTT 流量，防止窃听与篡改。

在 mosquitto.conf 中添加以下内容：

# Secure MQTT listener
listener 8883
cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

# Secure WebSocket listener
listener 9002
protocol websockets
cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key技术支持

您需要为自己的域名获取 SSL 证书。可以使用 Let’s Encrypt 提供的免费证书，或使用 Caddy Server 等反向代理自动签发证书。将证书文件放到 mosquitto/config 目录，使其在容器内可用。

持久化与日志

持久化会将消息与订阅保存到磁盘，而合理的日志有助于您排查连接问题。

您可以在 mosquitto.conf 中这样配置持久化：

# Enable persistence
persistence true
persistence_location /mosquitto/data/

# Save to disk every 300 seconds
autosave_interval 300

# Keep messages for offline clients
persistent_client_expiration 1d技术支持

至于日志，可以这样开启详细记录：

# Log to file and stdout
log_dest file /mosquitto/log/mosquitto.log
log_dest stdout

# Choose what to log
log_type error
log_type warning
log_type notice
log_type information
log_type debug

# Log connection details
connection_messages true
log_timestamp true技术支持

log_type 选项可筛选要记录的内容：

• error 与 warning：用于生产监控
• notice 与 information：提供一般运行洞察
• debug：用于排查连接问题

卷挂载可确保持久化数据与日志在容器重启后得以保留。data 目录保存所有持久化消息与订阅信息，log 目录则让您能在宿主机上直接查看调试信息。

通过配置文件，您无需重建容器就能完全掌控 Mosquitto 的行为。

测试搭建结果

只有确认客户端能连接并交换消息，您的代理才算真正可用。

使用 mosquitto_pub 与 mosquitto_sub

mosquitto_pub 与 mosquitto_sub 命令行工具是测试代理的最快方式。

根据您的平台，先安装 Mosquitto 客户端：

• Linux（Ubuntu/Debian）：sudo apt-get install mosquitto-clients
• macOS：brew install mosquitto
• Windows：从 Eclipse Mosquitto 官网下载，或使用 WSL

先从无认证测试开始。您需要两个终端窗口或标签页。在不同会话中分别运行以下命令：

# Subscribe to a topic (run this first)
mosquitto_sub -h localhost -p 1883 -t test/topic

# Publish a message (run in another terminal)
mosquitto_pub -h localhost -p 1883 -t test/topic -m "Hello MQTT"技术支持

在发布的终端中，您会看到如下输出：

图 4 - 发布消息

而在订阅的终端中，您会立即看到该消息：

图 5 - 订阅 Mosquitto 主题

若开启了身份验证，命令也很类似——只需传入用户名与密码：

# Subscribe with username and password
mosquitto_sub -h localhost -p 1883 -t test/topic -u username -P password

# Publish with credentials
mosquitto_pub -h localhost -p 1883 -t test/topic -m "Authenticated message" -u username -P password技术支持

如果您不想在本机安装 Mosquitto 客户端，也可以在 Docker 容器内运行：

# Subscribe using the container
docker exec -it mosquitto mosquitto_sub -h localhost -t test/topic

# Publish using the container
docker exec -it mosquitto mosquitto_pub -h localhost -t test/topic -m "Container message"技术支持

在发布的终端中，您会看到以下输出：

图 6 - 无认证发布消息

而在订阅的终端中，您会看到该消息：

图 7 - 无认证订阅 Mosquitto 主题

使用 MQTT 客户端进行测试

图形界面客户端更便于测试复杂场景并监控持续的消息流量。

MQTT Explorer 提供干净直观的界面来浏览主题与发送消息。连接到 localhost:1883 后，您能看到所有活动主题的树状视图。非常适合调试消息流和理解您的主题结构。

图 8 - MQTT Explorer 应用

MQTTX 提供更高级的功能，如脚本与批量发送。两者均支持身份验证、TLS 连接与 WebSocket 协议。

Home Assistant 用户可以直接在开发者工具中测试 MQTT 集成。将代理详情添加到 MQTT 集成后，使用内置的发布/订阅界面即可。

如果想要编程式测试，Paho MQTT 的 Python 客户端非常好用：

import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, rc):
    print(f"Connected with result code {rc}")
    client.subscribe("test/topic")

def on_message(client, userdata, msg):
    print(f"Received: {msg.payload.decode()}")

client = mqtt.Client()
# client.username_pw_set("username", "password")  # If using auth
client.on_connect = on_connect
client.on_message = on_message

client.connect("localhost", 1883, 60)
client.loop_forever()技术支持

在一个终端中运行该脚本，然后在另一个终端或 GUI 客户端发布消息。脚本会打印接收到的任何消息，从而确认代理能正确路由流量。

发布消息时，您需要这样做：

图 9 - 为 Python 示例发布消息

而在运行 Python 脚本的终端会看到如下输出：

图 10 - 为 Python 示例接收消息

发布与订阅正常工作意味着您的 Mosquitto Docker 部署已可用于实际应用。

将 Mosquitto Docker 集成到 Home Assistant

在 Docker 中将 Mosquitto 与 Home Assistant 并行运行，可打造一个无需任何网络配置烦恼的完整 IoT 消息枢纽。

Docker Compose 能让这一切变得简单。两个服务可以通过 Docker 的内部网络通信，无需额外暴露端口或处理 IP 地址。

下面是一个同时运行这两个服务的完整 docker-compose.yml：

services:
  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    networks:
      - homeassistant

  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:stable
    container_name: homeassistant
    restart: unless-stopped
    ports:
      - "8123:8123"
    volumes:
      - ./homeassistant:/config
      - /etc/localtime:/etc/localtime:ro
    networks:
      - homeassistant
    depends_on:
      - mosquitto

networks:
  homeassistant:
    driver: bridge技术支持

networks 段落创建了一个共享网络，两个容器可以通过名称互相访问。Home Assistant 可连接到 mosquitto:1883，无需使用 localhost 或 IP 地址。

用以下命令同时启动两个服务：

docker-compose up -d技术支持

接着在 Home Assistant 的网页界面中配置 MQTT 集成。转到 Settings > Devices & Services > Add Integration，然后搜索 "MQTT"。

输入以下连接信息：

• Broker：mosquitto（容器名）
• Port：1883
• 用户名/密码：若启用了身份验证，请填写您的凭据
• 其余保持默认设置

点击 Submit，Home Assistant 将测试连接。若成功，您会在集成列表中看到 MQTT。

图 11 - 在 Homelab 中配置 Mosquitto

现在，您可以添加 MQTT 设备，创建发布消息的自动化，并通过主题监控传感器数据。对兼容设备，Home Assistant 的 MQTT 集成还会自动完成设备发现。

常见问题排查

大多数 Docker Mosquitto 问题都归结于权限、端口或配置错误，导致连接受阻。

挂载卷的权限错误 

当容器无法写入宿主机目录时就会发生。您会在日志中看到 “Permission denied” 或 “Cannot create directory” 等报错。

通过为目录设置正确的属主即可修复：

sudo chown -R 1883:1883 mosquitto/技术支持

Mosquitto 容器以用户 ID 1883 运行，因此宿主机目录需匹配该属主。在某些系统上，您可能需要先创建该用户：

sudo useradd -u 1883 mosquitto
sudo chown -R mosquitto:mosquitto mosquitto/技术支持

端口冲突

当 1883 端口被其他程序占用时会发生。检查该端口上正在运行的程序：

# Linux/macOS
sudo lsof -i :1883

# Windows
netstat -an | findstr :1883技术支持

若有其他服务占用端口，请停止它，或将 Mosquitto 映射到其他端口：

docker run -p 1884:1883 eclipse-mosquitto:latest技术支持

本地模式阻止外部连接

即便容器运行中也可能发生。Mosquitto 2.0+ 默认仅接受来自本地主机的连接，除非您另行配置。

创建一个基础 mosquitto.conf 文件以允许外部连接：

listener 1883
allow_anonymous true技术支持

将该文件放到 mosquitto/config 目录中，并重启容器。

启动时目录为空

这意味着卷挂载未正确生效。请检查路径是否为绝对路径且目录已存在：

# Wrong - relative path might not work
-v ./mosquitto/config:/mosquitto/config

# Better - absolute path
-v $(pwd)/mosquitto/config:/mosquitto/config技术支持

在启动容器前先创建目录：

mkdir -p mosquitto/{config,data,log}技术支持

宿主与容器的 UID/GID 冲突

这会导致持续的权限问题。容器预期以用户 1883 运行，但宿主系统可能有不同的所有权要求。

强制容器以您的用户运行：

docker run --user $(id -u):$(id -g) eclipse-mosquitto:latest技术支持

或者调整宿主目录权限以符合容器预期。前者更适合开发环境，修复宿主权限更适合生产部署。

当出现问题时，请查看容器日志——通常会明确指出错误原因。

进阶：Mosquitto Pro Edition 功能

开源版 Mosquitto 覆盖了大多数用例，但企业环境通常需要只有 Pro 版才具备的功能。

基于角色的用户管理可为不同用户组定义精细的权限。您无需逐个管理用户访问，而是创建诸如 “sensor-readers”、“actuator-controllers” 或 “admin-users” 之类的角色，并为角色赋权。用户继承其角色的权限，从而更易在上百至上千设备中统一管理访问控制。

您可以按主题模式、IP 范围或时间窗口限制访问。当管理具有不同安全要求的复杂 IoT 部署时，这远胜于手动维护 ACL 文件。

高级身份验证选项超越简单的用户名/密码组合。JWT 令牌认证可与 Auth0、Okta 或企业 SSO 等现有身份提供商集成。LDAP 集成可直接连接 Active Directory 或其他企业目录服务。

深度检查与监控为消息流、连接模式与代理性能提供实时可视性。Pro 版内置仪表板，可显示哪些客户端带宽占用最高、哪些主题消息速率最高，以及瓶颈所在位置。

您将获得关于消息延迟、队列深度与客户端行为模式的详细度量。这些数据帮助您优化主题结构，并在问题客户端影响整个系统之前将其识别出来。

数据库与云服务集成免去了自定义桥接应用的需求。Pro 版可自动将消息转发至 PostgreSQL、MongoDB、InfluxDB、AWS IoT Core、Azure IoT Hub 或 Google Cloud IoT。您可以根据主题模式、消息内容或客户端元数据定义路由规则，决定消息的去向。

持久化队列应对高吞吐场景当标准 Mosquitto 的持久化不足以应对时，Pro 版可为离线客户端缓冲数百万条消息，并将负载分配到多个代理实例。它包含自动队列管理，防止内存耗尽，并保持消息有序性保证。

集群支持允许您运行多个代理实例，共享消息负载并提供故障切换保护。当某个代理宕机时，客户端会自动重连至健康实例，而不会丢失消息或订阅。

当您需要企业级可靠性与管理能力、而自行构建要耗费数月时，Pro 版就是合理选择。

在 Docker 中使用 Mosquitto 的优缺点

Docker 简化了部署，但并非所有场景下都是完美方案。

优点

• 跨平台一致性消除了操作系统特定安装的烦恼。同一条 Docker 命令可在 Windows、macOS 与 Linux 上工作，无需再为不同包管理器或依赖冲突头疼。开发环境与生产环境完全一致，部署时更少意外。
• 简单的版本升级只需更改镜像标签。无需卸载旧版本并祈祷升级不破坏配置，只要拉取新镜像并重启容器即可。若出问题，回退只需几秒。
• 备份与迁移便捷依托卷来保存数据。将 mosquitto 目录复制到另一台机器，运行同样的 Docker 命令即可恢复上线。在云厂商间迁移或升级硬件都只是简单的文件传输。

缺点

Docker 并非全是优势。

• 卷权限问题在某些操作系统上较为常见，尤其是在 Windows 与 Linux 宿主间切换时。您可能需要花时间修正所有权问题，并处理 UID/GID 不匹配，这在原生安装中通常不存在。
• 生产级安全需要额外配置意味着 Docker 有时会增加复杂度。除了 Mosquitto 自身的安全设置，您还需要管理网络策略、容器安全上下文与卷加密。原生安装则可直接利用操作系统现有的安全框架。
• 潜在的性能损耗在高吞吐、对微秒级延迟敏感的场景中更明显。容器网络层与卷挂载带来一定开销，而原生安装可以避免。对大多数 IoT 应用而言差异可忽略，但实时工业系统可能会感知到延迟。

当您需要在不同环境间保持一致部署与便捷管理时，Docker 是更优选择。

结语

在 Docker 中运行 Mosquitto，能为您提供一个在所有环境中都表现一致的可靠 MQTT 代理。无论是做物联网原型、构建家庭自动化系统，还是在开发中连接传感器，Docker 都能消除环境搭建的复杂性，让您专注于真正的项目。

如果计划在生产中使用 Mosquitto，请记住以下几点：

• 在暴露到互联网之前务必加固代理
• 使用 mosquitto_passwd 启用身份验证，并配备合规证书以配置 TLS 加密
• 仅对必要客户端开放访问

未加固的 MQTT 代理会成为攻击者监控设备通信或注入恶意指令的敞开大门。

对于需要角色访问控制、集群或 LDAP 集成等高级功能的企业部署，Mosquitto Pro 版提供了超越开源版本的管理工具与可扩展性。

准备好提升您的 Docker 与 Kubernetes 技能了吗？报名我们的使用 Docker 与 Kubernetes 的容器化与虚拟化技能路径，构建实用技能，助您求职成功。