telefonicaiot/fiware-sth-comet

FIWARE Short Time Historic (STH) - Comet

概述

FIWARE Short Time Historic (STH) - Comet 是 FIWARE 生态系统的核心组件，负责管理（存储和检索）来自 https://github.com/telefonicaid/fiware-orion 实例的历史上下文信息，包括原始数据和聚合时间序列数据。该组件通过标准化的 NGSI v1 接口与 Orion Context Broker 及第三方系统通信，支持上下文数据（即实体属性值）随时间变化的追踪与分析。

本项目属于 https://www.fiware.org/ 核心上下文管理章节，更多信息可参考 https://github.com/Fiware/catalogue/tree/master/core%E3%80%82

核心功能与特性

核心功能

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

关键特性

• 遵循 NGSI v1 标准接口，确保与 FIWARE 生态系统组件的兼容性。
• 支持原始数据与多粒度聚合数据（如按分钟、小时、天等）的存储与查询。
• 基于 MongoDB 实现高效数据存储与检索。
• 提供 REST API 覆盖数据全生命周期管理（存储、检索、删除）。

使用场景与适用范围

适用于需要追踪和分析上下文数据随时间变化的 IoT 场景，例如：

• 智能城市中传感器数据（如温度、湿度、交通流量）的历史趋势分析。
• 工业监控系统中设备状态的长期性能评估。
• 环境监测中环境参数的变化模式识别。

需与 Orion Context Broker 配合使用，作为上下文数据的历史存储与分析模块。

使用方法

前提条件

• 已部署 https://github.com/telefonicaid/fiware-orion 实例，用于提供上下文数据变更通知。
• 已部署 MongoDB 实例，用于存储历史数据（推荐 MongoDB 3.6+）。

镜像获取

可从 Docker Hub 或 Quay.io 获取镜像：

bash
# Docker Hub
docker pull docker.xuanyuan.run/telefonicaid/fiware-sth-comet

# Quay.io
docker pull ***-quay.xuanyuan.run/fiware/sth-comet

启动容器

基本启动命令

bash
docker run -d --name sth-comet \
  -p 8666:8666 \  # STH 服务端口
  -e STH_MONGO_URI=mongodb://<mongodb-host>:27017 \  # MongoDB 连接地址
  -e STH_ORION_URL=http://<orion-host>:1026 \  # Orion Context Broker 地址
  -e STH_SERVICE=default \  # FIWARE 服务名（与 Orion 对应）
  -e STH_SERVICEPATH=/ \  # FIWARE 服务路径（与 Orion 对应）
  telefonicaid/fiware-sth-comet

Docker Compose 示例

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

  orion:
    image: docker.xuanyuan.run/fiware/orion
    ports:
      - "1026:1026"
    depends_on:
      - mongodb
    environment:
      - ORION_MONGO_URI=mongodb://mongodb:27017/orion

  sth-comet:
    image: docker.xuanyuan.run/telefonicaid/fiware-sth-comet
    ports:
      - "8666:8666"
    depends_on:
      - mongodb
      - orion
    environment:
      - STH_MONGO_URI=mongodb://mongodb:27017
      - STH_ORION_URL=http://orion:1026
      - STH_SERVICE=default
      - STH_SERVICEPATH=/
      - STH_LOG_LEVEL=info  # 日志级别：debug/info/warn/error

volumes:
  mongodb_data:

配置参数

常用环境变量配置：

API 概览

STH 提供以下核心 API 端点：

1. 数据存储

接收 Orion 发送的上下文变更通知，存储原始及聚合数据：

• 端点：POST /STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attributeName>
• 说明：由 Orion 通过订阅机制自动调用，无需手动触发。

2. 原始数据检索

查询实体属性的历史原始值：

• 端点：GET /STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attributeName>?lastN=<num>
• 示例：获取设备 "Device1" 的 "temperature" 属性最近 10 条原始数据：

  bash
  curl "http://sth-comet:8666/STH/v1/contextEntities/type/Device/id/Device1/attributes/temperature?lastN=10"
  

3. 聚合数据检索

查询实体属性的聚合统计数据：

• 端点：GET /STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attributeName>?aggrMethod=<method>&dateFrom=<date>&dateTo=<date>&period=<period>
• 示例：获取设备 "Device1" 的 "temperature" 属性在 2023-01-01 至 2023-01-31 期间按天的平均值：

  bash
  curl "http://sth-comet:8666/STH/v1/contextEntities/type/Device/id/Device1/attributes/temperature?aggrMethod=avg&dateFrom=2023-01-01T00:00:00Z&dateTo=2023-01-31T23:59:59Z&period=day"
  

4. 数据删除

删除实体或属性的历史数据：

• 端点：DELETE /STH/v1/contextEntities/type/<entityType>/id/<entityId>/attributes/<attributeName>
• 示例：删除设备 "Device1" 的 "temperature" 属性所有历史数据：

  bash
  curl -X DELETE "http://sth-comet:8666/STH/v1/contextEntities/type/Device/id/Device1/attributes/temperature"
  

高级主题

数据库索引优化

为提升查询性能，建议为 MongoDB 集合创建以下索引（详细可参考 https://fiware-sth-comet.readthedocs.io/en/latest/manuals/db_indexes.html%EF%BC%89%EF%BC%9A

javascript
// 原始数据集合索引
db.sth_<service>_<servicepath>_raw.createIndex({ "entityId": 1, "entityType": 1, "attrName": 1, "recvTime": -1 })

// 聚合数据集合索引
db.sth_<service>_<servicepath>_aggr_<period>.createIndex({ "entityId": 1, "entityType": 1, "attrName": 1, "timeInstant": -1 })

日志与监控

• 日志输出至标准输出，可通过 STH_LOG_LEVEL 调整详细程度。
• 支持通过 Prometheus 等工具监控服务状态（需额外配置，参考 https://fiware-sth-comet.readthedocs.io/en/latest/manuals/additional-resources.html%EF%BC%89%E3%80%82

支持与许可

支持渠道

• Stack Overflow：使用标签 fiware-sth-comet 提问。
• FIWARE Q&A：访问 https://ask.fiware.org 并添加标签 sth-comet。
• Gitter 社区：https://gitter.im/telefonicaid/fiware-sth-comet

许可

STH-Comet 基于 GNU Affero General Public License (AGPL) v3.0 许可发布。详细许可条款见 https://github.com/telefonicaid/fiware-sth-comet/blob/master/LICENSE%E3%80%82

许可说明：仅修改源代码的衍生作品需遵循 AGPL v3.0 许可；仅使用（未修改）本组件的软件无需开源，也无需采用相同许可。