bitrox/alpine-mosquitto-certbot

alpine-mosquitto-certbot镜像概述

该镜像基于轻量的Alpine Linux系统，整合了https://mosquitto.org/%E4%B8%8Ehttps://certbot.eff.org/%E5%B7%A5%E5%85%B7%EF%BC%8C%E6%97%A8%E5%9C%A8%E7%AE%80%E5%8C%96%E5%AE%89%E5%85%A8MQTT broker的部署流程，解决传统镜像中安全配置复杂的痛点，帮助开发者和家庭用户轻松实现物联网设备的加密通信。

核心功能

1. 自动证书管理：通过Certbot与LetsEncrypt集成，自动完成TLS/SSL证书的获取与续期，保障MQTT通信的加密安全。
2. 多协议支持：提供非加密MQTT（1883端口）、加密MQTT（8883端口）和WebSocket（8083端口）三种通信方式，适配不同场景需求。
3. 安全增强：默认禁用***访问，支持用户密码认证，有效防止未授权访问。
4. 持久化存储：通过卷映射保存配置文件、日志和证书，确保数据不丢失。
5. 自定义扩展：支持启动时执行自定义脚本，满足个性化配置需求。

使用场景

• 智能家居集成：与Home Assistant等平台配合，实现智能设备的安全通信。
• IoT设备通信：为物联网设备提供可靠的加密消息队列服务。
• 云端/本地部署：支持在云服务器或本地设备上快速搭建安全的MQTT broker。

配置说明

Docker Compose部署示例

yaml
version: '2'
services:
  mqtt:
    image: docker.xuanyuan.run/bitrox/alpine-mosquitto-certbot
    networks:
      - backend-net
    ports:
      - 1883:1883
      - 8083:8083
      - 8883:8883
      - 80:80
    environment:
      - DOMAIN=mqtt.myserver.com
      - EMAIL=myemail@myprovider.com
    volumes:
      - ./mosquitto/conf/:/mosquitto/conf
      - ./mosquitto/log/:/mosquitto/log
      - ./letsencrypt:/etc/letsencrypt
      - ./scripts:/scripts
    container_name: mqtt
    restart: always
networks:
  backend-net:
    external:
      name: backend-net

环境变量

• DOMAIN（必填）：MQTT服务的域名（如mqtt.myserver.com），需指向服务器以完成LetsEncrypt证书验证。
• EMAIL（必填）：用于Certbot注册的***地址，用于接收证书相关通知。
• TESTCERT（可选）：设置任意值（如TRUE）时，使用LetsEncrypt测试服务器获取证书，避免触发正式服务器的请求限制。

卷映射

• /mosquitto/conf/：存储Mosquitto配置文件（如mosquitto.conf、用户密码文件passwd）。
• /mosquitto/log/：存储Mosquitto日志文件，用于故障排查。
• /letsencrypt/：存储Certbot获取的TLS/SSL证书。
• /scripts/：存放启动时执行的自定义脚本（以.sh结尾），按文件名顺序执行。

Certbot集成逻辑

1. 容器启动时检查证书是否存在：不存在则自动获取，存在则尝试续期。
2. 每周自动检查证书续期状态，若续期成功则重启Mosquitto以应用新证书（会有短暂服务中断）。

Mosquitto配置示例

# Mosquitto配置文件
# 通用配置
user mosquitto

# 默认监听器（非加密MQTT）
port 1883
protocol mqtt

# WebSocket监听器（加密）
listener 8083
protocol websockets 
cafile /etc/letsencrypt/live/mqtt.bitrox.io/chain.pem
certfile /etc/letsencrypt/live/mqtt.bitrox.io/fullchain.pem
keyfile /etc/letsencrypt/live/mqtt.bitrox.io/privkey.pem

# 加密MQTT监听器
listener 8883
protocol mqtt
cafile /etc/letsencrypt/live/mqtt.bitrox.io/chain.pem
certfile /etc/letsencrypt/live/mqtt.bitrox.io/fullchain.pem
keyfile /etc/letsencrypt/live/mqtt.bitrox.io/privkey.pem

# 日志配置
log_dest file /mosquitto/log/mosquitto.log
log_type all
websockets_log_level 255
connection_messages true
log_timestamp true

# 安全配置
allow_anonymous false
password_file /mosquitto/conf/passwd

生成用户密码

使用以下命令添加MQTT用户（容器名为mqtt）：

bash
docker exec -it mqtt mosquitto_passwd -b /mosquitto/conf/passwd 用户名 密码

测试服务器

1. 本地测试：
   • 订阅消息（终端1）：

     bash
     docker exec -it mqtt /bin/bash
     mosquitto_sub -h <服务器地址> -u "用户名" -P "密码" -t "testQueue"
     

   • 发布消息（终端2）：

     bash
     docker exec -it mqtt /bin/bash
     mosquitto_pub -h <服务器地址> -u "用户名" -P "密码" -t "testQueue" -m "测试消息"
     

2. 远程测试：使用https://hobbyquaker.github.io/mqtt-admin/%E5%B7%A5%E5%85%B7%E8%BF%9B%E8%A1%8C%E8%BF%9C%E7%A8%8B%E8%BF%9E%E6%8E%A5%E6%B5%8B%E8%AF%95%EF%BC%88%E9%9C%80%E7%A1%AE%E4%BF%9D%E9%98%B2%E7%81%AB%E5%A2%99%E5%BC%80%E6%94%BE%E5%AF%B9%E5%BA%94%E7%AB%AF%E5%8F%A3%EF%BC%89%E3%80%82