Cygnus-NGSI Docker镜像文档

镜像概述和主要用途

Cygnus-NGSI是FIWARE生态系统的核心组件，作为上下文数据持久化连接器，基于Apache Flume（流编程概念的数据流系统）开发。其核心功能是接收上下文数据源（如Orion Context Broker）的数据，通过流处理将数据路由并持久化到第三方数据库和存储系统，从而创建上下文的历史视图。Flume提供的强大可扩展数据流路由、转换能力，使Cygnus-NGSI能自动化系统间的信息流转与持久化。

核心功能和特性

• 基于Apache Flume：利用Flume的流处理架构，支持数据路由、转换和系统中介逻辑的可扩展有向图。
• 模块化代理结构：每个数据持久化代理包含三部分：
  • Source（源）：接收上下文数据并转换为Flume事件。
  • Channel（通道）：存储源生成的Flume事件。
  • Sink（ sink）：从通道获取事件，将数据体持久化到第三方存储。
• 多存储支持：可配置连接PostgreSQL、MongoDB、HDFS等多种第三方数据库和存储系统。
• 灵活配置方式：支持通过Docker环境变量或注入agent.conf文件进行参数配置。
• 敏感信息安全管理：支持Docker Secrets，通过_FILE后缀环境变量从文件加载敏感信息（如密码、密钥）。

使用场景和适用范围

适用于需要持久化上下文数据以保留历史记录的场景，主要包括：

• FIWARE生态中与Orion Context Broker配合，存储实时上下文数据的历史版本。
• 物联网（IoT）平台，将设备状态、传感器数据等上下文信息持久化到数据库。
• 智慧城市、工业监控等领域，需长期存储和分析上下文数据变化的应用。

使用方法和配置说明

前提条件

• 需与Orion Context Broker实例配合使用，Orion作为上下文 broker 提供实时数据。
• 根据目标存储类型（如PostgreSQL、MongoDB），配置并暴露相应的sink端口。

Docker Compose部署示例

以下示例展示Cygnus与Orion、PostgreSQL的配合使用，Cygnus将上下文数据持久化到PostgreSQL：

yaml
version: "3.5"
services:

  # Orion作为上下文 broker
  orion:
    image: fiware/orion
    hostname: orion
    container_name: fiware-orion
    depends_on:
      - mongo-db
    ports:
      - "1026:1026"
    command: -dbhost mongo-db -logLevel DEBUG -noCache

  # Cygnus配置为将上下文数据写入PostgreSQL
  cygnus:
    image: fiware/cygnus-ngsi
    hostname: cygnus
    container_name: fiware-cygnus
    networks:
      - default
    depends_on:
      - postgres-db
    ports:
      - "5055:5055"  # PostgreSQL sink服务端口
      - "5080:5080"  # Cygnus运维API端口
    environment:
      - "CYGNUS_POSTGRESQL_HOST=postgres-db"  # PostgreSQL服务器主机名
      - "CYGNUS_POSTGRESQL_PORT=5432"  # PostgreSQL监听端口
      - "CYGNUS_POSTGRESQL_USER=postgres"  # PostgreSQL用户名
      - "CYGNUS_POSTGRESQL_PASS=password"  # PostgreSQL密码
      - "CYGNUS_POSTGRESQL_ENABLE_CACHE=true"  # 启用PostgreSQL缓存
      - "CYGNUS_POSTGRESQL_SERVICE_PORT=5055"  # agent.conf配置的服务端口
      - "CYGNUS_LOG_LEVEL=DEBUG"  # 日志级别
      - "CYGNUS_SERVICE_PORT=5055"  # 订阅通知监听端口
      - "CYGNUS_API_PORT=5080"  # 运维API端口

  # 数据库服务
  mongo-db:  # Orion使用的MongoDB
    image: mongo:3.6
    hostname: mongo-db
    container_name: db-mongo
    ports:
      - "27017:27017"
    command: --bind_ip_all --smallfiles
    volumes:
      - mongo-db:/data
      
  postgres-db:  # Cygnus持久化目标PostgreSQL
    image: postgres
    hostname: postgres-db
    container_name: db-postgres
    ports:
      - "5432:5432"
    environment:
      - "POSTGRES_PASSWORD=password"
      - "POSTGRES_USER=postgres"
      - "POSTGRES_DB=postgres"
    volumes:
      - postgres-db:/var/lib/postgresql/data

volumes:
  mongo-db: ~
  postgres-db: ~

配置说明

环境变量配置

通过环境变量可配置存储连接、端口、日志等核心参数，以PostgreSQL为例，常用变量包括：

• CYGNUS_POSTGRESQL_HOST：目标PostgreSQL服务器主机名
• CYGNUS_POSTGRESQL_PORT：服务器监听端口（默认5432）
• CYGNUS_POSTGRESQL_USER/CYGNUS_POSTGRESQL_PASS：数据库用户及密码
• CYGNUS_LOG_LEVEL：日志级别（如DEBUG、INFO）
• CYGNUS_SERVICE_PORT：订阅通知监听端口
• CYGNUS_API_PORT：运维API端口

更复杂配置可通过挂载agent.conf文件实现，详情参考***文档。

Docker Secrets支持

为安全管理敏感信息，可通过_FILE后缀环境变量从容器内文件加载值（如Docker Secrets）。支持的变量包括：

• CYGNUS_MYSQL_USER_FILE/CYGNUS_MYSQL_PASS_FILE
• CYGNUS_MONGO_USER_FILE/CYGNUS_MONGO_PASS_FILE
• CYGNUS_HDFS_USER_FILE/CYGNUS_HDFS_TOKEN_FILE
• CYGNUS_POSTGRESQL_USER_FILE/CYGNUS_POSTGRESQL_PASS_FILE
• CYGNUS_POSTGIS_USER_FILE/CYGNUS_POSTGIS_PASS_FILE
• CYGNUS_CARTO_USER_FILE/CYGNUS_CARTO_KEY_FILE

示例：

bash
docker run --name some-cygnus -e CYGNUS_POSTGRESQL_PASS_FILE=/run/secrets/postgres-pass -d fiware/cygnus-ngsi:tag