00 环境准备

学员课程 00 环境准备 的讲师配套材料。

时间安排

总计约 30 分钟。这是课前作业，不是当天的授课内容，提前把它发给各组搭档，并在开课前一天 确认完成情况，而不是当天早上。这里没有任何环节是"跑起来就可以走开"意义上的无人值守；它是 五个工具安装、两个账号注册、一次克隆和两个 virtualenv 构建，全程都需要搭档的手放在键盘上。 一位跳过它才到场的搭档，大约需要占用 30 分钟的现场时间来补救，而这段时间会从模块 01 原本要讲的内容里扣掉。

讲解要点

• 把这个模块定位为管道铺设，而不是内容本身：两个云（Snowflake 作为源端，ClickHouse Cloud 作为目标端）、两个 dbt adapter，每个云一个，而两个 adapter 共用同一个严格的 Python 版本下限。
• 唯一值得反复讲出来的事实：dbt-snowflake 和 dbt-clickhouse 都要求 Python 3.11、3.12 或 3.13。Python 3.14+ 会让两个 adapter 共享的一个传递依赖 mashumaro 出问题。
• 指出那两个彼此独立的 virtualenv， workshop_public/snowflake_migration_lab/01-setup-snowflake/.venv 和 workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/.venv，并解释为什么 它们无法合并成一个：两个 adapter 锁定了互相冲突的依赖版本范围。
• 鼓励现在就完成两个云账号的注册，而不是留到当天：等模块 01 开始时，Snowflake 试用和 ClickHouse Cloud 试用都不应该成为阻塞项。

常见故障

• Python 3.14+ 会通过 mashumaro 破坏 dbt-snowflake 和 dbt-clickhouse。 这是本模块 的头号故障，也是最危险的一个，因为解释器版本锁错并不会在这里报错，它会在两个模块之后， 以一个令人困惑的 dbt 导入错误出现，而那个错误表面上和 Python 版本毫无关系。 在让一位搭档通过本模块之前，先确认 python3 --version 报告的是 3.11、3.12 或 3.13， 而且是每个 virtualenv 背后真正使用的那个解释器， workshop_public/snowflake_migration_lab/01-setup-snowflake/.venv 和 workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/.venv，而不只是系统 默认解释器。
• TODO：本模块在实验自带的 README 中没有记录其他故障模式。把演练中观察到的任何其他情况 记在这里（企业代理或防火墙拦截 pip install 或 terraform init、Docker Desktop 首次启动时的许可提示、试用注册的审批延迟）。

重置步骤

• 某个 venv 背后的 Python 版本不对：cd 进出错的那个模块的 virtualenv 目录， workshop_public/snowflake_migration_lab/01-setup-snowflake/ 或 workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/，然后删除它并用锁定的 解释器重建，例如 rm -rf .venv && python3.13 -m venv .venv && source .venv/bin/activate，再按学员页面第 4 步的方式重新安装该 venv 对应的 adapter。
• 本模块没有适用的销毁脚本，此时两个云上都还没有开通任何资源。 如果一位搭档需要重做某个步骤，直接重跑比重置任何东西都更省事。
• TODO：在演练中确认，对于 Wi-Fi 不稳定的教室，提前分发一个预构建好的 venv 是否值得， 而不是当天现场安装五个工具和两个 venv。