Eclipse Hono MQTT协议适配器 Docker镜像文档

1. 镜像概述和主要用途

Eclipse Hono MQTT协议适配器是Eclipse Hono项目的核心组件之一，提供基于MQTT协议的设备接入能力。作为IoT设备与后端服务之间的协议转换桥梁，其主要用途是通过统一的服务接口，实现IoT设备通过MQTT协议向（云）后端上传遥测数据和事件，从而简化设备与后端系统的集成流程。

2. 核心功能和特性

2.1 核心功能

• MQTT协议支持：兼容MQTT协议规范，允许IoT设备通过MQTT连接建立与适配器的通信
• 遥测数据上传：支持设备通过发布消息到特定MQTT主题（如telemetry/<tenant_id>/<device_id>）上传周期性或实时遥测数据
• 事件上传：支持设备通过发布消息到特定MQTT主题（如event/<tenant_id>/<device_id>）上报非周期性事件（如设备状态变更、异常告警）
• 协议适配：将MQTT消息转换为Hono内部统一格式，转发至后端服务进行处理

2.2 关键特性

• 轻量级协议适配，低资源占用，适合边缘设备场景
• 支持多租户设备接入，通过主题路径区分租户与设备标识
• 与Hono生态系统无缝集成，兼容Hono的设备管理、认证授权机制

3. 使用场景和适用范围

3.1 典型使用场景

• 传感器设备（如温湿度传感器、压力传感器）通过MQTT周期性上传监测数据
• 嵌入式设备（如工业控制器、智能家居终端）上报状态变更事件
• 低功耗设备通过MQTT over TCP/SSL连接实现数据高效传输

3.2 适用范围

• 工业物联网（IIoT）：生产线设备数据采集、设备健康状态监控
• 智能家居：家电设备状态上报、环境控制指令反馈
• 环境监测：气象站、空气质量监测设备数据上传
• 物流追踪：GPS终端位置信息实时上报

4. 使用方法和配置说明

4.1 Docker运行命令示例

docker run -d \
  --name hono-mqtt-adapter \
  -p 1883:1883 \  # MQTT默认端口（非加密）
  -p 8883:8883 \  # MQTT加密端口（SSL/TLS）
  -e MQTT_ADAPTER_HOST=0.0.0.0 \
  -e MQTT_ADAPTER_PORT=1883 \
  -e MQTT_ADAPTER_SECURE_PORT=8883 \
  -e HONO_AUTH_HOST=hono-auth-service \  # Hono认证服务地址
  -e HONO_AUTH_PORT=5671 \              # Hono认证服务端口
  -e TENANT_ID=default-tenant \         # 默认租户ID（可选）
  eclipse/hono-mqtt-adapter:latest

4.2 Docker Compose配置示例

version: '3.8'
services:
  hono-mqtt-adapter:
    image: eclipse/hono-mqtt-adapter:latest
    container_name: hono-mqtt-adapter
    ports:
      - "1883:1883"   # MQTT非加密端口
      - "8883:8883"   # MQTT加密端口
    environment:
      - MQTT_ADAPTER_HOST=0.0.0.0
      - MQTT_ADAPTER_PORT=1883
      - MQTT_ADAPTER_SECURE_PORT=8883
      - HONO_AUTH_HOST=hono-auth-service  # 需与Hono认证服务容器名/IP对应
      - HONO_AUTH_PORT=5671
      - LOG_LEVEL=INFO  # 日志级别（DEBUG/INFO/WARN/ERROR）
    restart: unless-stopped
    networks:
      - hono-network  # 需与Hono其他服务处于同一网络

networks:
  hono-network:
    driver: bridge

4.3 核心配置参数（环境变量）

注意：完整配置参数请参考Eclipse Hono官方文档，根据实际部署环境调整认证、TLS证书等安全相关配置。

4.4 设备接入示例

设备通过MQTT客户端连接适配器，发布消息至指定主题：

• 遥测数据主题：telemetry/<tenant_id>/<device_id>
• 事件主题：event/<tenant_id>/<device_id>

示例（使用***_pub工具）：

# 发布遥测数据（租户：my-tenant，设备：sensor-001）
***_pub -h <adapter-IP> -p 1883 \
  -t "telemetry/my-tenant/sensor-001" \
  -m '{"temperature": 25.5, "humidity": 60}'