tianyu.chu/poyee-data-warehouse: poyee数仓项目 @ a8fbd72d1f965f1433055d3f687edb36fcdb9017

4.3 DataX 脚本详细使用说明（即将重构）

DataX 脚本分为执行脚本和辅助工具两类，调用链如下：

datax-multiple-hive-job-starter.sh   （MySQL→Hive 专用批量入口，含自动分区管理）
        │
        ▼
datax-multiple-job-starter.sh        （通用批量入口）
        │
        ▼
datax-single-job-starter.sh          （单任务入口）
        │
        ├─► datax-job-config-generator.py   （ini→json 配置生成）
        │           │
        │           ▼
        │   dw_base/datax/job_config_generator.py（生成引擎）
        │
        ▼
python datax.py generated.json       （DataX 框架执行数据同步）

辅助工具：datax-gc-generator.py（连接源库元数据，批量生成 ini 配置文件）

.py 同名包装器：datax-single-job-starter.py、datax-multiple-job-starter.py、datax-multiple-hive-job-starter.py 是对应 .sh 的薄 Python 包装，仅供本地调试，禁止在 DolphinScheduler 调度中使用。

4.3.1 `datax-single-job-starter.sh` —— 单任务启动

用途：启动单个 DataX 同步任务。接受已生成的 JSON 或待生成的 ini 配置。

参数：

参数	必填	说明
`-c <path>`	二选一	DataX 作业 JSON 配置文件（绝对路径）
`-gc <path>`	二选一	DataX ini 配置文件（项目内相对路径或绝对路径），`-c` 优先
`-start-date <yyyyMMdd>`	否	开始日期，默认昨天
`-stop-date <yyyyMMdd>`	否	结束日期，默认今天
`-host <hostname>`	否	指定执行主机，优先于 `-random`
`-random`	否	随机选择 Worker 节点
`-skip-datax`	否	跳过实际 DataX 执行（仅生成配置）

Worker 选择逻辑（select_worker()）：

非 bigdata 用户 → 强制本机执行
非发布目录下执行 → 强制本机执行
指定了 -host → 使用指定主机
指定了 -random → 从 DATAX_WORKERS_QUEUE 随机选一台
都未指定 → 本机执行

HDFS 数据检查（check_data_exists()）：当 JSON 配置路径包含 hdfs- 时，会自动检查 HDFS reader 路径是否存在且有数据，无数据则跳过执行。

示例：

# 采集任务（raw 层 ini）
bin/datax-single-job-starter.sh -gc jobs/raw/trd/raw_trd_order_pay_inc_d.ini -start-date 20260415 -env prod

# 导出任务（ads 层 ini）
bin/datax-single-job-starter.sh -gc jobs/ads/trd/ads_trd_gmv_d_export.ini -start-date 20260415 -env prod

# 使用已生成的 JSON（跳过生成，env 已嵌入 JSON）
bin/datax-single-job-starter.sh -c /abs/path/to/generated.json

待重构项（见 90-重构路线.md §2.1 DataX 条目）：

-env 参数目前尚未实现，现阶段切环境靠改 datasource/ 下的实际文件或 conf/env.sh（待新建）

bin/ 下几个 DataX 启动脚本 / 生成器里还残留 conf/datax/config/ 前缀剥离逻辑（老项目遗留；该目录已迁至 conf/bak/ 并忽略入库），新项目 ini 放在 jobs/raw/ / jobs/ads/ / manual/，这段逻辑要清理掉

4.3.2 `datax-multiple-job-starter.sh` —— 通用批量启动

用途：批量启动多个 DataX 任务，支持串行/并行执行。DolphinScheduler 调度的主要入口。

参数：

参数	优先级	说明
`-c <path>`	1（最高）	JSON 配置文件，可多次传入
`-cd <dir>`	2	JSON 配置文件目录
`-gc <path>`	3	ini 配置文件，可多次传入
`-gcd <dir>`	4（最低）	ini 配置文件目录
`-start-date`	—	开始日期，默认昨天
`-stop-date`	—	结束日期，默认今天
`-host`	—	指定 Worker 节点
`-random`	—	随机选择 Worker
`-parallel`	—	并行执行（默认串行）
`-skip-datax`	—	跳过 DataX 执行

执行模式：

串行（默认）：逐个调用 datax-single-job-starter.sh，日志实时输出（tee），结束后汇报成功/失败计数
并行（-parallel）：后台启动所有任务，日志写入文件，仅限 bigdata 用户 + 发布主机

日志路径：${LOG_ROOT_DIR}/datax/${src-dst}/${project_layer_env}/${START_DATE}/${START_DATE}-${JOB_NAME}.log

示例（目标态）：

# 批量执行整个业务域下的 raw 采集 ini
bin/datax-multiple-job-starter.sh -gcd jobs/raw/trd -start-date 20260415 -env prod -parallel

# 指定多个 ini 文件串行执行
bin/datax-multiple-job-starter.sh \
  -gc jobs/raw/trd/raw_trd_order_pay_inc_d.ini \
  -gc jobs/raw/usr/raw_usr_user_info_inc_d.ini \
  -start-date 20260415 -env prod

4.3.3 `datax-multiple-hive-job-starter.sh` —— 带 Hive 分区自动管理的批量启动

用途：在 datax-multiple-job-starter.sh 之上封装了 Hive 分区自动管理。任何写入 Hive 分区表的 DataX 同步作业（不限于 MySQL→Hive）都可以用它，脚本头注释里"MySQL-Hive 作业"只是历史命名。日常采集作业的主力入口。

与 multiple-job-starter 的区别：

自动从 ini 配置中解析 Hive 表名和分区路径（parse_ddl() 函数，grep "path =" <ini>）
在执行 DataX 前自动执行 ALTER TABLE ... ADD IF NOT EXISTS PARTITION(dt=...)
支持在脚本内硬编码配置列表（partitioned_tables、generator_config_array 等数组），适合固定调度场景
支持 --override 参数临时覆盖脚本内硬编码配置

自动建分区只对 ini 输入生效：parse_ddl() 读的是 ini 里的 path = ... 行。如果走 -jc / -jcd 传已生成的 JSON，脚本没有 ini 可解析，自动建分区不触发，此时要么改用 -t db.table 显式声明分区、要么把分区记录在脚本内 partitioned_tables 数组。

额外参数：

参数	说明
`--override`	忽略脚本内硬编码的配置列表，只执行命令行传入的配置
`-t <db.table>`	显式指定需要建分区的 Hive 表，可多次传入
`-skip-add-partition`	跳过 Hive 分区创建
`-jc` / `-jcd` / `-gc` / `-gcd`	同 multiple-job-starter
`-start-date` / `-stop-date`	同上
`-random` / `-parallel` / `-skip-datax`	同上

分区解析逻辑（parse_ddl()）：

读取 ini 文件中 path = 行
检查路径是否包含 /dt=${dt}（分区标识）
从 HDFS 路径中提取 {db}.db/{table_name} → 拼接 ALTER TABLE {db}.{table} ADD IF NOT EXISTS PARTITION(dt={START_DATE})

示例（目标态）：

# 执行某业务域下所有 raw 采集 ini + 自动建 Hive 分区
bin/datax-multiple-hive-job-starter.sh \
  -gcd jobs/raw/trd \
  -start-date 20260415 -env prod -parallel

# 覆盖脚本内硬编码配置，只跑指定的失败任务
bin/datax-multiple-hive-job-starter.sh --override \
  -gc jobs/raw/trd/raw_trd_order_pay_inc_d.ini \
  -start-date 20260415 -env prod

4.3.4 `datax-job-config-generator.py` —— ini→JSON 配置生成器

用途：将人类可读的 .ini 任务配置转换为 DataX 框架所需的 .json 作业配置文件。通常由 datax-single-job-starter.sh 自动调用，也可独立执行。

参数：

参数	说明
`-c <path>`	ini 配置文件路径，可多次传入或逗号分隔
`-d <dir>`	扫描指定目录下的 ini 文件
`-r`	配合 `-d` 使用，递归扫描子目录
`-start-date`	开始日期，默认昨天
`-stop-date`	结束日期，默认今天
`-o <dir>`	输出目录（默认 `conf/datax/generated/`）

生成路径规则（当前脚本残留老逻辑，待清理）：脚本里仍保留 temp = os.path.dirname(gcf).replace(project_root_dir, '').replace('conf/datax/config/', '').split('/') 这段——老项目的 ini 放在 conf/datax/config/{src-dst}/{env}/ 下，前缀剥离后能派生出 src_dst / project_layer_env 拼接输出路径。新项目 ini 已经不走这条路径（conf/datax/config/ 整体挪到 conf/bak/ 并 gitignore），但脚本里的 replace 语句仍在执行一次无效剥离，输出会落到 conf/datax/generated/jobs/raw/trd/xxx.json——能跑但路径形态不符合新约定。

重构目标：去掉路径前缀剥离逻辑，输出统一扁平为 conf/datax/generated/{env}/{目标表名}.json。登记为硬编码待重构项，见 90-重构路线.md §2.1。

示例（目标态）：

# 生成单个 ini 对应的 JSON
python3 bin/datax-job-config-generator.py -c jobs/raw/trd/raw_trd_order_pay_inc_d.ini -env prod

# 批量生成某业务域下所有 ini（递归）
python3 bin/datax-job-config-generator.py -d jobs/raw/trd -r -env prod

# 指定日期和输出路径
python3 bin/datax-job-config-generator.py -c jobs/raw/trd/raw_trd_order_pay_inc_d.ini \
  -start-date 20260415 -stop-date 20260416 -env prod -o /tmp/datax-out

4.3.5 `datax-gc-generator.py` —— ini 配置元生成器

此部分需要完全重构，此记录仅为重构提供思路。

用途：连接源数据库读取表结构元数据，自动生成 DataX ini 配置文件。是开发阶段的辅助工具，用于批量初始化 ini 配置，生成后通常需要人工检查和调整。

通用参数：

参数	说明
`--from <type>`	源系统类型（`mysql` / `hdfs`，默认 `mysql`）
`--to <type>`	目标系统类型（`hdfs` / `hbase` / `kafka` / `mongo` / `elasticsearch` / `mysql`，默认 `hdfs`）
`--output <dir>`	生成的 ini 文件存储目录

MySQL 作为源（--from mysql）额外参数：-h（主机）、-P（端口）、-u（用户）、-p（密码）、-D（数据库）、-t（指定表）、-tr（表名正则）、-e（排除表）、-er（排除表正则）、--inc-col（增量字段，默认 update_time）

HDFS 作为源（--from hdfs）额外参数：-d（Hive 数据库）、-t（Hive 表）、-e（排除表）、--partitioned（是否分区表）

示例：

# 为 MySQL 库中所有表生成 mysql→hdfs 的 ini 配置，输出到 raw/trd 业务域
python3 bin/datax-gc-generator.py --from mysql --to hdfs \
  -h 10.0.0.1 -u reader -p xxx -D hobby_prod \
  --output jobs/raw/trd

# 只为指定表生成，排除临时表
python3 bin/datax-gc-generator.py --from mysql --to hdfs \
  -h 10.0.0.1 -u reader -p xxx -D hobby_prod \
  -tr "^order" -er "^tmp_" \
  --output jobs/raw/trd

# 为 Hive 表生成 hdfs→elasticsearch 的 ini 配置
python3 bin/datax-gc-generator.py --from hdfs --to elasticsearch \
  -d ads --partitioned \
  --output conf/datax/config/hdfs-elasticsearch/prod

安全提示：该脚本接受数据库账密作为命令行参数。生产环境中建议通过环境变量或临时文件传递敏感信息，避免密码出现在 shell history 和进程列表中。

已查证：whoami 分流 + env.sh 外配 2026-04-21 完成（kb/92 L175）；{module}/{dt}/{file}.log 统一结构仍目标态（日志模块统一 kb/92 L617 待启动）

91-重构备忘.md 12 KB Historia Raaka

4.3 DataX 脚本详细使用说明 （即将重构）

4.3.1 datax-single-job-starter.sh —— 单任务启动

4.3.2 datax-multiple-job-starter.sh —— 通用批量启动

4.3.3 datax-multiple-hive-job-starter.sh —— 带 Hive 分区自动管理的批量启动

4.3.4 datax-job-config-generator.py —— ini→JSON 配置生成器

4.3.5 datax-gc-generator.py —— ini 配置元生成器

91-重构备忘.md 12 KB

Historia Raaka

4.3 DataX 脚本详细使用说明（即将重构）

4.3.1 `datax-single-job-starter.sh` —— 单任务启动

4.3.2 `datax-multiple-job-starter.sh` —— 通用批量启动

4.3.3 `datax-multiple-hive-job-starter.sh` —— 带 Hive 分区自动管理的批量启动

4.3.4 `datax-job-config-generator.py` —— ini→JSON 配置生成器

4.3.5 `datax-gc-generator.py` —— ini 配置元生成器