openiamdocker/synchronization

Synchronization Jar Docker镜像文档

镜像概述

Synchronization Jar Docker镜像是一个封装了数据同步功能Jar包的容器化解决方案，旨在简化数据同步服务的部署与运维流程。该镜像将同步逻辑封装为独立可执行的Jar包，并通过Docker容器提供一致、隔离的运行环境，适用于需要在不同系统、数据库或服务间进行数据同步的场景。

核心功能与特性

• 多源同步支持：兼容多种数据源类型（如关系型数据库MySQL/PostgreSQL、NoSQL数据库MongoDB/Redis、文件系统等），支持跨类型数据源同步。
• 配置化任务管理：通过配置文件定义同步任务（源地址、目标地址、字段映射、过滤条件等），无需修改代码即可调整同步规则。
• 灵活触发机制：支持手动触发、定时触发（基于Cron表达式）和事件触发（如源数据变更时）三种同步模式。
• 健壮性保障：内置同步任务日志记录、错误重试机制及异常告警功能，确保同步过程可监控、可追溯。
• 轻量级部署：基于Alpine Linux构建，镜像体积小，资源占用低，支持在各类Docker环境（单机、K8s集群等）中部署。

使用场景与适用范围

• 企业数据集成：实现业务系统（如ERP、CRM）与数据分析平台（如数据仓库、BI系统）之间的定期数据同步。
• 跨系统数据迁移：支持从旧系统向新系统迁移数据，确保数据一致性。
• 实时数据同步：对关键业务数据（如订单、用户信息）进行近实时同步，满足多系统数据一致性要求。
• 数据备份与容灾：定时将核心数据同步至备份存储或容灾系统，提升数据安全性。

使用方法与配置说明

前提条件

• 已安装Docker Engine（20.10.0+）或Docker Desktop。
• 具备目标数据源的网络访问权限（如数据库地址、端口、认证信息）。
• 已准备同步任务配置文件（格式支持.properties或.yaml，具体见配置说明）。

获取镜像

通过Docker Hub或私有仓库拉取镜像（假设镜像名为synchronization-jar，标签为latest）：

bash
docker pull docker.xuanyuan.run/synchronization-jar:latest

运行容器

基础运行命令

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

bash
docker run -d \
  --name sync-jar-instance \
  -v /path/to/local/config:/app/config \  # 挂载本地配置文件目录至容器内
  -e SYNC_CONFIG_PATH=/app/config/sync-task.yaml \  # 指定容器内配置文件路径
  -e LOG_LEVEL=INFO \  # 设置日志级别（可选，默认INFO）
  synchronization-jar:latest

Docker Compose配置示例

创建docker-compose.yml文件，定义服务及依赖：

yaml
version: '3.8'
services:
  sync-jar:
    image: docker.xuanyuan.run/synchronization-jar:latest
    container_name: sync-jar-service
    volumes:
      - ./sync-config:/app/config  # 本地配置目录映射
    environment:
      - SYNC_CONFIG_PATH=/app/config/main-task.properties
      - LOG_LEVEL=DEBUG
      - RETRY_MAX=3  # 同步失败最大重试次数（可选，默认3次）
      - RETRY_INTERVAL=5000  # 重试间隔（毫秒，可选，默认5000ms）
    restart: unless-stopped  # 异常退出时自动重启

启动服务：

bash
docker-compose up -d

配置文件说明

同步任务通过配置文件定义，支持.properties和.yaml两种格式，以下为.yaml格式示例（sync-task.yaml）：

yaml
# 源数据源配置
source:
  type: mysql  # 数据源类型：mysql/postgresql/mongodb/redis/file
  url: jdbc:mysql://source-mysql:3306/source_db  # 连接URL
  username: source_user  # 认证用户名
  password: source_pass  # 认证密码（建议通过环境变量注入，避免明文）
  table: orders  # 待同步表名（文件类型时为文件路径）
  query: "SELECT id, order_no, amount, create_time FROM orders WHERE create_time > :last_sync_time"  # 同步数据查询SQL（支持动态参数:last_sync_time）

# 目标数据源配置
target:
  type: postgresql
  url: jdbc:postgresql://target-pg:5432/target_db
  username: target_user
  password: target_pass
  table: orders_sync  # 目标表名
  conflict_strategy: update  # 冲突处理策略：ignore/update/abort（默认update）

# 同步任务配置
task:
  name: order_sync_task  # 任务名称（用于日志标识）
  trigger: cron  # 触发方式：manual/cron/event（默认cron）
  cron: "0 0 */1 * * ?"  # Cron表达式（每小时执行一次，触发方式为cron时必填）
  batch_size: 1000  # 批量同步数据量（默认1000）
  timeout: 300000  # 单次同步超时时间（毫秒，默认300000）

# 字段映射（可选，默认字段名完全匹配）
field_mapping:
  source_id: id  # 源字段source_id映射至目标字段id
  order_number: order_no  # 源字段order_number映射至目标字段order_no

环境变量说明

查看日志与监控

通过Docker命令查看容器日志：

bash
docker logs -f sync-jar-instance  # 实时查看日志
docker logs --tail=100 sync-jar-instance  # 查看最近100行日志

日志文件默认存储在容器内/app/logs目录，可通过挂载目录持久化到宿主机：

bash
docker run -d \
  --name sync-jar-instance \
  -v /path/to/local/config:/app/config \
  -v /path/to/local/logs:/app/logs \  # 挂载日志目录
  synchronization-jar:latest

注意事项

1. 配置文件权限：确保宿主机挂载的配置文件目录及文件权限正确（容器内运行用户需有读权限，建议权限设置为644）。
2. 网络连通性：容器需能访问源和目标数据源的网络地址，可通过--network参数指定Docker网络，或配置宿主机端口映射。
3. 敏感信息处理：数据源密码等敏感信息建议通过环境变量注入或使用Docker Secrets管理，避免明文写在配置文件中。
4. 资源配置：根据同步任务数据量调整JVM内存参数（JVM_OPTS）及Docker容器资源限制（如--memory=1g --cpus=0.5）。
5. 版本兼容性：不同版本镜像的配置文件格式可能存在差异，使用前请确认镜像版本与配置文件格式匹配。