Cygnus-ngsi Docker镜像文档

镜像概述和主要用途

Cygnus是FIWARE生态系统中的一个连接器，主要用于将Orion Context Broker的上下文数据源持久化到第三方数据库和存储系统，从而创建上下文数据的历史视图。该镜像基于Apache Flume构建，Flume是一个基于流编程概念的数据流系统，支持强大且可扩展的数据流路由、转换和系统中介逻辑，实现系统间数据的自动化流转。

每个Cygnus数据持久化代理由三部分组成：负责接收数据的监听器（source）、source将数据转换为Flume事件后放入的通道（channel），以及从channel获取Flume事件并将其主体数据持久化到第三方存储的接收器（sink）。

核心功能和特性

• 基于Apache Flume：利用Flume的流处理能力，支持数据路由、转换和系统中介的可扩展 directed graphs。
• 多组件架构：
  • Source：接收上下文数据并转换为Flume事件。
  • Channel：暂存Flume事件，实现source与sink间的解耦。
  • Sink：从channel获取事件，将数据持久化到第三方存储系统。
• 多存储支持：可将数据持久化到多种第三方存储（如PostgreSQL、MySQL、MongoDB、HDFS等）。
• 灵活配置：支持通过Docker环境变量或注入agent.conf文件进行配置，也可结合两者使用。

使用场景和适用范围

适用于需要将Orion Context Broker的实时上下文数据持久化到第三方存储系统，以构建历史数据视图的场景。典型应用包括：

• 物联网（IoT）环境中设备状态数据的长期存储与分析。
• 需要跟踪上下文数据变化历史的业务系统。
• 与FIWARE生态系统集成，实现上下文数据的持久化与后续处理。

使用方法和配置说明

基本使用示例（docker-compose）

Cygnus需与Orion Context Broker实例连接，并根据数据持久化类型配置和暴露相应的sink端口。以下是一个连接Orion和PostgreSQL的docker-compose示例：

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"  # Postgres订阅通知端口
      - "5080:5080"  # 运维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"  # Postgres订阅的通知端口
      - "CYGNUS_API_PORT=5080"  # 运维API监听端口

  # 数据库服务 - Orion使用MongoDB，Cygnus持久化到PostgreSQL
  mongo-db:
    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:
    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: ~

配置说明

环境变量配置

Cygnus可通过环境变量配置，常用参数包括（以PostgreSQL为例）：

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

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

示例：

docker run --name some-cygnus -e CYGNUS_MYSQL_PASS_FILE=/run/secrets/mysql-root -d fiware/cygnus-ngsi:tag