efrecon/mqtt-client

MQTT Client 镜像文档

镜像概述和主要用途

基于Alpine的轻量级镜像，包含mosquitto MQTT客户端工具（mosquitto_sub和mosquitto_pub），用于订阅和发布MQTT主题。镜像内置Mozilla根证书列表，支持与主流CA签名的远程服务器安全通信，同时提供/opt/certs卷用于放置自定义CA或客户端证书。

核心功能和特性

• 轻量级基础：基于Alpine构建，镜像体积小，资源占用低
• 完整工具集：包含mosquitto_sub（订阅）和mosquitto_pub（发布）工具
• 证书支持：内置Mozilla根证书，同时支持通过/opt/certs卷挂载自定义证书
• 快捷命令：提供pub和sub快捷命令，简化操作（替代完整命令mosquitto_pub和mosquitto_sub）
• 信号处理：通过tini作为入口点，确保客户端可从命令行正常中断
• 版本同步：镜像标签与Alpine中包含的mosquitto版本同步，通过GitHub工作流自动构建

使用场景和适用范围

• MQTT消息通信测试与调试
• IoT设备数据上报与订阅
• 简单的MQTT主题数据发布/接收任务
• 需要轻量级MQTT客户端的容器化环境

使用方法和配置说明

基本使用说明

镜像暴露/opt/certs卷，可用于放置CA证书或客户端证书以实现可信通信。内置的Mozilla根证书允许连接到主流CA签名的远程服务器，无需额外配置。

订阅主题

使用sub命令（或完整命令mosquitto_sub）订阅主题。以下示例连接到测试服务器并订阅所有主题（#通配符），-v参数显示接收到的 payload：

bash
docker run -it --rm efrecon/mqtt-client sub \
        -h test.mosquitto.org \
        -t "#" \
        -v

连接TLS安全服务器（如端口8883）时，可指定证书路径：

bash
docker run -it --rm efrecon/mqtt-client sub \
        -h iot.eclipse.org \
        -p 8883 \
        --capath /etc/ssl/certs \
        -t "#" \
        -v

发布主题

使用pub命令（或完整命令mosquitto_pub）发布消息。以下示例向test/testdevice主题发布JSON数据：

bash
docker run -it --rm efrecon/mqtt-client pub \
        -h test.mosquitto.org \
        -p 1883 \
        -t "test/testdevice" \
        -m '[{"json":"validated","data":42},{"to":2,"test":"with"}]'

发布文件中的复杂数据时，需挂载本地目录。例如发布当前目录下的datafile.json：

bash
docker run -it --rm -v ${PWD}:/data/ efrecon/mqtt-client pub \
        -h test.mosquitto.org \
        -p 1883 \
        -t "test/testdevice" \
        -f /data/datafile.json

调试

遇到连接问题时，建议使用-d参数开启调试模式，查看连接详情：

bash
docker run -it --rm efrecon/mqtt-client sub \
        -h test.mosquitto.org \
        -t "#" \
        -d

部分MQTT服务器要求指定客户端ID，可通过-i参数设置：

bash
docker run -it --rm efrecon/mqtt-client pub \
        -h test.mosquitto.org \
        -t "test/testdevice" \
        -i "my-client-id" \
        -m "test message"

在macOS上运行

在macOS系统上运行时，需指定平台：

bash
docker run --platform linux/amd64 -it --rm efrecon/mqtt-client sub -h test.mosquitto.org -t "#" -v

技术说明

• 证书处理：镜像构建时通过调用/etc/ca-certificates/update.d/certhash重新哈希证书 bundle，确保mosquitto正确识别证书
• 进程管理：客户端工具通过tini作为入口点运行，支持从命令行正常中断（如Ctrl+C）
• 版本控制：镜像标签与Alpine中包含的mosquitto版本保持一致，通过GitHub工作流自动构建（https://github.com/efrecon/docker-images/blob/master/.github/workflows/mqtt.yml%EF%BC%89