datazip/ingestion

数据摄入框架Docker镜像文档

1. 镜像概述

本镜像为数据摄入框架的Docker化部署包，旨在提供一个轻量级、可移植的数据采集、转换和加载(ETL)解决方案。通过容器化部署，简化了数据从各类源系统到目标存储的全流程处理，降低了环境依赖和部署复杂度，适用于各类数据集成场景。

2. 核心功能与特性

2.1 多数据源支持

• 兼容主流数据源类型：关系型数据库（MySQL、PostgreSQL、Oracle等）、NoSQL数据库（MongoDB、Redis等）、文件系统（CSV、JSON、Parquet等）、API接口（REST、GraphQL）、消息队列（Kafka、RabbitMQ）等。

2.2 灵活的数据转换能力

• 内置常用数据转换算子：字段映射、格式转换（JSON/CSV/Parquet互转）、数据清洗（去重、空值处理、异常值过滤）、聚合计算等。
• 支持自定义转换规则配置，通过JSON/YAML文件定义转换逻辑。

2.3 多目标存储集成

• 支持数据加载至多种目标存储：数据仓库（***、Redshift）、关系型数据库、对象存储（S3、GCS）、数据湖（Delta Lake、Hudi）等。

2.4 任务调度与自动化

• 内置定时任务调度器，支持基于Cron表达式的周期性数据摄入。
• 支持任务依赖配置，实现复杂ETL流程的自动化执行。

2.5 监控与可观测性

• 集成日志输出功能，记录数据摄入过程中的关键节点和异常信息。
• 支持 metrics 暴露（如Prometheus格式），便于监控任务执行状态、数据吞吐量等指标。

3. 使用场景与适用范围

3.1 ETL流程自动化

适用于需要定期执行数据抽取、转换、加载的场景，替代传统手动或脚本化的ETL流程。

3.2 多源数据集成

当业务系统数据分散在不同数据源（如MySQL数据库、CSV文件、API接口）时，可通过本镜像实现统一的数据汇聚。

3.3 实时/批量数据处理

• 批量处理：支持大规模历史数据的全量或增量同步。
• 近实时处理：配合消息队列（如Kafka），可实现准实时数据摄入（延迟秒级/分钟级）。

3.4 数据迁移与同步

用于系统迁移时的数据全量迁移，或生产环境与测试/分析环境的数据定期同步。

4. 使用方法与配置说明

4.1 基本用法

4.1.1 拉取镜像

bash
docker pull [镜像仓库地址]/ingestion-framework:latest

4.1.2 启动容器（基础配置）

通过挂载配置文件和设置环境变量启动容器：

bash
docker run -d \
  --name ingestion-framework \
  -v /path/to/config:/app/config \  # 挂载配置文件目录
  -e SOURCE_TYPE="mysql" \          # 数据源类型
  -e SOURCE_CONN="jdbc:mysql://host:port/db" \  # 数据源连接串
  -e SOURCE_USER="user" \           # 数据源用户名
  -e SOURCE_PASSWORD="password" \   # 数据源密码
  -e TARGET_TYPE="postgres" \       # 目标存储类型
  -e TARGET_CONN="jdbc:postgresql://host:port/target_db" \  # 目标存储连接串
  -e TASK_SCHEDULE="0 0 * * *" \    # 每日凌晨执行（Cron表达式）
  [镜像仓库地址]/ingestion-framework:latest

4.2 配置说明

4.2.1 配置文件方式

推荐通过挂载配置文件（如config.yaml）定义数据摄入流程，示例配置：

yaml
# /path/to/config/config.yaml
source:
  type: "mysql"
  conn: "jdbc:mysql://source-mysql:3306/source_db"
  user: "source_user"
  password: "source_pass"
  table: "source_table"
  query: "SELECT id, name, create_time FROM source_table WHERE create_time > '{{last_exec_time}}'"  # 增量查询
transform:
  rules:
    - action: "rename"
      field: "create_time"
      new_name: "event_time"
    - action: "format_date"
      field: "event_time"
      format: "yyyy-MM-dd HH:mm:ss"
target:
  type: "postgres"
  conn: "jdbc:postgresql://target-postgres:5432/target_db"
  user: "target_user"
  password: "target_pass"
  table: "target_table"
  mode: "upsert"  # 插入或更新
  primary_key: "id"
schedule:
  cron: "0 */1 * * *"  # 每小时执行一次
logging:
  level: "INFO"
  file: "/var/log/ingestion/etl.log"

启动容器时挂载配置文件：

bash
docker run -d \
  --name ingestion-framework \
  -v /path/to/config:/app/config \
  [镜像仓库地址]/ingestion-framework:latest

4.2.2 环境变量参数

支持通过环境变量覆盖配置文件中的关键参数，常用环境变量：

4.3 Docker Compose示例

通过docker-compose.yml编排数据摄入服务与依赖组件（如目标数据库）：

yaml
version: "3.8"
services:
  ingestion-framework:
    image: [镜像仓库地址]/ingestion-framework:latest
    container_name: ingestion-framework
    volumes:
      - ./config:/app/config  # 挂载本地配置目录
      - ./logs:/var/log/ingestion  # 挂载日志目录
    environment:
      - LOG_LEVEL=INFO
      - METRICS_ENABLE=true
      - METRICS_PORT=9090
    depends_on:
      - target-postgres  # 依赖目标数据库
    restart: unless-stopped

  target-postgres:
    image: postgres:14
    container_name: target-postgres
    environment:
      - POSTGRES_DB=target_db
      - POSTGRES_USER=target_user
      - POSTGRES_PASSWORD=target_pass
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

启动服务：

bash
docker-compose up -d

4.4 查看日志与监控

• 查看容器日志：

  bash
  docker logs -f ingestion-framework
  

• 访问metrics（若启用）：

  bash
  curl http://localhost:9090/metrics
  

5. 注意事项

• 敏感信息（如数据库密码）建议通过环境变量注入或使用密钥管理工具，避免硬编码在配置文件中。
• 大规模数据同步时，建议调整JVM内存参数（通过JAVA_OPTS环境变量，如-e JAVA_OPTS="-Xmx2g -Xms1g"）。
• 增量同步需确保数据源支持基于时间戳或自增ID的增量查询，避免全表扫描导致性能问题。