4.5 KiB
故障排查手册
1. 数据库连接问题
1.1 连接超时
现象：psycopg2.OperationalError: connection timed out 或启动后长时间无响应。
排查步骤：
- 确认
PG_DSN或PG_HOST/PG_PORT配置正确 - 确认 PostgreSQL 服务可达：
pg_isready -h <host> -p <port> - 检查防火墙/安全组是否放行端口
- 系统限制连接超时为 1–20 秒（
db.connect_timeout_sec，默认 20 秒）
1.2 认证失败
现象：FATAL: password authentication failed for user "xxx"
排查步骤：
- 确认
.env中的PG_USER和PG_PASSWORD正确 - 确认 PostgreSQL 的
pg_hba.conf允许远程连接 - 如使用 DSN 格式，确认密码中的特殊字符已 URL 编码
1.3 Schema 不存在
现象：relation "ods.xxx" does not exist
解决方案：执行 DDL 初始化脚本，参见 环境搭建指南。
2. API 相关问题
2.1 API Token 无效
现象：HTTP 401 或 403 错误。
排查步骤：
- 确认
.env中的API_TOKEN有效且未过期 - 可通过 CLI 参数
--api-token临时覆盖测试 - 检查 Token 是否包含多余空格或换行符
2.2 API 超时
现象：requests.exceptions.Timeout 或 ReadTimeout
排查步骤：
- 默认超时为 20 秒（
api.timeout_sec），可通过--api-timeout调大 - 系统自动重试最多 3 次（退避间隔 1/2/4 秒）
- 检查网络连通性和上游服务状态
2.3 API 分页数据不完整
现象：抓取的记录数明显少于预期。
排查步骤：
- 检查时间窗口是否覆盖目标范围（
--window-start/--window-end） - 确认分页大小设置合理（
api.page_size，默认 200） - 使用
--dry-run查看实际请求的时间窗口
3. ETL 任务问题
3.1 任务代码不存在
现象：ValueError: 未注册的任务代码: XXX
解决方案：确认任务代码拼写正确（大写蛇形命名），可用的任务代码在 orchestration/task_registry.py 中注册。
3.2 DWD 装载失败
现象：DWD_LOAD_FROM_ODS 任务报错或数据不一致。
排查步骤：
- 确认 ODS 层数据已成功入库
- 检查是否有 Schema 变更未执行迁移脚本
- 查看日志中的具体错误信息（字段类型不匹配、约束冲突等）
3.3 DWS 汇总数据异常
现象：汇总指标与明细数据不一致。
排查步骤：
- 使用
--processing-mode verify_only执行校验 - 配合
--verify-tables指定具体表进行单表验证 - 检查 DWD 层数据是否完整（时间窗口是否覆盖）
3.4 锁冲突
现象：ERROR: deadlock detected 或 lock timeout
排查步骤：
- 避免多个 ETL 进程同时运行
- 调整锁超时：
db.session.lock_timeout_ms（默认 5000ms） - 事实表 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'
解决方案：
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）在日志中自动脱敏