telefonicaiot/sigfox-iotagent

FIWARE SigFox IoT Agent

镜像概述和主要用途

FIWARE SigFox IoT Agent 旨在作为 Sigfox 回调协议与 OMA NGSI 协议之间的桥梁，后者被 https://github.com/telefonicaid/fiware-orion 及其他 FIWARE 生态系统组件使用。该镜像基于 https://github.com/telefonicaid/iotagent-node-lib 构建，是 FIWARE 项目的一部分，用于实现 Sigfox 设备与 FIWARE 平台的无缝集成。

核心功能和特性

• 协议转换：在 Sigfox 回调协议与 OMA NGSI 协议间进行双向转换
• 设备管理：支持设备注册、配置及上下文信息维护
• 数据持久化：可使用 MongoDB 存储设备和服务组信息
• 灵活配置：通过环境变量自定义连接参数、端口及数据处理规则
• FIWARE 生态集成：与 Orion Context Broker 等 FIWARE 组件兼容

使用场景和适用范围

适用于需要将 Sigfox 低功耗广域网设备数据集成到 FIWARE 生态系统的场景，包括但不限于：

• 智能城市传感器网络
• 工业物联网监控系统
• 环境监测设备数据采集
• 资产追踪与管理系统

使用方法和配置说明

基本部署（Docker Compose）

IoT Agent 需与 Orion Context Broker 实例连接，若使用 IOTA_REGISTRY_TYPE=mongodb，还需 MongoDB 数据库。以下是完整的 docker-compose 配置示例：

yaml
version: "3.1"

volumes:
    mongodb: ~

services:
    iot-agent:
        image: fiware/sigfox-iotagent
        hostname: iot-agent
        container_name: fiware-iot-agent
        depends_on:
            - mongodb
        expose:
            - "4041"
            - "17428"
        ports:
            - "4041:4041"
            - "17428:17428"
        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=iotasigfox"
            - "IOTA_SIGFOX_PORT=17428"
            - "IOTA_SIGFOX_ID_FIELD_NAME=id"
            - "IOTA_PROVIDER_URL=http://iot-agent:4041"

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

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

环境变量配置

通过环境变量可配置以下核心参数：

完整配置参数可参考 IoT Agent 库安装指南，Sigfox 特定配置见 https://github.com/telefonicaid/sigfox-iotagent/tree/master/docs%E3%80%82

构建镜像

基本构建

使用项目 Dockerfile 可构建不同版本的镜像：

• 默认获取最新代码：

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

• 获取稳定版本：

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

• 获取特定版本（如 1.7.0）：

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

从自定义 Fork 构建

指定 GitHub 账户、仓库和分支：

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/iotasigfox/

特殊镜像版本

• PM2 版本：使用 PM2 进程管理器运行：

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

• Distroless 版本：使用精简容器运行：

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

Docker Secrets

敏感信息可通过 _FILE 后缀从文件加载，支持的变量包括：IOTA_AUTH_USER、IOTA_AUTH_PASSWORD、IOTA_AUTH_CLIENT_ID、IOTA_AUTH_CLIENT_SECRET、IOTA_MONGO_USER、IOTA_MONGO_PASSWORD。示例：

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

最佳实践

生产环境调整 ULIMIT

高负载场景下建议调整系统资源限制：

console
ulimit -n 65535        # 最大打开文件描述符数
ulimit -c unlimited    # 核心文件大小无限制
ulimit -l unlimited    # 内存锁定大小无限制

容器启动时应用限制：

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

MongoDB 索引优化

使用 MongoDB 时，建议为设备和服务组集合创建索引：

console
docker exec <mongo容器名> mongo --eval '
	conn = new Mongo();
	db = conn.getDB("iotasigfox");  # 数据库名需与 IOTA_MONGO_DB 一致
	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