第2章 Mosquitto安装指南

第2章 Mosquitto安装指南

2.1 安装方式概览

快速测试
开发学习
生产环境
Windows
选择安装方式
使用场景?
Docker容器
包管理器安装
源码编译
Windows安装包
最简单快速
环境隔离
易于管理
安装快捷
自动更新
依赖管理
完全自定义
性能优化
最新功能
图形界面
服务自动运行
开始安装

2.2 Windows系统安装

方式一：使用官方安装程序（推荐）

访问官网
下载安装包
运行安装程序
选择组件
Mosquitto Core
Service Runner
Clients
下一步
设置端口
完成安装
启动服务

详细步骤

1. 下载安装包

访问 Mosquitto 官方下载页面：

https://mosquitto.org/download/

选择 Windows 版本的安装程序（.exe文件）

2. 运行安装程序

双击下载的安装程序，按照向导操作：

# 推荐安装路径
C:\Program Files\Mosquitto

# 默认端口配置
MQTT端口: 1883
WebSocket端口: 8083（可选）

3. 配置防火墙

安装完成后，需要配置Windows防火墙允许Mosquitto通信：

# 以管理员身份运行PowerShell
# 添加防火墙入站规则
New-NetFirewallRule -DisplayName "Mosquitto MQTT" -Direction Inbound -LocalPort 1883 -Protocol TCP -Action Allow

# 如果使用WebSocket
New-NetFirewallRule -DisplayName "Mosquitto WebSocket" -Direction Inbound -LocalPort 8083 -Protocol TCP -Action Allow

4. 验证安装

# 检查服务状态
Get-Service | Where-Object {$_.Name -like "*mosquitto*"}

# 或者在服务管理器中查找 "Mosquitto Broker"

5. 测试连接

# 打开两个命令行窗口

# 窗口1：订阅消息
mosquitto_sub -v -t "test/#"

# 窗口2：发布消息
mosquitto_pub -t "test/hello" -m "Hello Mosquitto!"

方式二：使用Chocolatey包管理器

# 安装Chocolatey（如果未安装）
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# 安装Mosquitto
choco install mosquitto

# 验证安装
mosquitto --version

方式三：使用WSL（Windows Subsystem for Linux）

# 在WSL中按照Linux方式安装
sudo apt update
sudo apt install mosquitto mosquitto-clients

# 启动服务
sudo service mosquitto start

2.3 Linux系统安装

Ubuntu/Debian系统

启动服务
更新软件源
安装Mosquitto
配置服务
设置开机自启
测试连接
安装完成

详细安装步骤

1. 更新软件包索引

sudo apt update

2. 安装Mosquitto及客户端工具

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

# 如果需要最新版本，添加官方仓库
sudo apt-add-repository ppa:mosquitto-dev/mosquitto-ppa
sudo apt update
sudo apt install -y mosquitto mosquitto-clients

3. 验证安装

# 检查Mosquitto版本
mosquitto --version

# 示例输出：
# mosquitto version 2.0.14
# mosquitto 2.0.14

4. 启动并设置开机自启

# 启动Mosquitto服务
sudo systemctl start mosquitto

# 设置开机自动启动
sudo systemctl enable mosquitto

# 查看服务状态
sudo systemctl status mosquitto

5. 配置防火墙

# Ubuntu使用UFW
sudo ufw allow 1883/tcp
sudo ufw allow 8883/tcp  # 如果使用TLS

# 查看防火墙状态
sudo ufw status

6. 测试连接

# 打开两个终端窗口

# 终端1：订阅测试主题
mosquitto_sub -v -t "test/#"

# 终端2：发布测试消息
mosquitto_pub -t "test/hello" -m "Hello from Ubuntu!"

CentOS/RHEL系统

添加EPEL仓库
安装Mosquitto
启动服务
配置防火墙
测试连接

1. 启用EPEL仓库

# CentOS 7/8
sudo yum install -y epel-release

# RHEL 8/9
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

2. 安装Mosquitto

# CentOS 7/RHEL 7
sudo yum install -y mosquitto mosquitto-clients

# CentOS 8/RHEL 8/9
sudo dnf install -y mosquitto mosquitto-clients

3. 启动服务

# 启动服务
sudo systemctl start mosquitto

# 开机自启
sudo systemctl enable mosquitto

# 查看状态
sudo systemctl status mosquitto

4. 配置firewalld防火墙

# 启动防火墙（如果未启动）
sudo systemctl start firewalld
sudo systemctl enable firewalld

# 开放MQTT端口
sudo firewall-cmd --permanent --add-port=1883/tcp
sudo firewall-cmd --permanent --add-port=8883/tcp

# 重载防火墙规则
sudo firewall-cmd --reload

# 查看开放的端口
sudo firewall-cmd --list-ports

Arch Linux

# 安装Mosquitto
sudo pacman -S mosquitto

# 启动并设置开机自启
sudo systemctl start mosquitto
sudo systemctl enable mosquitto

# 验证安装
mosquitto --version

2.4 macOS系统安装

Homebrew
官方包
选择安装方式
使用Homebrew
下载DMG安装包
安装Homebrew
brew install mosquitto
启动服务
下载DMG
安装应用
配置启动项
测试连接

方式一：使用Homebrew（推荐）

1. 安装Homebrew（如果未安装）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. 安装Mosquitto

# 更新Homebrew
brew update

# 安装Mosquitto
brew install mosquitto

# 验证安装
mosquitto --version

3. 启动服务

# 启动Mosquitto服务
brew services start mosquitto

# 查看服务状态
brew services list

# 停止服务
brew services stop mosquitto

# 重启服务
brew services restart mosquitto

4. 测试连接

# 订阅测试
mosquitto_sub -v -t "test/#"

# 发布测试（新终端）
mosquitto_pub -t "test/hello" -m "Hello from macOS!"

方式二：从源码编译

# 下载源码
cd /tmp
wget https://mosquitto.org/files/source/mosquitto-2.0.18.tar.gz

# 解压
tar -xvzf mosquitto-2.0.18.tar.gz
cd mosquitto-2.0.18

# 编译安装
make
sudo make install

# 配置动态链接库
sudo /usr/bin/install_name_tool -change /usr/local/lib/libmosquitto.1.dylib /usr/local/lib/libmosquitto.1.0.0.dylib /usr/local/bin/mosquitto_pub
sudo /usr/bin/install_name_tool -change /usr/local/lib/libmosquitto.1.dylib /usr/local/lib/libmosquitto.1.0.0.dylib /usr/local/bin/mosquitto_sub

2.5 Docker容器化部署

为什么选择Docker？

Docker优势
环境隔离
快速部署
易于迁移
版本管理
避免依赖冲突
一行命令启动
跨平台一致性
灵活切换版本

快速启动

拉取镜像
运行容器
验证服务
配置持久化
生产部署

方式一：快速测试（最简单）

# 直接运行官方镜像
docker run -it -p 1883:1883 eclipse-mosquitto:2

# 后台运行
docker run -d -p 1883:1883 --name mosquitto eclipse-mosquitto:2

方式二：自定义配置（推荐）

1. 创建项目目录结构

mkdir -p ~/mosquitto/config
mkdir -p ~/mosquitto/data
mkdir -p ~/mosquitto/log
cd ~/mosquitto

2. 创建配置文件

cat > config/mosquitto.conf << 'EOF'
# 监听配置
listener 1883
allow_anonymous true

# 持久化
persistence true
persistence_location /mosquitto/data/

# 日志
log_dest file /mosquitto/log/mosquitto.log
log_dest stdout

# 连接配置
max_connections -1
connection_messages true
EOF

3. 运行容器

docker run -d \
  --name mosquitto \
  -p 1883:1883 \
  -p 9001:9001 \
  -v ~/mosquitto/config:/mosquitto/config \
  -v ~/mosquitto/data:/mosquitto/data \
  -v ~/mosquitto/log:/mosquitto/log \
  eclipse-mosquitto:2 \
  -c /mosquitto/config/mosquitto.conf

4. 验证运行

# 查看容器日志
docker logs -f mosquitto

# 查看容器状态
docker ps

# 测试连接
docker exec -it mosquitto mosquitto_sub -v -t "test/#"

Docker Compose部署（生产推荐）

创建docker-compose.yml

version: '3.8'

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped

    ports:
      - "1883:1883"   # MQTT端口
      - "9001:9001"   # WebSocket端口

    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log

    environment:
      - TZ=Asia/Shanghai

    # 资源限制
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

启动服务

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

常用Docker命令

Docker管理命令
查看状态
查看日志
进入容器
重启服务
删除容器
docker ps
docker logs mosquitto
docker exec -it mosquitto sh
docker restart mosquitto
docker rm -f mosquitto

2.6 源码编译安装

编译流程图

开始编译
安装依赖
下载源码
配置编译选项
编译
安装
配置环境
测试
完成

Ubuntu/Debian编译

1. 安装编译依赖

sudo apt update
sudo apt install -y \
    build-essential \
    libssl-dev \
    libc-ares-dev \
    uuid-dev \
    wget \
    cmake

2. 下载源码

# 访问 https://mosquitto.org/files/source/ 获取最新版本
cd /tmp
wget https://mosquitto.org/files/source/mosquitto-2.0.18.tar.gz

# 解压
tar -xvzf mosquitto-2.0.18.tar.gz
cd mosquitto-2.0.18

3. 编译安装

# 配置编译选项
cmake -B build \
  -DCMAKE_INSTALL_PREFIX=/usr \
  -DWITH_THREADING=ON \
  -DWITH_TLS=ON \
  -DWITH_TLS_PSK=ON \
  -DWITH_BRIDGE=ON

# 编译
cd build
make -j$(nproc)

# 安装
sudo make install

# 配置动态链接库
sudo ldconfig

4. 创建服务配置

# 创建mosquitto用户
sudo useradd -r -s /sbin/nologin mosquitto

# 创建必要目录
sudo mkdir -p /etc/mosquitto
sudo mkdir -p /var/lib/mosquitto
sudo chown mosquitto:mosquitto /var/lib/mosquitto

# 复制配置文件
sudo cp /tmp/mosquitto-2.0.18/mosquitto.conf /etc/mosquitto/

5. 创建systemd服务

sudo cat > /etc/systemd/system/mosquitto.service << 'EOF'
[Unit]
Description=Mosquitto MQTT Broker
After=network.target

[Service]
Type=notify
User=mosquitto
Group=mosquitto
ExecStart=/usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf
Restart=on-failure
ExecReload=/bin/kill -HUP $MAINPID

[Install]
WantedBy=multi-user.target
EOF

# 重新加载systemd
sudo systemctl daemon-reload

# 启动服务
sudo systemctl start mosquitto
sudo systemctl enable mosquitto

CentOS/RHEL编译

# 安装依赖
sudo yum groupinstall -y "Development Tools"
sudo yum install -y openssl-devel c-ares-devel libuuid-devel wget cmake

# 下载和编译（与Ubuntu相同步骤）
cd /tmp
wget https://mosquitto.org/files/source/mosquitto-2.0.18.tar.gz
tar -xvzf mosquitto-2.0.18.tar.gz
cd mosquitto-2.0.18
make
sudo make install
sudo ldconfig

macOS编译

# 安装依赖
brew install openssl cmake

# 下载源码并编译
cd /tmp
curl -O https://mosquitto.org/files/source/mosquitto-2.0.18.tar.gz
tar -xvzf mosquitto-2.0.18.tar.gz
cd mosquitto-2.0.18
make
sudo make install

2.7 安装验证与测试

完整验证流程

渲染错误: Mermaid 渲染失败: Parse error on line 10: ...ss -->|否| Error[排查故障]) -----------------------^ Expecting 'SQE', 'TAGEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'STADIUMEND'

详细验证步骤

1. 版本检查

# 检查Mosquitto版本
mosquitto --version

# 检查客户端工具版本
mosquitto_pub --version
mosquitto_sub --version

2. 服务状态检查

Linux:

# 检查服务状态
sudo systemctl status mosquitto

# 检查进程
ps aux | grep mosquitto

# 检查监听端口
sudo netstat -tulpn | grep mosquitto
# 或
sudo ss -tulpn | grep mosquitto

macOS (Homebrew):

brew services list | grep mosquitto
ps aux | grep mosquitto
lsof -i :1883

Windows:

Get-Service | Where-Object {$_.Name -like "*mosquitto*"}
netstat -ano | findstr :1883

Docker:

docker ps | grep mosquitto
docker logs mosquitto

3. 连接测试

终端2(发布) Mosquitto Broker 终端1(订阅) 终端2(发布) Mosquitto Broker 终端1(订阅) 等待消息 SUBSCRIBE test/ PUBLISH test/hello mosquitto_pub -t "test/hello" -m "Hello!" 转发消息 test/hello Hello!

测试步骤：

# 终端1：启动订阅
mosquitto_sub -v -t "test/#"

# 终端2：发布消息
mosquitto_pub -t "test/hello" -m "Hello Mosquitto!"
mosquitto_pub -t "test/world" -m "World of MQTT!"
mosquitto_pub -t "test/number" -m "42"

# 终端1应该看到：
# test/hello Hello Mosquitto!
# test/world World of MQTT!
# test/number 42

4. 完整功能测试

# 测试QoS级别
mosquitto_pub -t "test/qos0" -m "QoS 0" -q 0
mosquitto_pub -t "test/qos1" -m "QoS 1" -q 1
mosquitto_pub -t "test/qos2" -m "QoS 2" -q 2

# 测试保留消息
mosquitto_pub -t "test/retained" -m "保留消息" -r

# 新终端订阅验证保留消息
mosquitto_sub -t "test/retained" -C 1

# 测试遗嘱消息（终端3）
mosquitto_sub -t "test/will" -i "test_client"

# 另一终端连接时设置遗嘱
mosquitto_pub -h localhost -t "test/topic" -m "正常消息" \
  -will-topic "test/will" \
  -will-payload "客户端异常断开" \
  -will-qos 1 \
  -will-retain

5. 检查日志

Linux:

# 查看systemd日志
sudo journalctl -u mosquitto -f

# 查看配置的日志文件
tail -f /var/log/mosquitto/mosquitto.log

Docker:

docker logs -f mosquitto

故障排查指南

服务无法启动
检查日志
端口被占用
配置文件错误
权限问题
修改配置端口
修复配置文件
设置正确权限
重启服务

常见问题解决：

1. 端口被占用

# 查找占用端口的进程
sudo lsof -i :1883
sudo netstat -tulpn | grep :1883

# 停止占用进程或修改配置

2. 权限问题

# 设置正确的文件权限
sudo chown -R mosquitto:mosquitto /etc/mosquitto
sudo chown -R mosquitto:mosquitto /var/lib/mosquitto
sudo chown -R mosquitto:mosquitto /var/log/mosquitto

3. 配置文件错误

# 测试配置文件
mosquitto -c /etc/mosquitto/mosquitto.conf -t

2.8 多实例部署

场景说明

多实例部署
开发测试环境
多租户隔离
负载均衡测试

配置示例

实例1配置

# 配置文件
sudo cp /etc/mosquitto/mosquitto.conf /etc/mosquitto/mosquitto-1.conf

sudo cat > /etc/mosquitto/mosquitto-1.conf << 'EOF'
listener 1883
allow_anonymous true
persistence true
persistence_location /var/lib/mosquitto1/
pid_file /var/run/mosquitto1.pid
EOF

实例2配置

sudo cat > /etc/mosquitto/mosquitto-2.conf << 'EOF'
listener 1884
allow_anonymous true
persistence true
persistence_location /var/lib/mosquitto2/
pid_file /var/run/mosquitto2.pid
EOF

启动多实例

# 创建数据目录
sudo mkdir -p /var/lib/mosquitto1 /var/lib/mosquitto2
sudo chown mosquitto:mosquitto /var/lib/mosquitto1 /var/lib/mosquitto2

# 启动实例1
sudo /usr/sbin/mosquitto -c /etc/mosquitto/mosquitto-1.conf -d

# 启动实例2
sudo /usr/sbin/mosquitto -c /etc/mosquitto/mosquitto-2.conf -d

# 验证
ps aux | grep mosquitto

2.9 本章小结

安装方式总结

安装方式	难度	适用场景	推荐度
包管理器	⭐ 简单	开发学习	⭐⭐⭐⭐⭐
Windows安装包	⭐ 简单	Windows用户	⭐⭐⭐⭐⭐
Docker	⭐⭐ 中等	快速部署、隔离	⭐⭐⭐⭐⭐
源码编译	⭐⭐⭐ 较难	生产环境、定制	⭐⭐⭐

安装检查清单

安装完成检查
✓ 版本验证
✓ 服务运行
✓ 端口监听
✓ 防火墙配置
✓ 连接测试
🎉 安装成功

下章预告

第3章：MQTT核心概念详解

• 发布/订阅模式深入讲解
• 主题设计与通配符使用
• QoS质量等级详解
• 保留消息与遗嘱消息
• 会话管理机制

---

🎯 思考与练习

实践题

1. 在你的系统上安装Mosquitto，并完成基本连接测试
2. 使用Docker方式部署Mosquitto，并配置持久化存储
3. 尝试运行多个Mosquitto实例，使用不同端口

进阶题

1. 编写一个自动化安装脚本，实现Mosquitto的一键部署
2. 配置Mosquitto开机自启，并测试重启后的服务状态
3. 对比不同安装方式的资源占用情况

---

⏭️ 下一章：第3章 MQTT核心概念详解

📚 返回：完整教程目录