141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
# 故障排查手册
|
||
|
||
## 1. 数据库连接问题
|
||
|
||
### 1.1 连接超时
|
||
|
||
**现象**：`psycopg2.OperationalError: connection timed out` 或启动后长时间无响应。
|
||
|
||
**排查步骤**：
|
||
1. 确认 `PG_DSN` 或 `PG_HOST`/`PG_PORT` 配置正确
|
||
2. 确认 PostgreSQL 服务可达：`pg_isready -h <host> -p <port>`
|
||
3. 检查防火墙/安全组是否放行端口
|
||
4. 系统限制连接超时为 1–20 秒（`db.connect_timeout_sec`，默认 20 秒）
|
||
|
||
### 1.2 认证失败
|
||
|
||
**现象**：`FATAL: password authentication failed for user "xxx"`
|
||
|
||
**排查步骤**：
|
||
1. 确认 `.env` 中的 `PG_USER` 和 `PG_PASSWORD` 正确
|
||
2. 确认 PostgreSQL 的 `pg_hba.conf` 允许远程连接
|
||
3. 如使用 DSN 格式，确认密码中的特殊字符已 URL 编码
|
||
|
||
### 1.3 Schema 不存在
|
||
|
||
**现象**：`relation "billiards_ods.xxx" does not exist`
|
||
|
||
**解决方案**：执行 DDL 初始化脚本，参见 [环境搭建指南](environment_setup.md#4-数据库初始化)。
|
||
|
||
## 2. API 相关问题
|
||
|
||
### 2.1 API Token 无效
|
||
|
||
**现象**：HTTP 401 或 403 错误。
|
||
|
||
**排查步骤**：
|
||
1. 确认 `.env` 中的 `API_TOKEN` 有效且未过期
|
||
2. 可通过 CLI 参数 `--api-token` 临时覆盖测试
|
||
3. 检查 Token 是否包含多余空格或换行符
|
||
|
||
### 2.2 API 超时
|
||
|
||
**现象**：`requests.exceptions.Timeout` 或 `ReadTimeout`
|
||
|
||
**排查步骤**：
|
||
1. 默认超时为 20 秒（`api.timeout_sec`），可通过 `--api-timeout` 调大
|
||
2. 系统自动重试最多 3 次（退避间隔 1/2/4 秒）
|
||
3. 检查网络连通性和上游服务状态
|
||
|
||
### 2.3 API 分页数据不完整
|
||
|
||
**现象**：抓取的记录数明显少于预期。
|
||
|
||
**排查步骤**：
|
||
1. 检查时间窗口是否覆盖目标范围（`--window-start` / `--window-end`）
|
||
2. 确认分页大小设置合理（`api.page_size`，默认 200）
|
||
3. 使用 `--dry-run` 查看实际请求的时间窗口
|
||
|
||
## 3. ETL 任务问题
|
||
|
||
### 3.1 任务代码不存在
|
||
|
||
**现象**：`ValueError: 未注册的任务代码: XXX`
|
||
|
||
**解决方案**：确认任务代码拼写正确（大写蛇形命名），可用的任务代码在 `orchestration/task_registry.py` 中注册。
|
||
|
||
### 3.2 DWD 装载失败
|
||
|
||
**现象**：`DWD_LOAD_FROM_ODS` 任务报错或数据不一致。
|
||
|
||
**排查步骤**：
|
||
1. 确认 ODS 层数据已成功入库
|
||
2. 检查是否有 Schema 变更未执行迁移脚本
|
||
3. 查看日志中的具体错误信息（字段类型不匹配、约束冲突等）
|
||
|
||
### 3.3 DWS 汇总数据异常
|
||
|
||
**现象**：汇总指标与明细数据不一致。
|
||
|
||
**排查步骤**：
|
||
1. 使用 `--processing-mode verify_only` 执行校验
|
||
2. 配合 `--verify-tables` 指定具体表进行单表验证
|
||
3. 检查 DWD 层数据是否完整（时间窗口是否覆盖）
|
||
|
||
### 3.4 锁冲突
|
||
|
||
**现象**：`ERROR: deadlock detected` 或 `lock timeout`
|
||
|
||
**排查步骤**：
|
||
1. 避免多个 ETL 进程同时运行
|
||
2. 调整锁超时：`db.session.lock_timeout_ms`（默认 5000ms）
|
||
3. 事实表 upsert 可调整批量大小：`dwd.fact_upsert_batch_size`（默认 1000）
|
||
|
||
## 4. 配置问题
|
||
|
||
### 4.1 缺少必需配置
|
||
|
||
**现象**：`SystemExit: 缺少必需配置: app.store_id`
|
||
|
||
**解决方案**：在 `.env` 中设置 `STORE_ID`，或通过 CLI 参数 `--store-id` 指定。
|
||
|
||
### 4.2 配置优先级不符合预期
|
||
|
||
**排查步骤**：配置加载顺序为 `config/defaults.py` → `.env` → CLI 参数，后者覆盖前者。使用 `--dry-run` 可在不写库的情况下验证最终配置。
|
||
|
||
### 4.3 弃用配置警告
|
||
|
||
**现象**：`DeprecationWarning: 配置键 pipeline.flow=XXX 已弃用`
|
||
|
||
**解决方案**：将 `.env` 中的 `PIPELINE_FLOW` 替换为 `DATA_SOURCE`。映射关系：`FULL` → `hybrid`，`FETCH_ONLY` → `online`，`INGEST_ONLY` → `offline`。
|
||
|
||
## 5. 运行环境问题
|
||
|
||
### 5.1 Python 版本不兼容
|
||
|
||
**现象**：`SyntaxError` 或类型注解相关错误。
|
||
|
||
**解决方案**：确认 Python 版本 ≥ 3.10。代码使用了 `X | Y` 联合类型语法（3.10+）。
|
||
|
||
### 5.2 依赖缺失
|
||
|
||
**现象**：`ModuleNotFoundError: No module named 'xxx'`
|
||
|
||
**解决方案**：
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 5.3 编码问题
|
||
|
||
**现象**：`UnicodeDecodeError` 或中文乱码。
|
||
|
||
**解决方案**：确保终端和文件编码为 UTF-8。Windows 下可设置 `chcp 65001`。
|
||
|
||
## 6. 日志与调试
|
||
|
||
- 日志通过 `utils/logging_utils.py` 统一管理
|
||
- 日志输出目录：`export/LOG`（可通过 `--log-root` 覆盖）
|
||
- 使用 `--dry-run` 进行试运行，不提交数据库事务
|
||
- 安全配置 `security.redact_in_logs` 默认开启，敏感字段（token、password）在日志中自动脱敏
|