00 设置

学员课程 00 设置 的讲师配套材料。

时间安排

约 25 分钟。在开场讲解之前或期间就启动那些"启动后等待"的步骤（创建服务、docker compose up），让它们在讲解过程中后台运行。督促参会者在活动当天之前完成三个账号注册 （ClickHouse Cloud、Langfuse、OpenAI），每个需要 5 到 10 分钟，这样本模块才能控制在预算内。

对于混合平台的会场，为尚未安装 WSL 2 和 Docker Desktop 的 Windows 学员在开场前另外预留 10 分钟。 wsl --install 之后可能需要重启。

对于由培训师提供凭据的线下场次：

• 为每位学员分别签发临时的 ClickHouse Cloud 组织密钥和 OpenAI 项目 API 密钥。 绝不要让全场共用一个密钥。
• 通过经批准的密钥分发渠道交付每个密钥，不要用聊天工具或幻灯片。
• 设置 OpenAI 项目预算和速率限制，并在场次期间监控用量。
• 课程结束后吊销这两个密钥。任一密钥一旦泄露，立即轮换。

讲解要点

• 定调本场次：他们要把一个现有应用迁移到 ClickHouse Cloud 上，而构建工作由 agent 完成。
• CLI 只会返回 default 用户的密码一次；让学员立刻保存下来。 服务的 Connect 对话框提供主机名。
• 模块 00 现在会创建 Cloud 服务并填好所有凭据，因此"启动后等待"都前置到了这里； 模块 01 只是在这个已经存在的服务上构建 schema。
• 步骤 7 是唯一涉及 agent 集成的设置：skills、ClickHouse MCP 和 ClickStack MCP。
• 让学员在步骤 1 之前，在页面顶部选择 macOS 或 Windows。在 Windows 上， PowerShell 只用于 WSL 的 bootstrap；所有实训命令都在 Ubuntu 中运行。
• 把 WSL 2 当作 Windows 的预习内容，而不是场次内安装项。开门前确认：受支持的 Windows 版本、本地管理员权限、虚拟化、16 GB 主机内存、20 GB 可用磁盘、 Ubuntu 版本为 2，以及 Docker Desktop 的 Ubuntu 集成。

常见故障

• 工作邮箱已经绑定到某个已有的 ClickHouse 组织，因此看不到试用额度。 引导他们改用个人邮箱（预习阶段已暴露此问题）。
• 由于公司政策，编程 agent 无法添加 MCP 服务器（由预习的冒烟测试暴露）。
• docker compose up 失败，因为 Docker 分配的资源不足（需要 6 GB 以上）。
• Windows 学员把仓库克隆在了 /mnt/c 下，导致 bind mount 很慢或 CRLF 相关失败。 在 Ubuntu 内重新克隆到 ~/ClickHouse_Demos，并设置 git config --global core.autocrlf input。
• Docker Desktop 在运行，但 Ubuntu 连不上它。启用 WSL 2 引擎和明确的 Ubuntu 集成， 然后在 PowerShell 里运行 wsl --shutdown。
• 编程 agent 打开了另一个位于 C:\Users 的检出目录，而命令却在 WSL 中运行。在桌面版 agent 里 重新打开 ~/ClickHouse_Demos 这个 WSL 文件夹，并用 uname -s 确认它的终端报告的是 Linux。
• 公司政策封禁了 WSL、虚拟化、Docker Desktop 或 OAuth。这在模块进行中无法修复； 把该学员转到事先准备好的备用机或个人电脑上。
• Cloud 服务空闲缩容到零之后的第一个请求以前会返回 500；后端现在会在连接时重试唤醒， 所以第一次加载仪表板可能会停顿几秒，但会成功。不必追查这个现象。 已在 2026-07 的净室预演中确认。

重置步骤

• 如果某位参会者的试用不可用而卡住了，把他们引向备用 Cloud 服务池。
• 重新执行 cp .env.workshop.example .env.workshop 并重新填写；确认没有误提交的 .env.workshop。
• 在 Windows 上，验证 wsl --status、wsl --version 和 wsl --list --verbose；Ubuntu 必须是版本 2。在 Ubuntu 内部，pwd 应以 /home/ 开头，且 docker version 同时显示 Client 和 Server。
• TODO：确认重置命令。