文档中心

Appearance

Mosquitto Broker 生产环境部署与安全配置 ​

Eclipse Mosquitto 是一个轻量级且极具性价比的高性能开源 MQTT 代理。本文档提供在生产环境下的安全加固部署方案，包括容器化、SSL 加密配置以及基于主题的**访问控制列表（ACL）**设计。

1. 部署拓扑 (Docker Compose) ​

在生产环境中，我们通过 Docker Compose 快速容器化部署 Mosquitto，并挂载物理主机的持久化数据卷。

1.1 docker-compose.yml 配置 ​

在项目根目录的 /docker/mosquitto 路径下创建部署文件：

yaml
version: '3.8'

services:
  mosquitto:
    image: eclipse-mosquitto:2.0.18
    container_name: mosquitto_broker
    restart: always
    ports:
      - "1883:1883" # 默认 TCP 监听器 (限内网/本地调试)
      - "8883:8883" # 安全 SSL/TLS 监听器 (公网生产接口)
      - "9001:9001" # 供网页端连接的安全 WebSocket (WSS) 接口
    volumes:
      - ./config:/mosquitto/config:ro
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log
      # 挂载 SSL 证书 (例如 Let's Encrypt 目录)
      - /etc/letsencrypt:/etc/letsencrypt:ro
    user: "1883:1883" # 强制以安全 UID 运行，防止容器越权

2. 身份认证与密码文件 (Password File) ​

为了保障 Broker 的安全，必须禁用匿名登录，并强制启用密码验证。

2.1 创建静态加密账号 ​

  1. 进入 Mosquitto 运行容器:
    bash
    docker exec -it mosquitto_broker sh
  2. 生成密码加密文件: 通过 mosquitto_passwd 命令行工具来对密码实施 SHA-512 加密存储：
    bash
    # 创建密码文件，并添加后台服务账号 (如果文件已存在，请移除 -c 参数)
mosquitto_passwd -c /mosquitto/config/password_file backend_service

# 按照提示输入密码
# 接着为新设备添加一个静态绑定账号
mosquitto_passwd -b /mosquitto/config/password_file device_client_01 secret_token_abc

3. 精细化访问控制 (ACL 配置) ​

即使密码认证通过，设备如果可以订阅任意主题，也会带来极高的安全隐患。我们需要通过访问控制列表（ACL）将每个设备物理上隔离在它自己的客户端专属主题路径下。

3.1 编写 mosquitto.acl ​

在挂载的 ./config/mosquitto.acl 中写入以下配置规则：

text
# ----------------------------------------------------
# 1. 业务后台服务角色
# ----------------------------------------------------
user backend_service
topic readwrite devices/#

# ----------------------------------------------------
# 2. 设备客户端通用隔离模板
# ----------------------------------------------------
# %c 占位符将被连接时的 ClientID 物理替换
# 设备只允许对与其自身 Client ID 匹配的子路径主题进行订阅和发布
pattern readwrite devices/%c/#
pattern read devices/%c/commands
pattern write devices/%c/telemetry
pattern write devices/%c/status

提示：在此 ACL 策略下，如果 Client ID 为 dev_f49b10a2 的设备尝试发布到 devices/other_device/telemetry，Broker 将直接拒绝，从而防止恶意设备假冒他人上报或篡改配置指令。

4. 全局配置文件 (mosquitto.conf) ​

将上述的密码、ACL 以及 SSL 证书路径整合到 ./config/mosquitto.conf 中：

ini
# =================================================================
# 1. 通用配置与持久化
# =================================================================
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
log_type error
log_type warning

# =================================================================
# 2. 安全与鉴权
# =================================================================
allow_anonymous false
password_file /mosquitto/config/password_file
acl_file /mosquitto/config/mosquitto.acl

# =================================================================
# 3. 监听器配置 (Listeners)
# =================================================================

# 默认 TCP 监听器
listener 1883 127.0.0.1

# 生产环境安全 SSL/TLS 监听器
listener 8883
certfile /etc/letsencrypt/live/mqtt.example.com/fullchain.pem
keyfile /etc/letsencrypt/live/mqtt.example.com/privkey.pem

# 安全 WebSocket (WSS) 监听器
listener 9001
protocol websockets
certfile /etc/letsencrypt/live/mqtt.example.com/fullchain.pem
keyfile /etc/letsencrypt/live/mqtt.example.com/privkey.pem

部署完成后，在宿主机上通过 docker-compose restart 应用所有安全设置。