davradocker/ruban-ms-iotdata-persist-service

Kafka到时序数据库数据写入工具镜像

镜像概述与主要用途

本Docker镜像为一款轻量级数据集成工具，专注于实现Kafka消息队列与时序数据库（Time Series Database, TSDB）之间的数据流转。通过配置化方式，将Kafka主题中的消息数据提取、转换后，高效写入目标时序数据库，解决实时数据流从消息中间件到时序存储系统的无缝对接问题，适用于需要长期存储、分析时序数据的场景。

核心功能与特性

• 多时序数据库支持：兼容主流时序数据库，包括InfluxDB、Prometheus、TimescaleDB、OpenTSDB等，满足不同存储需求。
• 灵活配置：通过环境变量或配置文件定义数据映射规则，支持自定义数据转换（如字段重命名、类型转换、过滤条件）。
• 高可靠性：内置断点续传机制，支持数据消费偏移量持久化，避免数据丢失；支持分布式部署，提升服务可用性。
• 性能优化：支持批量写入、异步处理，降低数据库写入压力；可配置并发度，适配不同数据吞吐量场景。
• 监控与可观测性：暴露Prometheus监控指标（如数据写入量、成功率、延迟），便于运维监控。

使用场景与适用范围

• 物联网（IoT）数据存储：传感器、设备采集的时序数据（如温度、湿度、电压）经Kafka接入后，通过本镜像写入时序数据库，用于长期趋势分析与异常检测。
• 监控数据持久化：应用/系统监控指标（如CPU使用率、响应时间）从Kafka流转至时序数据库，替代短期内存存储，支持历史数据查询与报表生成。
• 日志数据归档：应用日志、访问日志等结构化时序数据经Kafka汇总后，通过本镜像写入时序数据库，用于用户行为分析、系统审计。
• ***时序数据处理：***行情、交易数据等高频时序数据经Kafka实时传输，通过本镜像写入时序数据库，支持量化分析与回测。

使用方法与配置说明

基本使用（Docker Run）

bash
docker run -d \
  --name kafka-to-tsdb \
  -e KAFKA_BOOTSTRAP_SERVERS="kafka-broker:9092" \
  -e KAFKA_TOPICS="sensor-data,metrics" \
  -e TSDB_TYPE="influxdb" \
  -e TSDB_URL="http://influxdb:8086" \
  -e TSDB_DATABASE="iot_data" \
  -e TSDB_USER="admin" \
  -e TSDB_PASSWORD="password" \
  -v ./data-mapping.json:/app/config/mapping.json \
  your-registry/kafka-to-tsdb:latest

Docker Compose示例

yaml
version: '3'
services:
  kafka-to-tsdb:
    image: your-registry/kafka-to-tsdb:latest
    container_name: kafka-to-tsdb
    environment:
      - KAFKA_BOOTSTRAP_SERVERS=kafka:9092
      - KAFKA_TOPICS=iot-sensors,system-metrics
      - KAFKA_CONSUMER_GROUP=tsdb-writer
      - TSDB_TYPE=timescaledb
      - TSDB_URL=jdbc:postgresql://timescaledb:5432/metrics_db
      - TSDB_USER=tsdb_user
      - TSDB_PASSWORD=tsdb_pass
      - BATCH_SIZE=1000
      - FLUSH_INTERVAL=5000
    volumes:
      - ./mapping:/app/config
    depends_on:
      - kafka
      - timescaledb

  kafka:
    image: confluentinc/cp-kafka:latest
    # Kafka配置省略...

  timescaledb:
    image: timescale/timescaledb:latest-pg14
    # TimescaleDB配置省略...

环境变量配置

数据映射配置

通过挂载JSON配置文件（如/app/config/mapping.json）定义Kafka消息到时序数据库的字段映射规则，示例如下（以InfluxDB为例）：

json
{
  "sensor-data": {  // Kafka主题名
    "measurement": "sensor_measure",  // InfluxDB measurement名称
    "tags": ["sensor_id", "location"],  // 作为InfluxDB tag的字段（从Kafka消息中提取）
    "fields": {  // 作为InfluxDB field的字段（支持类型转换）
      "temperature": {"type": "float"},
      "humidity": {"type": "float"},
      "status": {"type": "string"}
    },
    "timestamp": {  // 时间戳字段配置
      "field": "ts",  // 从消息中提取的时间戳字段名
      "format": "unix_ms"  // 时间戳格式：unix_ms/unix/iso8601
    },
    "filter": "status != 'error'"  // 数据过滤条件（可选）
  }
}

注意事项

• 确保Kafka与目标时序数据库网络互通，防火墙规则允许对应端口访问。
• 数据映射规则需与Kafka消息格式（如JSON、Avro）匹配，避免字段解析错误。
• 高吞吐量场景下，建议调整BATCH_SIZE与FLUSH_INTERVAL，并配置数据库连接池参数（通过环境变量DB_MAX_CONNECTIONS等）。
• 首次部署时建议开启调试日志（设置环境变量LOG_LEVEL=debug），验证数据写入正确性。