故障排查

下面每一条都是真实发生过的故障：实验各部分 README 中记录的十一条， 外加在构建和测试本课程期间发现的五条。找到你的症状、 读懂原因并动手修复。如果这里没有匹配项，请查看讲师指南中的 ## Common failures 小节以更大篇幅覆盖了每个模块的讲师视角， 再往下一站就是你的解决方案架构师。

工具链与环境准备

dbt 报 mashumaro 导入错误，或者装不上

• 症状 - 安装 dbt-snowflake 或 dbt-clickhouse 失败，或者 dbt 抛出一个 提到 mashumaro 的导入错误，表面上看和你的 Python 版本毫无关系。
• 原因 - dbt-snowflake 和 dbt-clickhouse 都要求 Python 3.11、3.12 或 3.13。Python 3.14+ 会破坏它们共用的 mashumaro 依赖，而这个故障通常 在错误已经犯下之后，才在一个无关的模块里浮现。
• 修复 - 在你的系统 Python 旁边额外安装 3.13（例如 brew install python@3.13），并显式用那个解释器重建虚拟环境： python3.13 -m venv .venv。

Snowflake 源环境

terraform init 报 provider 错误

• 症状 - 在 workshop_public/snowflake_migration_lab/01-setup-snowflake/ 中执行 terraform init 时在解析某个 provider 时失败。
• 原因 - Terraform 二进制版本过旧，或者无法访问 Terraform registry。
• 修复 - 使用 Terraform >= 1.6，并确认能连通 registry。

snowsql 连接被拒绝

• 症状 - snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER} 被拒绝连接。
• 原因 - SNOWFLAKE_ORG 或 SNOWFLAKE_ACCOUNT 写错了。
• 修复 - 对照你创建的账号重新核对这两个值，然后重试同一条 snowsql 命令。

dbt run 报 relation not found

• 症状 - 在第 1 部分的 dbt 项目中执行 dbt run 时报告某个关系不 存在。
• 原因 - 数据库结构从未被创建。
• 修复 - 先运行 ./setup.sh --skip-seed，并确认 profiles.yml 指向 NYC_TAXI_DB。

Superset 显示 connection refused

• 症状 - docker-compose up 之后立刻访问第 1 部分的 Superset 界面 被拒绝连接。
• 原因 - Superset 需要大约 60 秒来初始化。
• 修复 - 等 60 秒后重试。如果仍然失败，检查 docker logs nyc_taxi_superset。

数据灌入耗时超出预期

• 症状 - workshop_public/snowflake_migration_lab/01-setup-snowflake/ 中的灌入步骤 看起来卡住了。
• 原因 - 在这个数据规模下这是 Snowflake 的正常行为，不是卡死。生成 5000 万行的 TABLE(GENERATOR) 插入大约需要 10-12 分钟，而随后对全部 5000 万行 填充 VARIANT TRIP_METADATA 列的 UPDATE 在 SMALL warehouse 上还要再花 15-20 分钟。
• 修复 - 让它跑完。这两步都不是交互式的；没有什么可重试的。

开通 ClickHouse Cloud 与迁移数据

Terraform 认证失败，报 401 Unauthorized

• 症状 - 在 workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ 中执行 terraform apply 时报 401 Unauthorized。
• 原因 - CLICKHOUSE_TOKEN_KEY 或 CLICKHOUSE_TOKEN_SECRET 写错了，或者该密钥 缺少所需的权限范围。
• 修复 - 在 ClickHouse Cloud 界面中从 Settings -> API keys 重新生成密钥对，并确保它具有 Admin 范围。

迁移脚本在运行途中失败

• 症状 - scripts/02_migrate_trips.py 在 5000 万行的拷贝过程中途中断。

• 原因 - 长时间传输期间出现的短暂网络或 warehouse 抖动。

• 修复 - 用 --resume 重跑。脚本以 ClickHouse 中已有的 max(pickup_at) 作为水位线，并跳过它已经加载过的行：

  python scripts/02_migrate_trips.py --resume

迁移脚本连接错误

• 症状 - 迁移脚本连不上 Snowflake 或 ClickHouse。

• 原因 - 当前 shell 中有一个或多个 Snowflake 或 ClickHouse 环境变量 未设置。

• 修复 - 检查它们，然后在重试前重新 source 状态文件：

  echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD
  echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD

  先运行 source .env && source .clickhouse_state，然后重试。

dbt run 报 Connection refused 或 Unknown host

• 症状 - 针对 ClickHouse 项目执行 dbt run 时无法解析或连接到 某个主机。
• 原因 - 当前 shell 中没有设置 CLICKHOUSE_HOST。
• 修复 - 在模块目录下执行 source .clickhouse_state，然后重试 dbt run。

dbt 报 Could not find profile named 'nyc_taxi_ch'

• 症状 - 在 workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch 中执行 dbt debug 或 dbt run 时立刻报 profile 缺失错误。
• 原因 - ClickHouse 的 dbt profile 从未被加进 ~/.dbt/profiles.yml。
• 修复 - 打开 workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/dbt/nyc_taxi_dbt_ch/profiles.yml.example， 把它的 nyc_taxi_ch: 块合并进你现有的 ~/.dbt/profiles.yml，作为 第二个顶层 profile。不要覆盖该文件 - 那样做会删掉 模块 01 的 nyc_taxi: profile，并破坏它步骤 4 的刷新循环。见 03 开通与迁移， 其中完整讲解了这个合并步骤。

ClickHouse 上的 dbt

dbt 运行之后 analytics.agg_hourly_zone_trips 是空的

• 症状 - 模块 04 的 dbt run 之后，analytics.agg_hourly_zone_trips 有零 行，并且任何由它支撑的仪表板图表都显示无数据。
• 原因 - 这是预期结果，不是故障。该模型的增量过滤条件是 WHERE pickup_at >= now() - INTERVAL 2 HOUR，只会匹配实时行程生产者 写入的行。迁移脚本搬来的所有行都是历史数据，因此没有 一行落在那个 2 小时窗口内。
• 修复 - 无需修复。这里的 0 就是正确值。这张表会在 05 基准测试与切换 的切换步骤之后、生产者开始直接写入 ClickHouse 时被填充。

仪表板与基准测试

Superset 显示 403 Forbidden

• 症状 - 在模块进行到一半时 Superset 界面返回 403 Forbidden。
• 原因 - 会话 cookie 过期了。
• 修复 - 登出，在 http://localhost:8088 重新登录，然后重跑 bash superset/add_clickhouse_connection.sh。

基准测试中 Q7 显示 N/A

• 症状 - run_benchmark.sh 输出的 CSV 中，查询 7 的提速倍数位置是 N/A。
• 原因 - 基准测试脚本连不上 ClickHouse。
• 修复 - 确认 CLICKHOUSE_HOST 已设置（source .clickhouse_state）且服务 正在运行，然后重跑基准测试。

导入的 Superset 仪表板连不上 ClickHouse

• 症状 - 导入 Superset 的仪表板能打开，但它们的图表访问不了 ClickHouse。
• 原因 - 已提交的导出 ZIP 中主机名被脱敏为 your-instance.clickhouse.cloud。add_clickhouse_connection.sh 会在导入前把 .env 中的真实 URI 修补进去；而通过 Superset 界面手动导入不会。
• 修复 - 使用 bash superset/add_clickhouse_connection.sh 而不是手动导入， 或者事后编辑该连接，改用你真实的 CLICKHOUSE_HOST 和凭据。

切换与一致性

一致性检查失败，或者切换看起来丢了数据行

• 症状 - 模块 05 的行数一致性检查失败，或者切换看起来像是 丢了数据。

• 原因 - --resume 追赶那一遍被跳过了。Snowflake 生产者在模块 01-05 期间持续写入，所以模块 03 的迁移只捕获了数据的一个前缀； 尾巴只存在于 Snowflake 中，直到被追赶上。过早停掉 Snowflake 生产者（例如刚做完模块 01 就停）会无声地毁掉本 模块的切换演示，因为那样就没有尾巴可追了。

• 修复 - 在检查一致性之前先跑追赶那一遍。它只搬运间隔内的数据行， 耗时是数秒到数分钟，不是原来的 40-50 分钟：

  python scripts/02_migrate_trips.py --resume
  bash scripts/01_verify_migration.sh