6.2 DataX包结构与目录说明

6.2 DataX包结构与目录说明

解压 DataX 后，目录看着多，其实各司其职。认清每个目录管什么，部署和排错都顺手。

核心目录

bin 放启动脚本（datax.py）；conf 放全局配置如 core.json、logback.xml；plugin 放所有 reader/writer 插件；job 一般用来放你写的 job.json；lib 是核心依赖 jar；log 是运行日志。

# 6.2 DataX包结构与目录说明
ls -F
# 重点看 plugin/reader 和 plugin/writer 有哪些可用插件
​

plugin 目录的秘密

plugin/reader 和 plugin/writer 下，每个子目录是一个插件，内含 jar 和 plugin_job_template.json（参数模板）。自定义插件也按这个结构放。框架靠目录名识别插件名，所以目录名必须和 job.json 里的 "name" 完全一致，大小写都不能错。

全局配置 core.json

conf/core.json 里有容器级默认参数，比如 transport 的 channel 缓冲大小、通信超时。一般不动，但遇到特定性能或稳定性问题时，这里才是真正的旋钮所在。我们改全局参数前都会备份，并在注释里写明改了什么、为什么。

我们的管理习惯

我们把所有自定义 job 放到 job/ 下，按业务分子目录，并用 git 管理这些 json 模板。这样谁改了什么、为什么改，都有迹可循。插件目录则保持原样，升级时整体替换，避免手动改插件导致版本错乱。

插件目录名就是插件名

框架靠目录名识别插件，所以 plugin/reader/xxx 的 xxx 必须和 job.json 里 "name": "xxx" 完全一致，大小写都不能错。我们见过因为目录名多一个下划线导致插件找不到的排查半小时。

我们把自定义 job 放 git 管理，插件目录保持原样，升级时整体替换，避免手动改插件导致版本错乱。环境可重现比方便更重要。

延伸与提醒

星型拓扑把 N 乘 M 的对接降到 N 加 M，变更成本随之下降。
机器核数、内存、带宽三者共同决定 channel 的甜点值。
对象存储比 FTP 更适合做跨机房中转，因为它支持断点和内网加速。
eswriter 的批量 bulk 写入，比逐条插入快一个数量级。
全量基线加增量补充，是批流配合的常见稳妥组合。
JVM 堆要给 Channel 缓冲留足空间，否则 GC 频繁拖慢吞吐。
生产环境的稳定性，常常取决于部署习惯而非某个高级特性。
权限收得越紧，凭据泄露的爆炸半径越小。
writeMode 必须和数据更新语义对齐，不能凭感觉选。
限速不是限制能力，而是给其他任务留出生存空间。
反压机制保护内存，看到任务变慢应去优化下游而非加并发。
Reader 和 Writer 互不知晓，正是插件能独立扩展的原因。
Hive 表的分区设计直接影响下游查询性能，写入时就该想清楚。
把转换逻辑下推到源库，通常比在 DataX 内部处理更高效。
把复杂 join 留在计算引擎，DataX 只做贴源搬运。
Channel 是有界缓冲，填满即触发反压保护内存。
源库索引评审应作为同步查询上线的前置环节。
日志里周期打印的读写速率，是定位瓶颈的第一手材料。
插件目录名必须和 job.json 的 name 完全一致，大小写都不能错。
rowkey 的散列前缀设计，能避免 HBase 写入热点。
preSql 里带 truncate 的任务，上线前必须二次确认目标表名。
任务的读写速率差，比绝对速率更能说明瓶颈在哪一段。
orc 加 snappy 是 Hive 落地的常见稳妥组合，省空间且查询快。

查看包内关键目录，确认插件齐全。

ls -F bin conf plugin job lib log
# 重点确认 plugin/reader plugin/writer 非空
​

背景

DataX 解压后目录层次固定。理解每个目录的用途，排错时才知道「插件在哪、配置放哪、日志去哪」。

操作：查看关键目录

# 进入解压目录，列出顶层结构
cd /opt/datax && ls -1
# 查看已安装插件，确认目标 reader/writer 是否存在
ls plugin/reader/ | head
ls plugin/writer/ | head
​

启动命令

# 把自写 job 放进 job/ 目录便于管理，再运行
mkdir -p job && cp my_job.json job/
python bin/datax.py job/my_job.json
​

结果解读

核心目录：bin（启动器 datax.py）、conf（全局配置如 core.json，含 JVM 默认参数）、plugin（reader/writer/transformer 插件 jar）、job（你放配置的地方）、log（运行日志）、lib（框架依赖）。当报 plugin not found 时，第一反应应是去 plugin/reader 下确认插件目录名与你配置的 name 是否一致。

变式

把 core.json 里的 JVM 参数（Xms/Xmx）调大，等价于启动时加 --jvm，适合统一给所有任务提内存，无需每条命令都带参数。

目录职责对照

💡 关键直觉：目录结构就是 DataX 的「使用说明书」。记住 plugin 装能力、job 放任务、conf 控全局，绝大部分「找不到 / 起不来」的故障都能在三个目录里定位。

⚠️ 常见坑：插件目录名是 mysqlreader 但 job 里写成 mysqlReader（大小写不符），Linux 下路径大小写敏感，会报 plugin not found；复制官方示例时尤其要注意插件名大小写完全匹配。

容易被忽视的几个文件

除了目录，还有几个文件值得记住：conf/core.json 里的 channel 与 transport 段控制全局缓冲与传输；conf/logback.xml 控制日志级别与落盘；插件的 plugin_job_template.json 声明依赖。排错时，90% 的「全局行为异常」都能在 core.json 里找到对应开关。

💡 关键直觉：目录告诉你「有什么」，配置文件告诉你「怎么默认工作」。改默认值前先读懂 core.json，别在每条 job 里反复写重复参数，既啰嗦又易不一致。