eclipse/hono-service-auth

Eclipse Hono Docker镜像文档

1. 镜像概述和主要用途

Eclipse Hono 是一个开源的 IoT 设备连接平台，旨在为 IoT 设备与后端系统（如云端平台）之间提供统一的服务接口。该 Docker 镜像封装了 Eclipse Hono 的核心服务组件，简化了平台的部署与运维流程，帮助用户快速构建稳定、可扩展的设备连接基础设施，实现设备数据的采集、转发与管理。

2. 核心功能和特性

2.1 统一设备连接接口

• 提供标准化的南北向接口，屏蔽底层设备协议差异，简化设备与后端系统的集成。

2.2 多协议支持

• 原生支持 MQTT、HTTP、CoAP 等主流 IoT 协议，可通过扩展支持 LwM2M、OPC UA 等工业协议。

2.3 设备身份管理

• 内置设备认证与授权机制，支持设备注册、身份验证及权限控制，确保接入设备的合法性。

2.4 消息路由与转发

• 支持基于规则的消息路由，可将设备遥测数据、事件通知定向转发至 Kafka、AMQP 等后端消息系统或业务服务。

2.5 可扩展性设计

• 采用微服务架构，核心组件（如设备注册表、协议适配器、消息路由器）可独立水平扩展，适应大规模设备接入场景。

2.6 遥测数据与命令下发

• 支持设备上行遥测数据采集与下行控制命令下发，实现双向通信。

3. 使用场景和适用范围

3.1 典型使用场景

• 工业 IoT 设备集成：连接工厂传感器、机床等设备，采集生产数据并转发至 MES、ERP 系统。
• 智能家居设备管理：统一管理智能家电、安防设备，实现数据上报与远程控制。
• 智慧城市传感器网络：接入交通信号灯、环境监测传感器，汇聚城市运行数据。
• 物流追踪设备数据采集：处理物流车辆、包裹追踪设备的位置、状态信息。
• 环境监测系统：收集气象站、水质监测仪等设备的环境数据，支持实时分析。

3.2 适用范围

• IoT 解决方案开发人员：快速搭建设备连接层，聚焦业务逻辑开发。
• 企业 IT 运维团队：通过容器化部署简化 Hono 平台的安装、升级与监控。
• 需要构建设备连接平台的组织：如制造业、能源、交通等领域的企业或服务提供商。

4. 使用方法和配置说明

4.1 前提条件

• Docker Engine 20.10 及以上版本
• Docker Compose 2.0 及以上版本（推荐用于多组件部署）
• 至少 2GB 可用内存，5GB 可用磁盘空间
• 网络环境需开放镜像运行所需端口（如 AMQP、HTTP 端口）

4.2 获取镜像

从 Docker Hub 拉取官方镜像：

bash
docker pull docker.xuanyuan.run/eclipse/hono:latest

如需指定版本，可替换 latest 为具体版本号（如 2.4.0）：

bash
docker pull docker.xuanyuan.run/eclipse/hono:2.4.0

4.3 基本运行命令

以下命令启动 Hono 核心服务，映射默认端口并后台运行：

bash
docker run -d \
  --name hono-service \
  --publish 5672:5672 \  # AMQP 协议端口（设备连接）
  --publish 8080:8080 \  # HTTP 协议端口（设备连接/API）
  --publish 15672:15672 \ # 管理控制台端口
  --env HONO_LOG_LEVEL=INFO \
  --env HONO_AUTH_ENABLED=true \
  eclipse/hono:latest

4.4 Docker Compose 部署示例

对于生产环境，推荐使用 Docker Compose 管理多组件部署（如协议适配器、设备注册表、消息 broker 等）。以下为基础配置示例（docker-compose.yml）：

yaml
version: '3.8'

services:
  hono-service:
    image: docker.xuanyuan.run/eclipse/hono:latest
    container_name: hono-core
    restart: always
    ports:
      - "5672:5672"   # AMQP 端口
      - "8080:8080"   # HTTP 端口
      - "15672:15672" # 管理控制台
    environment:
      - HONO_AMQP_PORT=5672
      - HONO_HTTP_PORT=8080
      - HONO_LOG_LEVEL=INFO
      - HONO_AUTH_ENABLED=true
      - HONO_DB_URL=jdbc:postgresql://hono-db:5432/hono  # 数据库连接URL
      - HONO_DB_USER=hono
      - HONO_DB_PASSWORD=hono-pass
    depends_on:
      - hono-db
    networks:
      - hono-network

  hono-db:
    image: docker.xuanyuan.run/postgres:14-alpine
    container_name: hono-db
    restart: always
    environment:
      - POSTGRES_DB=hono
      - POSTGRES_USER=hono
      - POSTGRES_PASSWORD=hono-pass
    volumes:
      - hono-db-data:/var/lib/postgresql/data
    networks:
      - hono-network

networks:
  hono-network:
    driver: bridge

volumes:
  hono-db-data:

启动命令：

bash
docker-compose up -d

4.5 配置文件挂载

如需自定义 Hono 配置（如协议适配器参数、消息路由规则），可通过挂载配置文件实现。示例：

bash
docker run -d \
  --name hono-service \
  --publish 5672:5672 \
  --publish 8080:8080 \
  --volume /path/to/local/config:/etc/hono \  # 本地配置文件目录挂载至容器内
  eclipse/hono:latest

容器内配置文件路径默认为 /etc/hono，支持 .properties 或 .yml 格式配置文件。

5. 配置参数与环境变量

5.1 核心环境变量说明

5.2 配置文件说明

容器内默认配置文件路径为 /etc/hono/config.yml，可通过挂载本地文件覆盖默认配置。配置文件支持自定义协议适配器参数、消息路由规则、缓存策略等高级选项，详细配置项可参考 https://www.eclipse.org/hono/docs/admin-guide/configuration/。