iotechsys/sparkplug-historian

Sparkplug Historian 镜像文档

概述

Sparkplug Historian 是一款专为工业物联网(IIoT)环境打造的时序数据存储组件，基于Eclipse Sparkplug协议标准开发。该镜像提供了从Sparkplug协议设备高效采集、持久化存储和查询历史数据的完整能力，适用于工业自动化、智能制造等场景下的设备数据管理需求。

核心功能与特性

• Sparkplug协议原生兼容：全面支持Sparkplug B规范，可直接接收来自Sparkplug网关、边缘节点的遥测数据与设备状态信息
• 多后端存储支持：适配主流时序数据库（InfluxDB、TimescaleDB、PostgreSQL），支持根据业务需求灵活选择存储引擎
• 高吞吐数据处理：优化的时序数据写入 pipeline，单实例支持每秒数千点设备数据的稳定写入
• 标准化数据接口：提供RESTful API与SQL查询能力，支持与监控平台、BI工具及数据分析系统无缝集成
• 智能数据生命周期管理：内置数据保留策略引擎，支持按时间/大小自动归档、压缩和清理过期数据
• 容器化灵活部署：轻量级微服务架构，支持单机Docker部署及Kubernetes集群化扩展

使用场景与适用范围

• 工业自动化系统：存储生产线传感器、PLC设备的实时运行数据，用于工艺优化与故障追溯
• 智能制造平台：收集制造执行系统(MES)关键指标，支撑生产过程可视化与质量分析
• 能源监控网络：记录电力、油气等能源设施的能耗数据，实现能源效率分析与优化
• 设备健康管理：持久化设备振动、温度等状态参数，为预测性维护提供历史数据支持
• IIoT数据中台：作为工业数据中台的核心存储组件，统一管理跨厂区、跨协议的设备历史数据

使用方法与配置说明

快速启动

通过以下命令启动基础功能容器：

bash
docker run -d \
  --name sparkplug-historian \
  -p 8080:8080 \
  -e SPARKPLUG_BROKER_URL=mqtt://mqtt-broker:1883 \
  -e DB_TYPE=influxdb \
  -e DB_CONNECTION_STRING=http://influxdb:8086?db=sparkplug_data&org=industrial&token=my-secret-token \
  -e DATA_RETENTION_DAYS=90 \
  docker.xuanyuan.run/eclipse/sparkplug-historian:latest

Docker Compose完整部署示例

yaml
version: '3.8'

services:
  sparkplug-historian:
    image: docker.xuanyuan.run/eclipse/sparkplug-historian:latest
    container_name: sparkplug-historian
    restart: always
    ports:
      - "8080:8080"
    environment:
      - SPARKPLUG_BROKER_URL=mqtt://mosquitto:1883
      - SPARKPLUG_USERNAME=sparkplug-user
      - SPARKPLUG_PASSWORD=secure-password
      - DB_TYPE=timescale
      - DB_CONNECTION_STRING=postgresql://tsdb-user:tsdb-pass@timescale:5432/sparkplug_tsdb
      - DATA_RETENTION_DAYS=180
      - LOG_LEVEL=INFO
      - API_AUTH_ENABLED=true
      - API_KEY=your-api-key-here
    depends_on:
      - mosquitto
      - timescale

  mosquitto:
    image: docker.xuanyuan.run/eclipse-mosquitto:2.0
    container_name: sparkplug-mqtt
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
    ports:
      - "1883:1883"

  timescale:
    image: docker.xuanyuan.run/timescale/timescaledb:latest-pg14
    container_name: sparkplug-tsdb
    environment:
      - POSTGRES_USER=tsdb-user
      - POSTGRES_PASSWORD=tsdb-pass
      - POSTGRES_DB=sparkplug_tsdb
    volumes:
      - timescale-data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  timescale-data:

核心配置参数

数据查询API示例

获取指定设备的温度历史数据：

bash
curl -X GET "http://localhost:8080/api/v1/history?deviceId=motor-pump-01&metric=temperature&start=2024-05-01T08:00:00Z&end=2024-05-01T18:00:00Z" \
  -H "Authorization: Bearer your-api-key-here"

注意事项

• 生产环境需配置API_AUTH_ENABLED=true并设置强密钥，防止未授权数据访问
• 高吞吐量场景建议独立部署数据库服务并配置性能优化参数
• 数据保留策略应根据合规要求与存储成本综合设置，关键数据建议配合外部归档系统
• MQTT Broker需启用持久化消息机制，避免Historian离线期间的数据丢失
• 容器部署时建议通过-v参数挂载配置文件目录，实现配置持久化与版本控制