Eclipse Hono HTTP协议适配器镜像文档

1. 镜像概述与主要用途

Eclipse Hono是一个开源IoT设备连接平台，提供统一的服务接口，用于将IoT设备连接到云端或本地后端系统。本镜像为Eclipse Hono的HTTP协议适配器组件，主要功能是允许IoT设备通过HTTP协议向Hono后端上传遥测数据和事件数据，实现设备与后端系统的双向通信。

2. 核心功能与特性

2.1 协议支持

• 支持HTTP/1.1协议，兼容标准HTTP请求方法（POST为主）。
• 支持HTTPS加密传输（需配置TLS证书）。

2.2 数据上传能力

• 遥测数据上传：支持设备周期性或实时上传传感器等遥测数据。
• 事件数据上传：支持设备上报非周期性事件（如状态变更、告警触发等）。

2.3 后端集成

• 与Hono后端服务（如AMQP适配器、认证服务、设备注册表）无缝集成，实现数据路由与处理。
• 支持Hono的设备认证与授权机制，确保数据上传合法性。

2.4 轻量级设计

• 低资源占用，适合边缘计算环境部署。
• 简化设备端集成，降低HTTP客户端实现复杂度。

3. 使用场景与适用范围

3.1 典型场景

• IoT设备HTTP数据上传：不支持MQTT、CoAP等协议的设备，通过HTTP/HTTPS向后端发送数据。
• 轻量级协议需求场景：设备资源受限（如低内存、低算力），需采用简单协议实现数据传输。
• 间歇性连接设备：设备网络不稳定，通过HTTP短连接上传数据可减少连接维护开销。
• Web使能设备：原生支持HTTP的设备（如基于Web技术的传感器）直接接入Hono平台。

3.2 适用设备类型

• 不支持MQTT/CoAP的传统工业设备。
• 基于HTTP客户端的嵌入式设备（如使用curl、wget或自定义HTTP库的设备）。
• 需通过RESTful接口与后端交互的IoT网关。

4. 使用方法与配置说明

4.1 前提条件

• 已部署Eclipse Hono后端服务（包括AMQP适配器、认证服务、设备注册表等）。
• 设备已在Hono设备注册表中注册，获取设备认证凭证（如租户ID、设备ID、密码/令牌）。
• 网络环境确保HTTP适配器与Hono后端服务（AMQP适配器、认证服务）网络可达。

4.2 镜像获取

从Docker镜像仓库拉取最新版本镜像：

docker pull eclipse/hono-http-adapter:latest

4.3 运行容器（docker run）

通过以下命令启动HTTP适配器容器，需根据实际环境配置环境变量：

docker run -d \
  --name hono-http-adapter \
  -p 8080:8080 \  # HTTP端口映射（默认8080）
  -e HONO_AMQP_HOST=hono-amqp-adapter \  # Hono AMQP适配器主机名/IP
  -e HONO_AMQP_PORT=5672 \               # Hono AMQP适配器端口
  -e HONO_AUTH_HOST=hono-auth \          # Hono认证服务主机名/IP
  -e HONO_AUTH_PORT=5671 \               # Hono认证服务端口
  -e HTTP_ADAPTER_PORT=8080 \            # HTTP适配器监听端口
  eclipse/hono-http-adapter:latest

4.4 环境变量配置

HTTP适配器通过环境变量配置与后端服务的连接及自身运行参数，常用配置如下表：

4.5 docker-compose部署示例

以下为与Hono核心服务（AMQP适配器、认证服务）协同部署的docker-compose.yml示例：

version: '3.8'
services:
  hono-http-adapter:
    image: eclipse/hono-http-adapter:latest
    ports:
      - "8080:8080"
    environment:
      - HONO_AMQP_HOST=hono-amqp-adapter
      - HONO_AMQP_PORT=5672
      - HONO_AUTH_HOST=hono-auth
      - HONO_AUTH_PORT=5671
      - HTTP_ADAPTER_PORT=8080
      - HONO_TENANT_ID=default-tenant
    depends_on:
      - hono-amqp-adapter
      - hono-auth

  hono-amqp-adapter:
    image: eclipse/hono-amqp-adapter:latest
    # AMQP适配器配置（省略，参考其官方文档）

  hono-auth:
    image: eclipse/hono-auth:latest
    # 认证服务配置（省略，参考其官方文档）

4.6 设备数据上传示例

设备通过HTTP POST请求向适配器发送数据，需在请求头中指定租户、设备标识及认证信息。

4.6.1 遥测数据上传（HTTP POST）

请求URL：http://<adapter-ip>:<port>/telemetry
请求头：

• Host: 适配器主机
• Content-Type: application/json（或其他数据格式）
• Authorization: Basic <base64(tenant:device@password)>（Basic认证）
  请求体：遥测数据（如JSON格式传感器读数）

示例（curl命令）：

# 设备认证信息：租户=my-tenant，设备ID=device-001，密码=secret
# Basic认证字符串：echo -n "my-tenant:device-001@secret" | base64 → bXktdGVuYW50OmRldmljZS0wMDFAc2VjcmV0
curl -X POST [***] \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic bXktdGVuYW50OmRldmljZS0wMDFAc2VjcmV0" \
  -d '{"temperature": 23.5, "humidity": 60}'

4.6.2 事件数据上传（HTTP POST）

请求URL：http://<adapter-ip>:<port>/events
请求头：与遥测数据上传相同
请求体：事件数据（如设备状态变更信息）

示例（curl命令）：

curl -X POST [***] \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic bXktdGVuYW50OmRldmljZS0wMDFAc2VjcmV0" \
  -d '{"event": "door_opened", "timestamp": "2024-05-20T10:30:00Z"}'

5. 注意事项

1. 认证要求：设备必须通过Hono认证服务校验（如用户名/密码或令牌），未认证请求将被拒绝（HTTP 401）。
2. 网络可达性：确保HTTP适配器容器可访问Hono AMQP适配器和认证服务，避免因网络隔离导致数据转发失败。
3. 端口冲突：若宿主机已占用HTTP_ADAPTER_PORT（默认8080），需通过-p参数映射至其他端口（如-p 8081:8080）。
4. HTTPS配置：生产环境建议启用HTTPS，需挂载TLS密钥库文件并配置TLS_ENABLED=true及相关密钥库参数。

6. 故障排查

• 设备无法连接：检查宿主机防火墙规则，确保HTTP_ADAPTER_PORT端口开放；验证容器启动日志（docker logs <container-id>）是否有端口绑定错误。
• 数据未送达后端：查看适配器日志中AMQP连接状态，确认HONO_AMQP_HOST和HONO_AMQP_PORT配置正确；检查Hono AMQP适配器是否正常运行。
• 认证失败：验证设备在Hono设备注册表中的注册状态，确认Authorization头中的租户、设备ID及密码是否正确。