DataX：阿里异构数据源离线同步工具安装与使用指南

本文是 DataX（阿里巴巴离线数据同步工具） GitHub 官方 README 及《快速开始》《项目介绍》文档的完整中文整理版，命令、路径、版本与官方文档保持一致。

官方信息

项目	信息
项目名称	DataX
维护方	阿里巴巴（开源，阿里云 DataWorks 团队）
仓库地址	github.com/alibaba/DataX
商业版本	阿里云 DataWorks 数据集成
开源协议	Apache License
运行环境	Linux、JDK 1.8+、Python 2 或 3、Maven 3.x（编译用）

项目背景

DataX 是阿里云 DataWorks 数据集成的开源版本，是在阿里巴巴集团内部被广泛使用的离线数据同步工具与平台，实现了在 MySQL、Oracle、OceanBase、SQL Server、PostgreSQL、HDFS、Hive、ADS、HBase、TableStore（OTS）、MaxCompute（ODPS）、Hologres、DRDS、databend 等各种异构数据源之间高效的数据同步。相比开源版，DataWorks 数据集成还支持实时同步（读写任意组合），离线数据源种类扩充到 DB2、Kafka、Hologres、MetaQ、SAP HANA、达梦等，并提供整库迁移、批量上云、一键全增量等开箱流程，是 DataX 全面升级后的商业化版本。

为什么需要这样一个工具？现实场景中，业务库是 MySQL，日志在 HDFS，数仓用 MaxCompute，用户行为落在 HBase，运营报表要进 Oracle——如果每次都要为两种数据源的组合单独写一套搬运程序，组合数量会爆炸。DataX 的思路是把"从哪里读"和"往哪里写"拆开：读端是 Reader 插件，写端是 Writer 插件，框架只负责在两者之间搬运数据。于是理论上 DataX 框架可以支持任意数据源类型的同步工作；每接入一套新数据源，这套新插件就能和现有所有数据源互通，插件体系就此形成一个不断长大的生态系统。

商业版本说明

阿里云 DataWorks 数据集成是 DataX 团队在阿里云上的商业化产品，致力于在复杂网络环境下提供丰富的异构数据源之间高速稳定的数据移动能力。目前已支持云上近 3000 家客户，单日同步数据超过 3 万亿条，支持离线 50 多种数据源，可以做整库迁移、批量上云、增量同步、分库分表等同步方案；2020 年起又增加实时同步能力，支持 10 多种数据源读写任意组合，并提供 MySQL、Oracle 等数据源到 MaxCompute、Hologres 等大数据引擎的一键全增量同步。商业版本详情见阿里云 DataWorks 产品页。

环境要求（System Requirements）

官方《快速开始》给出的依赖非常克制：

操作系统：Linux；
JDK：1.8 以上，推荐 1.8（Oracle JDK 下载页）；
Python：2 或 3 都可以（python.org 下载）；
Apache Maven 3.x：仅当你要从源码编译 DataX 时才需要（maven.apache.org 下载）。

安装与部署步骤

官方提供两条安装路径：直接下载预编译工具包，或拉源码自行编译。

方法一：直接下载 DataX 工具包

从官方下载地址获取压缩包：datax.tar.gz（202308 版）。下载后解压到本地某个目录，进入 bin 目录即可运行同步作业：

$ cd {YOUR_DATAX_HOME}/bin
$ python datax.py {YOUR_JOB.json}

官方还提供了一个自带的自检作业，用来确认解压后的环境是否正常：

$ python {YOUR_DATAX_HOME}/bin/datax.py {YOUR_DATAX_HOME}/job/job.json

方法二：下载源码自行编译

先从 GitHub 克隆源码仓库：

$ git clone https://github.com/alibaba/DataX.git

然后用 Maven 打包：

$ cd {DataX_source_code_home}
$ mvn -U clean package assembly:assembly -Dmaven.test.skip=true

打包成功时日志会显示 BUILD SUCCESS。产物位于 {DataX_source_code_home}/target/datax/datax/，目录结构如下：

$ cd {DataX_source_code_home}
$ ls ./target/datax/datax/
bin    conf    job    lib    log    log_perf    plugin    script    tmp

其中 bin 是启动脚本，conf 是全局配置，job 是作业样例目录，plugin 下放各类 Reader/Writer 插件，log 与 log_perf 分别记录运行日志与性能日志。

使用方法：一个最小完整示例

官方演示的例子是"从 stream 读数据并打印到控制台"，正好用来理解 DataX 的作业模型。

第一步：生成作业配置模板

DataX 提供了模板命令：python datax.py -r {读插件} -w {写插件}。例如：

$ cd {YOUR_DATAX_HOME}/bin
$ python datax.py -r streamreader -w streamwriter

命令会打印出 streamreader 与 streamwriter 的文档链接，并给出一份空模板 JSON，包含 job.content（reader/writer）和 job.setting.speed.channel（并发通道数）骨架。

第二步：填写作业 JSON

官方示例把一个 stream 到 stream 的作业写成 stream2stream.json：

{
  "job": {
    "content": [
      {
        "reader": {
          "name": "streamreader",
          "parameter": {
            "sliceRecordCount": 10,
            "column": [
              { "type": "long", "value": "10" },
              { "type": "string", "value": "hello，你好，世界-DataX" }
            ]
          }
        },
        "writer": {
          "name": "streamwriter",
          "parameter": {
            "encoding": "UTF-8",
            "print": true
          }
        }
      }
    ],
    "setting": {
      "speed": { "channel": 5 }
    }
  }
}

这份配置的含义是：streamreader 每秒生成 10 条记录，包含一个 long 列和一个 string 列；streamwriter 用 UTF-8 编码打印到控制台；整个作业开 5 个并发通道。把这套模型替换成 mysqlreader + mysqlwriter、hdfsreader + mysqlwriter，就是生产上最常见的 MySQL 到 HDFS、或 Hive 回灌 MySQL 的作业。

第三步：启动作业

$ cd {YOUR_DATAX_DIR_BIN}
$ python datax.py ./stream2stream.json

运行结束后，DataX 会在日志里打印一份执行报表，包括任务启动时刻、结束时刻、总耗时、平均流量、记录写入速度、读出记录总数、读写失败总数。官方示例的输出形如：

任务启动时刻                    : 2015-12-17 11:20:15
任务结束时刻                    : 2015-12-17 11:20:25
任务总计耗时                    :                 10s
任务平均流量                    :              205B/s
记录写入速度                    :              5rec/s
读出记录总数                    :                  50
读写失败总数                    :                   0

核心架构：一次同步作业是怎么跑起来的

DataX 3.0 开源版本支持单机多线程模式运行同步作业。从一个作业的生命周期看，核心模块各司其职：

Job（作业）：DataX 接受一个同步作业后会启动一个进程，Job 模块是单个作业的中枢管理节点，承担数据清理、子任务切分（把一个大作业拆成多个子 Task）、TaskGroup 管理等职责；
Task（子任务）：Job 会根据源端的切分策略，把作业切成多个小 Task 以便并发执行。Task 是 DataX 作业的最小单元，每个 Task 负责一部分数据的同步；
TaskGroup（任务组）：切分完成后，Job 调用 Scheduler 模块，按配置的并发量把 Task 重新组合成 TaskGroup，默认单个任务组的并发数是 5；
Reader → Channel → Writer 线程：每个 Task 由 TaskGroup 启动后，会固定拉起一条 Reader→Channel→Writer 的线程链完成数据搬运；
收尾：Job 监控并等待所有 TaskGroup 完成，全部成功则进程正常退出，否则异常退出、进程退出值非 0。

官方给了一个调度实例：用户配置 20 个并发，要把 100 张分表的 MySQL 数据同步到 ODPS。DataX 先按分库分表切成 100 个 Task，再按 20 并发算出需要 4 个 TaskGroup，最后 4 个 TaskGroup 平分 100 个 Task，每个任务组以 5 并发跑完 25 个 Task。

DataX 3.0 的六大核心优势

可靠的数据质量监控：新版修复了旧版对时间戳等类型毫秒级失真的问题，支持所有强数据类型，每种插件都有自己的类型转换策略；运行时可实时展示作业状态、数据流量、速度、执行进度，并智能对比源端与目的端速度；还能对类型转换失败等"脏数据"做精确过滤、识别、采集与展示。
丰富的数据转换功能：作为服务于大数据的 ETL 工具，DataX 在搬运之外支持脱敏、补全、过滤等转换，并提供 Groovy 自定义转换函数，详见 DataX 3 transformer 文档。
精准的速度控制：提供通道（并发）、记录流、字节流三种流控模式，让作业在数据库可承受的压力内跑到最佳速度：

"speed": {
  "channel": 5,
  "byte": 1048576,
  "record": 10000
}

强劲的同步性能：每种读插件都有一种或多种切分策略，能把作业合理拆成多个 Task 并行，单机多线程模型让速度随并发近似线性增长；源端和目的端性能足够时，单个作业可以打满网卡。
健壮的容错机制：网络闪断、数据源抖动是离线同步的常见干扰。DataX 3.0 提供线程内部重试与线程级 Task Failover（失败 Task 整段重新调度），进程级与作业级重试暂未对外开放，保证作业在波动环境下稳定跑完。
极简的使用体验：下载即可用，支持 Linux 和 Windows，几步完成数据传输；运行日志会打印传输速度、Reader/Writer 性能、进程 CPU、JVM 与 GC 情况，任务结束后输出总体运行报表。

支持的数据源通道

DataX 已经形成比较全面的插件体系，主流关系型数据库、NoSQL、大数据计算系统都已接入，官方完整清单见 DataX 数据源参考指南，这里按类型归纳：

RDBMS 关系型数据库：MySQL、Oracle、OceanBase、SQLServer、PostgreSQL、DRDS、Kingbase，以及支持所有关系型数据库的通用 RDBMS 读写插件；
阿里云数仓与存储：ODPS（MaxCompute）、ADB、ADS、OSS、OCS、Hologres、AnalyticDB for PostgreSQL；
阿里云中间件：datahub、SLS；
图数据库：阿里云 GDB（读写）、Neo4j（写）；
NoSQL：OTS（TableStore）、Hbase 0.94、Hbase 1.1、Phoenix 4.x、Phoenix 5.x、MongoDB、Cassandra；
数仓与分析引擎：StarRocks、ApacheDoris、ClickHouse、Databend、Hive、kudu、selectdb；
无结构化数据：TxtFile、FTP、HDFS、Elasticsearch（写）；
时序数据库：OpenTSDB（读）、TSDB、TDengine。

每个数据源在仓库里都有独立的 xxxreader/doc 与 xxxwriter/doc 使用文档，配置参数以对应文档为准。选型时可以先按业务归类：业务库迁云选 RDBMS 一栏；日志进湖选 HDFS/Hive 与 TxtFile/FTP；OLAP 报表选 ClickHouse、StarRocks、Doris、Hologres；时序场景选 OpenTSDB、TSDB、TDengine；MongoDB、Cassandra、Neo4j、Elasticsearch 等 NoSQL 也都有对应通道。通用 RDBMS 插件的价值在于：遇到官方还没单独封装的国产数据库（如 Kingbase、达梦），只要它兼容标准 JDBC，就能先用通用插件跑通，不必等官方出新插件。

近期版本更新

DataX 后续计划按月迭代，官方欢迎社区提交 Pull Request。近期更新摘要：

datax_v202309：Phoenix 同步支持 where 条件；新增华为 GaussDB 读写插件；修复 ClickHouse Reader 报 Can't find bundle 错误；增加 DataX 调试模块；修复 ORC 空文件报错；优化 OceanBase Writer 性能；txtfilewriter 支持导出为 insert 语句；HdfsReader/HdfsWriter 支持 parquet 读写；
datax_v202308：OTS 插件更新、databend 插件更新、OceanBase 驱动修复；
datax_v202306：精简代码；新增 neo4jwriter、clickhousewriter；优化 oceanbase、hdfs、databend、txtfile 插件；
datax_v202303：精简代码；新增 adbmysqlwriter、databendwriter、selectdbwriter；修复 sqlserver、hdfs、cassandra、kudu、oss；fastjson 升级到 fastjson2；
datax_v202210 / 202209 / 202205：OceanBase、TDengine、Doris、MaxCompute、Datahub、SLS、Hologres、OSS 等通道能力更新，以及安全漏洞修复与通用打包更新。

想自己开发新插件的同学，请参考官方的 DataX 插件开发宝典。插件开发的基本思路是：继承 Reader 端的抽象基类实现从新数据源读取切片数据，再继承 Writer 端的抽象基类实现把记录写入新存储；框架会自动把新插件挂到调度模型上，与已有所有 Writer/Reader 组成新的可用通道。开发完成后按仓库约定放到对应 plugin/reader 或 plugin/writer 目录并注册，即可在作业 JSON 里像使用官方插件一样引用它。

常见问题（FAQ）

问：DataX 需要 Hadoop 环境吗？ 答：不一定。它是独立运行的离线同步程序，下载解压即用；只有在作业本身涉及 HDFS、Hive 等通道时，才需要网络能连通对应的 Hadoop 集群。
问：Python 版本有限制吗？ 答：官方说明 Python 2 或 3 都可以，启动脚本是 python datax.py job.json。
问：怎么控制同步速度？ 答：在作业 JSON 的 setting.speed.channel 里配置并发通道数，官方示例设为 5；生产上还可以按字节限速，具体见各 Reader/Writer 文档。
问：任务跑完怎么看结果？ 答：控制台会直接打印执行报表，包括平均流量、写入速度、读写记录数和失败数；详细日志在 log/ 目录。
问：开源版和商业版怎么选？ 答：离线单表迁移、内网搬运用开源版即可；实时同步、整库迁移、批量上云、一键全增量等复杂方案，以及需要 SLA 保障时，用阿里云 DataWorks 数据集成。
问：作业里 channel、byte、record 三种限速能同时用吗？ 答：可以。官方在《项目介绍》中给出的示例就是三者同写：channel=5 表示 5 个并发通道，byte=1048576（每秒 1MB）做字节流限速，record=10000 做记录流限速，三者取最严格的约束生效，防止大同步作业把在线库打挂。
问：同步中途失败怎么办？ 答：DataX 3.0 内部有线程内重试和 TaskFailover 机制，失败的子任务会被重新调度；整个作业仍失败时进程以非 0 退出，可以配合调度系统（如海豚、Airflow）做作业级重跑。
问：怎么判断作业跑快了还是慢了？ 答：看日志报表里的"任务平均流量"和"记录写入速度"，并对照源端/目的端的 IO 指标；DataX 运行时也会打印 Reader、Writer 各自的吞吐，方便定位瓶颈在哪一端。
问：Windows 上能跑吗？ 答：官方《项目介绍》写明下载即可用、支持 Linux 和 Windows；生产环境官方建议 Linux。

反馈与联系

遇到问题请优先到 DataX GitHub Issues 提交，DataX 研发与社区会定期回答；官方说明钉钉群受管控策略影响后，Issue 是主要答疑渠道。项目核心贡献者包括言柏、枕水、秋奇、青砾、一斅、云时，并感谢天烬、光戈、祁然、巴真、静行的贡献。DataX 基于 Apache License 开源，可免费商用。长期招聘信息也挂在仓库首页，联系方式为 datax@alibabacloud.com，岗位面向大数据开发平台、任务调度引擎、任务监控告警、海量异构数据同步等方向。