fiware/sth-comet

FIWARE Short Time Historic (STH) - Comet

镜像概述和主要用途

FIWARE Short Time Historic (STH) - Comet 是FIWARE核心上下文管理组件之一，主要用于管理（存储和检索）历史原始和聚合时间序列上下文信息。这些信息记录了Orion Context Broker实例中注册的上下文数据（即实体属性值）随时间的演变过程。

STH与Orion Context Broker之间以及STH与第三方（通常用于数据检索）之间的所有通信均采用标准化的NGSI v1接口。本项目是FIWARE的一部分，更多信息可参考FIWARE目录中的https://github.com/Fiware/catalogue/tree/master/core%E6%9D%A1%E7%9B%AE%E3%80%82

核心功能和特性

主要功能

1. 历史数据存储：接收Orion Context Broker发送的属性变化通知，处理并存储相关的原始和聚合时间序列上下文信息到MongoDB数据库
2. 原始数据检索：查询和获取实体属性随时间变化的具体值及时间戳
3. 聚合数据检索：查询和获取按时间分组的聚合时间序列信息，支持均值、标准差、最大值、最小值及出现次数等统计量
4. 数据删除：支持删除指定实体和属性的原始及聚合时间序列信息

技术特性

• 基于NGSI v1标准接口，确保与FIWARE生态系统的兼容性
• 支持灵活的时间粒度聚合（如秒、分钟、小时、天等）
• 依赖MongoDB进行数据持久化，支持高可用性配置
• 提供REST API接口，方便第三方系统集成

使用场景和适用范围

STH - Comet适用于需要跟踪和分析上下文数据随时间变化的场景，典型应用包括：

• 物联网设备监控数据的历史记录与趋势分析
• 智慧城市中环境参数（如温度、湿度、交通流量）的时间序列分析
• 工业系统中设备状态变化的历史追踪与性能评估
• 需要基于历史数据进行决策支持的应用系统

使用方法和配置说明

前提条件

• 运行中的MongoDB实例（用于数据存储）
• 运行中的Orion Context Broker实例（用于上下文数据来源）

Docker部署示例

基本运行命令

bash
docker run -d \
  --name sth-comet \
  -p 8666:8666 \
  -e STH_MONGO_HOST=mongodb \
  -e STH_MONGO_PORT=27017 \
  -e STH_ORION_HOST=orion \
  -e STH_ORION_PORT=1026 \
  fiware/sth-comet

Docker Compose配置示例

yaml
version: '3'
services:
  mongodb:
    image: mongo:4.4
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db

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

  sth-comet:
    image: fiware/sth-comet
    ports:
      - "8666:8666"
    environment:
      - STH_MONGO_HOST=mongodb
      - STH_MONGO_PORT=27017
      - STH_ORION_HOST=orion
      - STH_ORION_PORT=1026
      - STH_LOG_LEVEL=info
      - STH_AGGREGATION_PERIOD=day,hour,minute
    depends_on:
      - mongodb
      - orion

volumes:
  mongodb_data:

主要配置参数（环境变量）

API概述

STH组件提供REST API，主要涵盖以下功能：

1. 数据存储API

接收Orion Context Broker发送的属性变化通知，存储原始和聚合数据。
端点：/notify
方法：POST
内容类型：application/json

2. 原始数据检索API

查询实体属性的历史原始数据。
端点：/STH/v1/contextEntities/type/{entityType}/id/{entityId}/attributes/{attributeName}
方法：GET
查询参数：dateFrom、dateTo、limit、offset等

3. 聚合数据检索API

查询实体属性的历史聚合数据。
端点：/STH/v1/contextEntities/type/{entityType}/id/{entityId}/attributes/{attributeName}/aggregated
方法：GET
查询参数：dateFrom、dateTo、aggrMethod（如sum、avg、min、max）、period（如day、hour）等

4. 数据删除API

删除指定实体和属性的历史数据。
端点：/STH/v1/contextEntities/type/{entityType}/id/{entityId}/attributes/{attributeName}
方法：DELETE

测试

单元测试

STH组件包含完整的单元测试套件，覆盖核心功能模块。测试代码位于项目的test/unit目录，可通过以下命令运行：

bash
npm test

性能测试

提供性能测试脚本，用于评估在高负载情况下的系统表现。测试代码位于test/performance目录，可通过以下命令运行：

bash
npm run test:performance

高级主题

推荐数据库索引

为提高查询性能，建议在MongoDB中创建以下索引：

javascript
// 原始数据集合索引
db.sth_original.createIndex({ "entityId": 1, "entityType": 1, "attrName": 1, "recvTime": 1 })

// 聚合数据集合索引
db.sth_aggregated.createIndex({ "entityId": 1, "entityType": 1, "attrName": 1, "aggrPeriod": 1, "aggrTimestamp": 1 })

扩展资源

• 官方文档
• FIWARE Academy教程
• https://github.com/telefonicaid/fiware-sth-comet

支持与社区

• Stack Overflow：使用标签fiware-sth-comet提问
• FIWARE Q&A：在ask.fiware.org提问，标签sth-comet
• Gitter社区：[***]

许可证

STH - Comet采用Affero General Public License (GPL) version 3许可证。详细信息参见https://github.com/telefonicaid/fiware-sth-comet/blob/master/LICENSE%E3%80%82

关于AGPL 3.0的***说明：使用AGPL 3.0许可的软件不存在使用风险。仅当修改源代码时，衍生作品需遵循相同许可；仅使用或链接未修改的软件不属于衍生作品，无需以相同许可发布。