Eclipse Hono 镜像文档

1. 镜像概述和主要用途

Eclipse Hono 是一个开源物联网（IoT）设备连接中间件，提供统一的服务接口，用于将各类IoT设备无缝连接到云后端系统。其核心目标是简化异构设备（支持不同网络协议、数据格式）与后端应用之间的通信，抽象底层设备连接细节，使应用开发者无需关注具体设备协议，即可统一处理设备数据和控制指令。

2. 核心功能和特性

2.1 多协议设备接入

• 支持主流IoT协议适配，包括MQTT、HTTP、AMQP、CoAP等，实现不同协议设备的统一接入。
• 协议适配器组件（如MQTT Adapter、HTTP Adapter）负责协议转换和消息处理。

2.2 设备身份与生命周期管理

• 提供设备注册表（Device Registry），支持设备身份注册、认证信息管理（如凭证、TLS证书）及状态跟踪（在线/离线）。
• 支持设备身份动态更新和生命周期状态管理（激活、禁用、删除）。

2.3 数据传输与消息路由

• 高效传输设备遥测数据（Telemetry Data）和事件数据（Event Data）至后端服务。
• 支持基于规则的消息路由，可集成Kafka、RabbitMQ等消息中间件作为底层消息 backbone。

2.4 双向通信能力

• 支持从后端向下游设备下发命令（Command & Control），实现远程设备控制。
• 提供命令状态跟踪（待处理、已执行、失败）和结果反馈机制。

2.5 安全性保障

• 强制TLS加密所有设备-云端通信，支持设备证书认证（X.509）和令牌认证（JWT）。
• 基于角色的访问控制（RBAC），限制设备和应用的操作权限。

3. 使用场景和适用范围

3.1 典型使用场景

• 工业物联网（IIoT）：连接工厂中的传感器、机床等设备，统一采集生产数据并下发控制指令。
• 智能家居：整合不同厂商的智能设备（灯光、温控、安防），通过统一接口实现数据上报和远程控制。
• 物流与资产追踪：管理运输车辆、集装箱等移动设备，实时传输位置、温湿度等状态数据。
• 智慧城市：接入交通信号灯、环境监测站等城市基础设施，实现数据汇总与远程运维。

3.2 适用范围

• 需管理大规模异构设备（不同协议、厂商、数据格式）的场景。
• 要求高可靠性消息传输（数据不丢失、顺序保证）的应用。
• 需端到端安全性（加密、认证、授权）的 IoT 系统。
• 需要解耦设备层与应用层，简化后端开发的架构设计。

4. 详细使用方法和配置说明

4.1 镜像拉取

Eclipse Hono 官方镜像托管于 Docker Hub，可通过以下命令拉取最新版本：

docker pull eclipse/hono:latest

4.2 基本运行命令（docker run）

以下为单节点快速启动示例，仅用于测试（生产环境需配置外部消息中间件和持久化存储）：

docker run -d \
  --name hono \
  -p 1883:1883  # MQTT 端口 \
  -p 8080:8080  # HTTP 端口 \
  -p 5672:5672  # AMQP 端口 \
  -e HONO_REGISTRY_TYPE=in-memory  # 使用内存设备注册表（测试用） \
  -e HONO_AUTH_MODE=anonymous  # 允许匿名访问（测试用） \
  eclipse/hono:latest

4.3 Docker Compose 部署示例（生产环境参考）

生产环境需集成消息中间件（如 Kafka）、持久化设备注册表（如 PostgreSQL）及 TLS 配置。以下为 docker-compose.yml 示例：

version: '3.8'

services:
  # Kafka 消息中间件（用于消息路由和持久化）
  kafka:
    image: confluentinc/cp-kafka:7.3.0
    ports:
      - "9092:9092"
    environment:
      - KAFKA_ADVERTISED_LISTENERS=PLAINTEXT://kafka:9092
      - KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR=1
    volumes:
      - kafka-data:/var/lib/kafka/data

  # Hono 设备注册表（使用 PostgreSQL 持久化）
  hono-registry:
    image: eclipse/hono-registry:latest
    depends_on:
      - kafka
    environment:
      - SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/hono  # PostgreSQL 连接
      - SPRING_DATASOURCE_USERNAME=hono
      - SPRING_DATASOURCE_PASSWORD=securepassword
      - HONO_KAFKA_BOOTSTRAP_SERVERS=kafka:9092  # 连接 Kafka
    ports:
      - "28080:28080"  # 设备注册表 API 端口

  # MQTT 协议适配器
  hono-mqtt-adapter:
    image: eclipse/hono-mqtt-adapter:latest
    depends_on:
      - hono-registry
      - kafka
    environment:
      - HONO_REGISTRY_HOST=hono-registry
      - HONO_REGISTRY_PORT=28080
      - HONO_KAFKA_BOOTSTRAP_SERVERS=kafka:9092
      - HONO_MQTT_ADAPTER_PORT=1883
    ports:
      - "1883:1883"

  # HTTP 协议适配器
  hono-http-adapter:
    image: eclipse/hono-http-adapter:latest
    depends_on:
      - hono-registry
      - kafka
    environment:
      - HONO_REGISTRY_HOST=hono-registry
      - HONO_REGISTRY_PORT=28080
      - HONO_KAFKA_BOOTSTRAP_SERVERS=kafka:9092
      - HONO_HTTP_ADAPTER_PORT=8080
    ports:
      - "8080:8080"

volumes:
  kafka-data:  # Kafka 数据持久化卷

5. 配置参数与环境变量

5.1 核心配置参数

5.2 协议适配器端口配置

6. 设备连接与数据交互流程

6.1 设备注册

1. 通过 Hono 设备注册表 API 注册设备：

   POST http://<hono-host>:28080/v1/devices/<tenant-id>/<device-id>
   Content-Type: application/json
   {
     "credentials": [{"type": "hashed-password", "auth-id": "device1", "secrets": [{"pwd-plain": "secret"}]}]
   }
   

6.2 遥测数据上报（MQTT 示例）

设备通过 MQTT 连接并发送遥测数据：

***_pub -h <hono-host> -p 1883 \
  -u "<tenant-id>:<device-id>" -P "secret" \
  -t "telemetry" \
  -m '{"temperature": 25.5, "humidity": 60}'

6.3 命令下发（HTTP 示例）

后端应用通过 HTTP 向下发命令：

POST http://<hono-host>:8080/v1/commands/<tenant-id>/<device-id>
Content-Type: application/json
{
  "command": "set_frequency",
  "parameters": {"value": 50}
}