153 lines
5.3 KiB
Markdown
153 lines
5.3 KiB
Markdown
# 调度配置说明
|
||
|
||
## 1. 运行模式概览
|
||
|
||
系统支持两种运行模式：
|
||
|
||
| 模式 | 说明 | 适用场景 |
|
||
|------|------|----------|
|
||
| **任务模式** | 通过 `--tasks` 指定具体任务代码 | 单任务调试、手动补数 |
|
||
| **管道模式** | 通过 `--pipeline` 指定管道类型 | 日常增量、全流程运行 |
|
||
|
||
## 2. CLI 参数详解
|
||
|
||
### 2.1 基本参数
|
||
|
||
```bash
|
||
python -m cli.main [参数]
|
||
```
|
||
|
||
| 参数 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| `--store-id` | 门店 ID（整数） | `--store-id 1` |
|
||
| `--tasks` | 任务列表，逗号分隔（任务模式） | `--tasks ODS_MEMBER,ODS_ORDER` |
|
||
| `--dry-run` | 试运行，不提交数据库事务 | `--dry-run` |
|
||
| `--pg-dsn` | PostgreSQL 连接字符串 | `--pg-dsn "postgresql://..."` |
|
||
| `--api-token` | API Bearer Token | `--api-token "xxx"` |
|
||
|
||
### 2.2 管道参数
|
||
|
||
| 参数 | 说明 | 可选值 |
|
||
|------|------|--------|
|
||
| `--pipeline` | 管道类型 | 见下方管道定义表 |
|
||
| `--processing-mode` | 处理模式（默认 `increment_only`） | `increment_only` / `verify_only` / `increment_verify` |
|
||
| `--fetch-before-verify` | 校验前先从 API 获取数据 | 仅在 `verify_only` 模式下有效 |
|
||
| `--verify-tables` | 仅校验指定表（逗号分隔） | `--verify-tables "dim_member,fact_order"` |
|
||
|
||
### 2.3 时间窗口参数
|
||
|
||
| 参数 | 说明 | 默认值 |
|
||
|------|------|--------|
|
||
| `--window-start` | 固定窗口开始时间 | 当前时间 - 24h |
|
||
| `--window-end` | 固定窗口结束时间 | 当前时间 |
|
||
| `--window-split` | 窗口切分粒度 | `none`（可选 `day` / `week` / `month`） |
|
||
| `--lookback-hours` | 回溯小时数 | `24` |
|
||
| `--overlap-seconds` | 冗余秒数（窗口重叠） | `3600` |
|
||
| `--force-window-override` | 强制使用指定窗口，不走游标兜底 | 关闭 |
|
||
|
||
### 2.4 数据源参数
|
||
|
||
| 参数 | 说明 | 可选值 |
|
||
|------|------|--------|
|
||
| `--data-source` | 数据源模式 | `online`（仅 API 抓取）/ `offline`（仅本地入库）/ `hybrid`（抓取+入库） |
|
||
| `--fetch-root` | 抓取 JSON 输出根目录 | 默认 `export/JSON` |
|
||
| `--ingest-source` | 本地清洗入库源目录 | — |
|
||
|
||
> `--pipeline-flow` 已弃用，请使用 `--data-source` 替代。映射关系：`FULL` → `hybrid`，`FETCH_ONLY` → `online`，`INGEST_ONLY` → `offline`。
|
||
|
||
## 3. 管道定义
|
||
|
||
每个管道包含一组按顺序执行的 ETL 层：
|
||
|
||
| 管道名称 | 包含层 | 典型用途 |
|
||
|----------|--------|----------|
|
||
| `api_ods` | ODS | 仅从 API 抓取原始数据 |
|
||
| `api_ods_dwd` | ODS → DWD | 抓取并清洗至明细层 |
|
||
| `api_full` | ODS → DWD → DWS → INDEX | 全流程（抓取→清洗→汇总→指数） |
|
||
| `ods_dwd` | DWD | 从 ODS 清洗至 DWD（不抓取） |
|
||
| `dwd_dws` | DWS | 从 DWD 汇总至 DWS |
|
||
| `dwd_dws_index` | DWS → INDEX | 汇总并计算指数 |
|
||
| `dwd_index` | INDEX | 仅计算指数 |
|
||
|
||
## 4. 处理模式
|
||
|
||
| 模式 | 说明 |
|
||
|------|------|
|
||
| `increment_only` | 仅执行增量 ETL（默认） |
|
||
| `verify_only` | 跳过增量，仅执行校验并修复 |
|
||
| `increment_verify` | 先增量 ETL，再校验并修复 |
|
||
|
||
校验模式下可配合 `--fetch-before-verify` 先从 API 获取最新数据再校验。
|
||
|
||
## 5. 常用命令示例
|
||
|
||
```bash
|
||
# 日常增量：全流程管道
|
||
python -m cli.main --pipeline api_full --store-id 1
|
||
|
||
# 仅抓取 ODS 数据
|
||
python -m cli.main --pipeline api_ods --store-id 1
|
||
|
||
# 指定任务模式
|
||
python -m cli.main --tasks ODS_MEMBER,ODS_ORDER --store-id 1
|
||
|
||
# 校验并修复（先获取 API 数据）
|
||
python -m cli.main --pipeline api_full --processing-mode verify_only --fetch-before-verify
|
||
|
||
# 增量 + 校验
|
||
python -m cli.main --pipeline api_full --processing-mode increment_verify
|
||
|
||
# 指定时间窗口
|
||
python -m cli.main --pipeline api_ods --window-start "2026-02-01" --window-end "2026-02-02"
|
||
|
||
# 按天切分窗口
|
||
python -m cli.main --pipeline api_full --window-split day --window-split-days 10
|
||
|
||
# 试运行
|
||
python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
|
||
```
|
||
|
||
## 6. 定时任务配置
|
||
|
||
### 6.1 使用系统定时任务
|
||
|
||
Linux（crontab）示例：
|
||
|
||
```cron
|
||
# 每天凌晨 4:00 执行全流程增量
|
||
0 4 * * * cd /path/to/etl-billiards && .venv/bin/python -m cli.main --pipeline api_full --store-id 1 >> /var/log/etl.log 2>&1
|
||
```
|
||
|
||
Windows（任务计划程序）示例：
|
||
|
||
```
|
||
程序：C:\path\to\etl-billiards\.venv\Scripts\python.exe
|
||
参数：-m cli.main --pipeline api_full --store-id 1
|
||
起始于：C:\path\to\etl-billiards
|
||
```
|
||
|
||
### 6.2 闲时窗口
|
||
|
||
系统支持闲时窗口配置，在闲时使用更大的时间窗口以减少 API 调用频率：
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| `run.idle_window.start` | `04:00` | 闲时开始 |
|
||
| `run.idle_window.end` | `16:00` | 闲时结束 |
|
||
| `run.window_minutes.default_busy` | `30` | 忙时窗口（分钟） |
|
||
| `run.window_minutes.default_idle` | `180` | 闲时窗口（分钟） |
|
||
|
||
CLI 参数覆盖：`--idle-start "04:00" --idle-end "16:00"`
|
||
|
||
## 7. 游标与增量机制
|
||
|
||
系统通过 `CursorManager` 管理每个任务的增量水位（游标）：
|
||
|
||
- 每个任务 + 门店组合维护独立的游标记录
|
||
- 游标存储在 `etl_admin` Schema 中
|
||
- 每次成功执行后，游标自动推进到当前窗口结束时间
|
||
- `--force-window-override` 可强制使用指定窗口，绕过游标
|
||
- `--allow-empty-advance` 允许空结果时仍推进游标
|
||
|
||
`RunTracker` 记录每次运行的状态、计数和耗时，用于运行历史追溯。
|