migoller/http-mqtt-bridge 镜像文档

1. 镜像概述

migoller/http-mqtt-bridge 是一个轻量级的 HTTP 到 MQTT 桥接工具，用于将 HTTP 请求转换为 MQTT 消息并转发至指定的 MQTT Broker。该工具最初设计用于解决 IFTTT（不原生支持 MQTT 服务）与 OpenHab 等智能家居系统的集成问题，通过接收 IFTTT Maker Webhooks 等 HTTP 请求，实现与 MQTT 设备/服务的通信。

2. 核心功能与特性

• HTTP-MQTT 协议转换：接收 HTTP POST 请求并将其内容转发为 MQTT 消息。
• 灵活配置：通过环境变量自定义 MQTT Broker 连接参数及安全认证。
• 安全认证：支持通过密钥（AUTH_KEY）验证 HTTP 请求合法性。
• 轻量级部署：基于 Docker 容器化部署，无需复杂依赖。

3. 使用场景

• 智能家居集成：将 IFTTT、Zapier 等平台的 HTTP Webhooks 事件转换为 MQTT 消息，控制支持 MQTT 的智能家居设备（如 OpenHab、Home Assistant）。
• 跨协议数据转发：需将 HTTP 接口数据（如传感器 HTTP 上报）同步至 MQTT 消息队列的场景。
• 简化 HTTP 转 MQTT 开发：无需手动开发桥接服务，直接通过容器快速部署。

4. 使用方法

4.1 环境变量配置

镜像通过以下环境变量配置核心参数，必须根据实际需求设置：

4.2 启动容器

4.2.1 基础启动命令（默认配置）

默认监听容器内 5000 端口，连接本地 MQTT Broker（实际使用需通过环境变量指定远程 Broker）：

docker run -d -p 5000:5000 migoller/http-mqtt-bridge

4.2.2 完整配置启动命令（推荐）

指定 MQTT Broker 连接参数及认证密钥：

docker run -d \
  -p 5000:5000 \
  -e AUTH_KEY=912ec803b2ce49e4a541068d495ab570 \  # 替换为自定义密钥
  -e MQTT_HOST=mqtts://k99.cloudmqtt.com:21234 \   # 替换为实际 MQTT Broker 地址
  -e MQTT_USER=<你的用户名> \                       # 替换为 MQTT 用户名
  -e MQTT_PASS=<你的密码> \                        # 替换为 MQTT 密码
  migoller/http-mqtt-bridge

5. 消息发布方法

容器启动后，可通过 HTTP POST 请求向 MQTT 主题发布消息，支持两种方式：

5.1 通过 JSON 请求体发布

发送包含 topic（目标 MQTT 主题）和 message（消息内容）的 JSON 数据：

curl -H "Content-Type: application/json" \
  "http://<Docker主机IP>:5000/post" \
  -d '{"topic": "MyTopic", "message": "Hello World"}'

响应：成功时返回 OK。

5.2 通过 URL 查询参数发布

通过 URL 参数 topic 指定目标主题，path 指定消息内容，适用于动态构建 URL 的场景：

http://<Docker主机IP>:5000/post?topic=/MyTopic/TestTopic&path=payload

• topic：目标 MQTT 主题（如 /MyTopic/TestTopic）。
• path：消息内容（如 payload）。

6. 安全配置（HTTPS 加密）

为保障传输安全，建议通过反向代理实现 HTTPS 加密。推荐使用以下容器组合：

• nginx-proxy：自动配置反向代理。
• docker-letsencrypt-nginx-proxy-companion：自动申请和续期 Let's Encrypt 证书。

具体配置请参考上述项目官方文档，通过设置 VIRTUAL_HOST、LETSENCRYPT_HOST 等环境变量实现 HTTP 到 HTTPS 的转发。

7. 致谢

本项目基于 petkov 的 HTTP to MQTT bridge（Node.js 实现）开发，感谢原作者提供的核心代码。