### 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 ` | 二选一 | DataX 作业 JSON 配置文件（绝对路径） | | `-gc ` | 二选一 | DataX ini 配置文件（项目内相对路径或绝对路径），`-c` 优先 | | `-start-date ` | 否 | 开始日期，默认昨天 | | `-stop-date ` | 否 | 结束日期，默认今天 | | `-host ` | 否 | 指定执行主机，优先于 `-random` | | `-random` | 否 | 随机选择 Worker 节点 | | `-skip-datax` | 否 | 跳过实际 DataX 执行（仅生成配置） | **Worker 选择逻辑**（`select_worker()`）： 1. 非 `bigdata` 用户 → 强制本机执行 2. 非发布目录下执行 → 强制本机执行 3. 指定了 `-host` → 使用指定主机 4. 指定了 `-random` → 从 `DATAX_WORKERS_QUEUE` 随机选一台 5. 都未指定 → 本机执行 **HDFS 数据检查**（`check_data_exists()`）：当 JSON 配置路径包含 `hdfs-` 时，会自动检查 HDFS reader 路径是否存在且有数据，无数据则跳过执行。 **示例**： ```bash # 采集任务（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 ` | 1（最高） | JSON 配置文件，可多次传入 | | `-cd ` | 2 | JSON 配置文件目录 | | `-gc ` | 3 | ini 配置文件，可多次传入 | | `-gcd ` | 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` **示例**（目标态）： ```bash # 批量执行整个业务域下的 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 的区别**： 1. 自动从 ini 配置中解析 Hive 表名和分区路径（`parse_ddl()` 函数，`grep "path =" `） 2. 在执行 DataX 前自动执行 `ALTER TABLE ... ADD IF NOT EXISTS PARTITION(dt=...)` 3. 支持在脚本内硬编码配置列表（`partitioned_tables`、`generator_config_array` 等数组），适合固定调度场景 4. 支持 `--override` 参数临时覆盖脚本内硬编码配置 > **自动建分区只对 ini 输入生效**：`parse_ddl()` 读的是 ini 里的 `path = ...` 行。如果走 `-jc` / `-jcd` 传已生成的 JSON，脚本没有 ini 可解析，自动建分区**不触发**，此时要么改用 `-t db.table` 显式声明分区、要么把分区记录在脚本内 `partitioned_tables` 数组。 **额外参数**： | 参数 | 说明 | | --------------------------------------- | -------------------------------------------------- | | `--override` | 忽略脚本内硬编码的配置列表，只执行命令行传入的配置 | | `-t ` | 显式指定需要建分区的 Hive 表，可多次传入 | | `-skip-add-partition` | 跳过 Hive 分区创建 | | `-jc` / `-jcd` / `-gc` / `-gcd` | 同 multiple-job-starter | | `-start-date` / `-stop-date` | 同上 | | `-random` / `-parallel` / `-skip-datax` | 同上 | **分区解析逻辑**（`parse_ddl()`）： 1. 读取 ini 文件中 `path =` 行 2. 检查路径是否包含 `/dt=${dt}`（分区标识） 3. 从 HDFS 路径中提取 `{db}.db/{table_name}` → 拼接 `ALTER TABLE {db}.{table} ADD IF NOT EXISTS PARTITION(dt={START_DATE})` **示例**（目标态）： ```bash # 执行某业务域下所有 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 ` | ini 配置文件路径，可多次传入或逗号分隔 | | `-d ` | 扫描指定目录下的 ini 文件 | | `-r` | 配合 `-d` 使用，递归扫描子目录 | | `-start-date` | 开始日期，默认昨天 | | `-stop-date` | 结束日期，默认今天 | | `-o ` | 输出目录（默认 `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。 **示例**（目标态）： ```bash # 生成单个 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 ` | 源系统类型（`mysql` / `hdfs`，默认 `mysql`） | | `--to ` | 目标系统类型（`hdfs` / `hbase` / `kafka` / `mongo` / `elasticsearch` / `mysql`，默认 `hdfs`） | | `--output ` | 生成的 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`（是否分区表） **示例**： ```bash # 为 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 待启动）