fiware/iotagent-ul

FIWARE Ultralight 2.0协议IoT Agent

Ultralight 2.0协议的物联网代理（支持AMQP、https://www.w3.org/Protocols/和https://mqtt.org/传输）。此IoT Agent设计为Ultralight与上下文broker的https://swagger.lab.fiware.org/?url=https://raw.githubusercontent.com/Fiware/specifications/master/OpenAPI/ngsiv2/ngsiv2-openapi.json接口之间的桥梁。

它基于https://github.com/telefonicaid/iotagent-node-lib构建。有关FIWARE IoT Agents框架的更多一般信息、其架构和常见交互模型，可在该库的GitHub仓库中找到。

该项目是https://www.fiware.org/的一部分。更多信息请查看FIWARE目录中的https://github.com/Fiware/catalogue/tree/master/iot-agents条目。

如何使用此镜像

IoT Agent必须实例化并连接到https://fiware-orion.readthedocs.io/en/latest/实例，下面提供一个`docker-compose`示例文件。

如果IOTA_REGISTRY_TYPE=mongodb，则还需要https://www.mongodb.com/数据库实例——下面的示例假设主机系统中有`/data`目录用于存放数据库文件，请根据自己的配置修改挂载卷。

yml
version: "3.1"

volumes:
    mongodb: ~

services:
    iot-agent:
        image: docker.xuanyuan.run/fiware/iotagent-ul
        hostname: iot-agent
        container_name: fiware-iot-agent
        depends_on:
            - mongodb
        expose:
            - "4061"
            - "7896"
        ports:
            - "4061:4061"
            - "7896:7896"
        environment:
            - "IOTA_CB_HOST=orion"  # 上下文broker的主机名
            - "IOTA_CB_PORT=1026"    # 上下文broker监听的端口
            - "IOTA_NORTH_PORT=4061" # 用于配置IoT Agent和接收上下文broker更新的端口
            - "IOTA_REGISTRY_TYPE=mongodb"  # IoT设备信息存储类型（内存或数据库）
            - "IOTA_MONGO_HOST=mongodb"     # MongoDB主机名
            - "IOTA_MONGO_PORT=27017"       # MongoDB监听端口
            - "IOTA_MONGO_DB=iotagent-ul"   # MongoDB中使用的数据库名
            - "IOTA_HTTP_PORT=7896"         # IoT Agent监听HTTP设备流量的端口
            - "IOTA_PROVIDER_URL=http://iot-agent:4061"  # 注册命令时传递给上下文broker的URL

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

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

使用环境变量配置

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

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

更多信息

所有IoT Agent通用参数的完整覆盖项在IoT Agent Library的https://iotagent-node-lib.readthedocs.io/en/latest/installationguide/index.html#configuration的配置部分描述。

Ultralight IoT Agent特有的更多设置（如MQTT、AMQP和HTTP的特定配置）可在Ultralight IoT Agent的https://fiware-iotagent-ul.readthedocs.io/en/latest/installationguide/index.html#configuration中找到。

如何构建镜像

与此镜像关联的https://github.com/telefonicaid/iotagent-ul/blob/master/docker/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/iotaul/

完整说明可在Dockerfile本身中找到。

使用PM2 / Distroless

Docker镜像中的IoT Agent可通过关联的pm2镜像在http://pm2.keymetrics.io/进程管理器中运行：

console
docker run --name iotagent -d docker.xuanyuan.run/fiware/iotagent-ul:<tag>-pm2

也可通过关联的distroless镜像在无发行版容器中运行：

console
docker run --name iotagent -d docker.xuanyuan.run/fiware/iotagent-ul:<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 docker.xuanyuan.run/fiware/iotagent-ul

目前支持_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设置假设多个用户共享系统，这些设置限制每个用户使用的资源数量。默认设置对于高性能服务器通常很低，应进行增加。在高性能场景下，我们建议对IoTAgent-UL服务器的ulimit进行如下调整：

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

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

要在容器中设置ulimit，需使用以下附加--ulimit标志运行IoTAgent-UL Docker容器：

console
docker run --ulimit nofile=65535:65535 --ulimit core=100000000:100000000 --ulimit memlock=100000000:100000000 \
--name iotagent -d docker.xuanyuan.run/fiware/iotagent-ul

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

注意：--ulimit标志仅在Docker 1.6及更高版本支持。然而，请求更多资源（如多个核心）可能使编排工具（https://docs.docker.com/engine或https://kubernetes.io）更难调度，相比多个请求1个核心（或更少）的容器（可调度到多个节点，不必寻找有足够可用核心的单个节点）。

如需了解更多高性能场景下系统和node.js配置的详细信息，请参考安装指南。

设置适当的数据库索引

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

例如：

console
docker exec  <mongo-db-container-name> mongo --eval '
	conn = new Mongo();
	db = conn.getDB("iotagentul");
	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()语句。