telefonicaiot/lightweightm2m-iotagent

FIWARE OMA LightWeight Machine2Machine IoT Agent

镜像概述和主要用途

该物联网代理（IoT Agent）旨在作为OMA Lightweight M2M协议与上下文broker的https://swagger.lab.fiware.org/?url=https://raw.githubusercontent.com/Fiware/specifications/master/OpenAPI/ngsiv2/ngsiv2-openapi.json%E6%8E%A5%E5%8F%A3%E4%B9%8B%E9%97%B4%E7%9A%84%E6%A1%A5%E6%A2%81%E3%80%82%E5%AE%83%E5%9F%BA%E4%BA%8Ehttps://github.com/telefonicaid/iotagent-node-lib%E6%9E%84%E5%BB%BA%EF%BC%8C%E6%98%AFFIWARE%E9%A1%B9%E7%9B%AE%E7%9A%84%E4%B8%80%E9%83%A8%E5%88%86%E3%80%82%E6%9C%89%E5%85%B3FIWARE IoT Agents框架的更多通用信息、架构及常见交互模型，可参考该库的GitHub仓库。

核心功能和特性

• 协议桥接：实现OMA LWM2M协议与NGSI接口的双向数据转换与通信
• 标准化集成：与FIWARE生态系统中的Orion Context Broker无缝集成
• 灵活存储：支持内存或MongoDB数据库存储设备和服务信息
• 可配置性：通过环境变量灵活配置连接参数、端口及存储选项
• 扩展性：基于Node.js构建，支持高并发场景下的设备接入

使用场景和适用范围

适用于需要通过LWM2M协议接入物联网设备，并将设备数据同步到上下文broker的场景，例如：

• 工业物联网中低功耗设备的数据采集与管理
• 智能家居设备的标准化接入与控制
• 城市物联网传感器网络的数据汇聚
• 任何采用LWM2M协议的物联网设备与FIWARE平台的集成

使用方法和配置说明

如何使用此镜像

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

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

yaml
version: "3.1"

volumes:
    mongodb: ~

services:
    iot-agent:
        image: fiware/lightweightm2m-iotagent
        hostname: iot-agent
        container_name: fiware-iot-agent
        depends_on:
            - mongodb
        expose:
            - "4041"
            - "5683"
        ports:
            - "4041:4041"
            - "5683:5683"
        environment:
            - "IOTA_CB_HOST=orion"           # 上下文broker主机名
            - "IOTA_CB_PORT=1026"            # 上下文broker端口
            - "IOTA_NORTH_PORT=4041"         # 配置IoT Agent和接收上下文更新的端口
            - "IOTA_REGISTRY_TYPE=mongodb"   # 设备信息存储类型（内存或数据库）
            - "IOTA_MONGO_HOST=mongodb"      # MongoDB主机名
            - "IOTA_MONGO_PORT=27017"        # MongoDB端口
            - "IOTA_MONGO_DB=iotagent-lwm2m" # MongoDB数据库名
            - "LWM2M_PORT=5683"              # IoT Agent监听设备流量的端口

    mongodb:
        image: mongo:3.6
        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 Agent容器由以下环境变量驱动：

• 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中使用的数据库名
• LWM2M_PORT - IoT Agent监听IoT设备流量的端口

更多信息

所有IoT Agent通用参数的完整覆盖项在IoT Agent Library的安装指南的配置部分描述。

LightWeight Machine2Machine IoT Agent的特定设置（如LWM2M端口和协议的具体配置）可在其安装指南中找到。

构建镜像方法

与此镜像关联的https://github.com/telefonicaid/lwm2m-node-lib/blob/master/docker/Dockerfile%E5%8F%AF%E9%80%9A%E8%BF%87%E5%A4%9A%E7%A7%8D%E6%96%B9%E5%BC%8F%E6%9E%84%E5%BB%BA%E9%95%9C%E5%83%8F%EF%BC%9A

默认构建

默认情况下，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/iota-lwm2m/

完整说明可在Dockerfile中找到。

使用PM2/Distroless

Docker镜像中的IoT Agent可通过关联的pm2镜像在pm2进程管理器中运行：

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

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

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

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

• IOTA_AUTH_USER
• IOTA_AUTH_PASSWORD
• IOTA_AUTH_CLIENT_ID
• IOTA_AUTH_CLIENT_SECRET
• IOTA_MONGO_USER
• IOTA_MONGO_PASSWORD

最佳实践

调整Docker生产环境中的ULIMIT

Linux系统上的默认ulimit设置假设多个用户共享系统，限制了每个用户使用的资源数量。这些默认设置对于高性能服务器通常过低，应进行调整。在高性能场景下，我们建议对Lightweight OMA M2M IoTAgent服务器进行以下ulimit更改：

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

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

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

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

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

注意：--ulimit标志仅在Docker 1.6或更高版本中有效。

此外，需要“请求”更多资源（如多个核心），这可能使编排工具（Docker Engine或Kubernetes）比调度多个请求一个核心（或更少）的容器更难安排（后者可调度到多个节点，不必寻找有足够可用核心的单个节点）。

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

设置适当的数据库索引

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

例如：

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