FIWARE IoT Agent for JSON协议

![FIWARE IoT Agents]([] ![]([]

基于JSON协议的物联网代理（支持AMQP、HTTP和MQTT传输方式）。此IoT代理旨在作为JSON与上下文代理的NGSI接口之间的桥梁。

它基于IoT Agent Node.js Library构建。有关FIWARE IoT Agents框架的更多一般信息、架构和常见交互模型，可在该库的GitHub仓库中找到。

本项目是FIWARE的一部分。更多信息请查看FIWARE目录中的IoT Agents条目。

镜像概述和主要用途

该镜像提供了一个基于JSON协议的IoT代理，能够通过MQTT、HTTP、AMQP等多种传输方式接收IoT设备数据，并将其转换为NGSI格式与上下文代理（如Orion Context Broker）交互。主要用于构建IoT系统中设备与上下文管理平台之间的通信桥梁，实现设备数据的标准化接入和管理。

核心功能和特性

• 多传输协议支持：兼容HTTP、MQTT、AMQP等多种设备通信协议
• NGSI协议转换：将JSON格式的设备数据转换为NGSI标准格式，实现与上下文代理的交互
• 设备管理：支持设备注册、配置和状态跟踪，可通过环境变量配置存储方式（内存或MongoDB）
• 灵活部署：可通过Docker Compose快速部署，支持与Orion上下文代理、MongoDB等组件集成
• 可定制构建：支持从GitHub获取最新/稳定版本、特定版本，或从自定义fork、本地源码构建镜像

使用场景和适用范围

适用于需要将基于JSON协议的IoT设备数据接入FIWARE生态系统的场景，例如：

• 智能家居设备（通过MQTT/HTTP传输JSON数据）
• 工业传感器网络（通过AMQP协议传输设备状态）
• 需要标准化设备数据格式以对接上下文管理平台的IoT项目

详细使用方法和配置说明

如何使用此镜像

IoT代理必须实例化并连接到Orion Context Broker实例，以下是一个示例docker-compose文件。

如果设置IOTA_REGISTRY_TYPE=mongodb，则还需要MongoDB数据库实例——下方示例假设主机系统中有/data目录用于存储数据库文件，请根据实际配置修改挂载卷。

yml
version: "3.1"

volumes:
    mongodb: ~

services:
    iot-agent:
        image: fiware/iotagent-json
        hostname: iot-agent
        container_name: fiware-iot-agent
        depends_on:
            - mongodb
        expose:
            - "4041"
            - "7896"
        ports:
            - "4041:4041"
            - "7896:7896"
        environment:
            - "IOTA_CB_HOST=orion"
            - "IOTA_CB_PORT=1026"
            - "IOTA_NORTH_PORT=4041"
            - "IOTA_REGISTRY_TYPE=mongodb"
            - "IOTA_MONGO_HOST=mongodb"
            - "IOTA_MONGO_PORT=27017"
            - "IOTA_MONGO_DB=iotagent-json"
            - "IOTA_HTTP_PORT=7896"
            - "IOTA_PROVIDER_URL=[***]"

    mongodb:
        image: mongo:4.2
        hostname: mongodb
        container_name: db-mongo
        ports:
            - "27017:27017"
        command: --bind_ip_all --smallfiles
        volumes:
            - mongodb:/data

    orion:
        image: fiware/orion
        hostname: orion
        container_name: fiware-orion
        depends_on:
            - mongodb
        expose:
            - "1026"
        ports:
            - "1026:1026"
        command: -dbhost mongodb

配置与环境变量

许多设置可通过Docker环境变量配置。典型的IoT代理Docker容器由以下环境变量驱动：

• IOTA_CB_HOST - 用于更新上下文的上下文代理主机名
• IOTA_CB_PORT - 上下文代理监听上下文更新的端口
• IOTA_NORTH_PORT - 用于配置IoT代理和接收上下文代理更新的端口
• IOTA_REGISTRY_TYPE - IoT设备信息的存储方式（内存或数据库）
• IOTA_MONGO_HOST - MongoDB主机名（用于存储设备和服务信息）
• IOTA_MONGO_PORT - MongoDB监听端口
• IOTA_MONGO_DB - MongoDB中使用的数据库名称
• IOTA_HTTP_PORT - IoT代理监听HTTP设备流量的端口
• IOTA_PROVIDER_URL - 注册命令时传递给上下文代理的URL，用于上下文代理向设备下发命令时的转发地址

进一步信息

所有IoT代理通用参数的完整覆盖说明，可参见IoT Agent Library的安装指南中的配置部分。

JSON IoT代理特有的设置（如MQTT、AMQP和HTTP的特定配置），可参见JSON IoT代理的安装指南。

如何构建镜像

与此镜像关联的Dockerfile可通过多种方式构建镜像：

从默认代码库构建

• 默认情况下，Dockerfile从GitHub获取代码库的最新版本（build-arg为可选）：

console
docker build -t iot-agent . --build-arg DOWNLOAD=latest

• 可通过构建参数DOWNLOAD=stable获取最新稳定版本：

console
docker build -t iot-agent . --build-arg DOWNLOAD=stable

• 也可通过构建参数DOWNLOAD=<version>下载特定版本：

console
docker build -t iot-agent . --build-arg DOWNLOAD=1.7.0

从自定义fork构建

要从GitHub仓库的自定义fork下载代码，需在docker build命令中添加GITHUB_ACCOUNT、GITHUB_REPOSITORY和SOURCE_BRANCH参数（默认master）：

console
docker build -t iot-agent . \
    --build-arg GITHUB_ACCOUNT=<你的账户> \
    --build-arg GITHUB_REPOSITORY=<你的仓库> \
    --build-arg SOURCE_BRANCH=<你的分支> \
    --target=distroless|pm2|slim

从本地源文件构建

若需直接从本地源码构建，可将现有Dockerfile复制到仓库根目录，并修改为复制本地源码：

Dockerfile
COPY . /opt/iotajson/

完整说明可参见Dockerfile本身。

使用PM2/Distroless

Docker镜像中的IoT代理可通过pm2进程管理器运行，使用关联的pm2镜像：

console
docker run --name iotagent -d fiware/iotagent-json:<tag>-pm2

也可在distroless容器中运行，使用关联的distroless镜像：

console
docker run --name iotagent -d fiware/iotagent-json:<tag>-distroless

Docker Secrets

作为通过环境变量传递敏感信息的替代方案，可在部分敏感环境变量后附加_FILE，使初始化脚本从容器内的文件加载这些变量的值。特别是，这可用于从存储在/run/secrets/<secret_name>文件中的Docker Secrets加载密码。例如：

console
docker run --name iotagent -e IOTA_AUTH_PASSWORD_FILE=/run/secrets/password -d fiware/iotagent-json

目前，支持_FILE后缀的变量包括：

• IOTA_AUTH_USER
• IOTA_AUTH_PASSWORD
• IOTA_AUTH_CLIENT_ID
• IOTA_AUTH_CLIENT_SECRET
• IOTA_MONGO_USER
• IOTA_MONGO_PASSWORD
• IOTA_MQTT_KEY
• IOTA_MQTT_USERNAME
• IOTA_MQTT_PASSWORD
• IOTA_AMQP_USERNAME
• IOTA_AMQP_PASSWORD

最佳实践

调整Docker生产环境中的ULIMIT

Linux系统的默认ulimit设置假设多个用户共享系统，这些设置限制了每个用户的资源使用。默认设置对于高性能服务器通常过低，应进行调整。在高性能场景下，建议对IoT Agent - JSON服务器调整以下ulimit设置：

console
ulimit -n 65535        # nofile: 最大打开文件描述符数（多数系统不允许设置此值）
ulimit -c unlimited    # core: 创建的核心文件的最大大小
ulimit -l unlimited    # memlock: 可锁定到内存中的最大大小

若仅进行轻量测试和开发，可忽略这些设置，系统仍能正常工作。

要在容器中设置ulimit，需使用以下额外的--ulimit标志运行IoT Agent - JSON Docker容器：

console
docker run --ulimit nofile=65535:65535 --ulimit core=***:*** --ulimit memlock=***:*** \
--name iotagent -d fiware/iotagent-json

由于“unlimited”不被支持，此处将core和memlock值设置为100 GB。若系统RAM超过100 GB，应增加此值以匹配可用RAM。

注意：--ulimit标志仅在Docker 1.6及以上版本支持。

有关高性能场景下系统和Node.js配置的更多详细信息，请参阅安装指南。

设置适当的数据库索引

若使用MongoDB作为数据持久化机制（即IOTA_REGISTRY_TYPE=mongodb），设备和服务组详情将从数据库检索。IoT代理数据库的默认名称为iotagentjson。可通过创建适当的索引优化数据库访问。

例如：

console
docker exec  <mongo-db-container-name> mongo --eval '
	conn = new Mongo();
	db = conn.getDB("iotagentjson");
	db.createCollection("devices");
	db.devices.createIndex({"_id.service": 1, "_id.id": 1, "_id.type": 1});
	db.devices.createIndex({"_id.type": 1});
	db.devices.createIndex({"_id.id": 1});
	db.createCollection("groups");
	db.groups.createIndex({"_id.resource": 1, "_id.apikey": 1, "_id.service": 1});
	db.groups.createIndex({"_id.type": 1});' > /dev/null

数据库名称可通过IOTA_MONGO_DB环境变量修改。若使用其他数据库，请修改上述conn.getDB()语句。