# 故障排查手册

## 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 "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）在日志中自动脱敏