00 环境准备

创建云服务、安装本地客户端、一次性接入你的 agent，并启动本地应用。

开始之前，请在页面顶部选择 macOS 或 Windows。你的选择会在整门课程中保持。 Windows 使用 WSL 2 上的 Ubuntu，因此同样的 Bash、Docker、ClickHouse 和 agent 命令在每个模块中都能工作。

成果

在约 25 分钟 内，你将得到：

一个 ClickHouse Cloud 服务和一个组织级 API key；
clickhousectl 以及 clickhouse 数据库客户端；
在你的编码助手中配置好 ClickHouse skills，以及 ClickHouse 和 ClickStack 的 MCP 连接；
Langfuse 和 OpenAI 的密钥；以及
在 localhost:8080 上健康运行的应用。

ClickHouse、Postgres、ClickPipes、ClickStack/HyperDX、Langfuse 和 MCP 端点都托管在云上。只有实训应用、CLI/客户端工具、编码助手、负载生成器和无状态遥测收集器运行在你的机器上。

从第 2 步之后，除非某一步另有说明，所有命令都在应用目录中运行。

第 1 步：检查前置条件

你需要至少分配 6 GB 内存的 Docker、Git、Node.js 22+、Python 3，以及一个支持 MCP 的编码助手：Claude Code、Cursor、Codex CLI 或 Windsurf。

macOS 环境准备

安装 Docker Desktop for Mac 并在 Settings -> Resources 中至少分配 6 GB。打开 Terminal 并运行：

docker version
docker compose version
git --version
node --version
python3 --version

只有当每条命令都打印出版本号，并且 docker version 同时显示 Client 和 Server 两部分时，才继续往下。

受管控的笔记本？

公司策略可能会阻止 MCP 安装或浏览器 OAuth。如果第 7 步的 OAuth 环节打不开，请使用个人电脑，或联系你的管理员。

第 2 步：克隆仓库并切换到实训分支

在 macOS Terminal 中运行：

git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd workshops/build_workshop/app
cp .env.workshop.example .env.workshop

让这个终端保持在 ClickHouse_Demos/workshops/build_workshop/app 中。在 Windows 上，这指的是 Ubuntu 终端。预检脚本就是 这个目录里 的 ./preflight.sh。除了模块 07 的故障测试期间，一直留在 build-workshop-v1 上。现在确认一下分支：

git branch --show-current

预期输出：build-workshop-v1。

第 3 步：创建 ClickHouse Cloud 账号和 API key

开课前：创建好三个账号

如果你参加的是定期课程，请提前创建好你的 ClickHouse Cloud、Langfuse 和 OpenAI 账号。每个注册流程都可能花掉 5–10 分钟等待邮件或手机验证。在环境准备阶段再回到这里，创建练习会用到的密钥和资源。

线下培训： 使用讲师通过安全方式提供给你的、专属于学员的 ClickHouse Cloud 组织级 API key，并跳过这一步。

在 console.clickhouse.cloud 登录或开启试用。
打开 API Keys，创建一个 Admin 组织级 key，并保存它的 Key ID 和 secret。

secret 只会显示一次。请把它保存在仓库之外；不要把它放进 .env.workshop。

第 4 步：安装 `clickhousectl`

curl https://clickhouse.com/cli | sh
export PATH="$HOME/.local/bin:$PATH"
clickhousectl --version

如果新开的终端找不到 clickhousectl，就把 ~/.local/bin 加入你的 shell 配置文件。在 Windows 上，要在 Ubuntu 内安装和运行它；不要在 PowerShell 中使用 Windows 可执行文件。

第 5 步：为 `clickhousectl` 完成认证

使用第 3 步得到的 API key。交互式表单可以避免 secret 进入 shell 历史记录：

clickhousectl cloud auth login --interactive

可信的自动化流程可以使用 CLI 所期望的显式形式：

clickhousectl cloud auth login --api-key <key> --api-secret <secret>

同时验证已保存的凭据和 Cloud 访问权限：

clickhousectl cloud auth status
clickhousectl cloud org list

clickhousectl 把项目凭据保存在当前目录下的 .clickhouse/ 中。请一直从应用目录运行 Cloud 命令，并且绝不要提交或分享那个文件夹。

第 6 步：创建 ClickHouse 服务

选择你在模块 03 中也会用于 Postgres 的区域。如有需要，请替换示例中的区域：

clickhousectl cloud service create \
  --name my-workshop-clickhouse \
  --provider aws \
  --region ap-southeast-1 \
  --min-replica-memory-gb 8 \
  --max-replica-memory-gb 8 \
  --num-replicas 1 \
  --idle-scaling true \
  --idle-timeout-minutes 15

保存返回的 service ID 和一次性的 default 用户密码。检查服务是否就绪：

clickhousectl cloud service list
clickhousectl cloud service get <service-id>

安装一个与 Cloud 服务同一个主/次版本的客户端。这可以避免较新的 stable 客户端在面对略旧的 Cloud 服务端时发出「未知设置」告警：

CLICKHOUSE_VERSION=$(clickhousectl cloud service query \
  --id <service-id> \
  --format TabSeparatedRaw \
  --query "SELECT version()")
CLICKHOUSE_SERIES=$(printf '%s\n' "$CLICKHOUSE_VERSION" | cut -d. -f1,2)
clickhousectl local use "$CLICKHOUSE_SERIES"
clickhouse client --version

local use 只安装一个客户端二进制文件；它不会启动 ClickHouse 服务端。课程中的每个查询都指向 ClickHouse Cloud。从服务的 Connect 对话框中复制主机名，然后验证客户端。--password 标志会提示输入密码而不回显：

cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app"
workshop_env() { sed -n "s/^$1=//p" .env.workshop | tail -n 1; }
CLICKHOUSE_HOST=$(workshop_env CLICKHOUSE_HOST)
CLICKHOUSE_USER=$(workshop_env CLICKHOUSE_USER)
CLICKHOUSE_PASSWORD=$(workshop_env CLICKHOUSE_PASSWORD)
unset -f workshop_env

clickhouse client \
  --host "$CLICKHOUSE_HOST" \
  --secure \
  --user "$CLICKHOUSE_USER" \
  --password "$CLICKHOUSE_PASSWORD" \
  --query "SELECT version(), currentUser()"

预期输出：一行，包含 ClickHouse 版本和 default。

第 7 步：一次性配置 agent skills 和两个 MCP 服务器

这些集成各有明确的职责：

集成	用途	使用于
ClickHouse skills	依据 ClickHouse 实践审查表结构和 SQL	模块 01 和 03
ClickHouse MCP（`/mcp`）	用 `SELECT` 查询读取你的服务	模块 01 和 04
ClickStack MCP（`/clickstack`）	搜索遥测数据并保存 SRE 产物	模块 06 和 07

先为你的 agent 安装 skills：

clickhousectl skills --agent <claude|cursor|codex|windsurf>

在 ClickHouse Cloud 中，打开你服务的 Connect 对话框并启用 Connect with MCP。然后添加两个端点并完成浏览器 OAuth：

claude mcp add --transport http clickhouse-cloud https://mcp.clickhouse.cloud/mcp
claude mcp add --transport http clickstack https://mcp.clickhouse.cloud/clickstack
claude mcp login clickhouse-cloud
claude mcp login clickstack

codex mcp add clickhouse-cloud --url https://mcp.clickhouse.cloud/mcp
codex mcp add clickstack --url https://mcp.clickhouse.cloud/clickstack
codex mcp login clickhouse-cloud
codex mcp login clickstack

把下面这段一次性加入 .cursor/mcp.json，然后在 Cursor 设置中授权这两个服务器：

{
  "mcpServers": {
    "clickhouse-cloud": { "url": "https://mcp.clickhouse.cloud/mcp" },
    "clickstack": { "url": "https://mcp.clickhouse.cloud/clickstack" }
  }
}

把下面这段一次性加入 ~/.codeium/windsurf/mcp_config.json，然后授权这两个服务器：

{
  "mcpServers": {
    "clickhouse-cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/mcp"]
    },
    "clickstack": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.clickhouse.cloud/clickstack"]
    }
  }
}

现在验证 ClickHouse 连接：

Use the clickhouse-cloud MCP to list my databases. Run read-only queries only.

在模块 05 发送遥测数据之前，ClickStack 返回空结果是正常的。之后不要重复做 MCP 配置；模块 06 和 07 会使用这里配置好的 clickstack 连接。

第 8 步：创建 Langfuse 和 OpenAI 密钥

Langfuse 记录模块 08 中用到的 AI 聊天追踪数据。

线下培训： 使用讲师通过安全方式提供给你的、专属于学员的 OpenAI 项目 API key，并跳过第 3 项。你仍然需要第 1 和第 2 项中的 Langfuse 密钥。

在 US Langfuse Cloud 或 EU Langfuse Cloud 创建一个项目。
创建一对项目 API key，并保存 public key 和 secret key。
在 platform.openai.com/api-keys 创建一个项目级 API key，并启用计费。

使用你创建项目所在区域对应的 Langfuse URL：

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://us.cloud.langfuse.com

OPENAI_API_KEY=sk-...

保留 .env.workshop 中已有的模型和 API base 默认值。

第 9 步：填写 `.env.workshop`

把第 6 步的服务信息和第 8 步的密钥复制到已有的字段中：

CLICKHOUSE_HOST=<hostname without https:// or port>
CLICKHOUSE_PORT=8443
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=<one-time service password>
CLICKHOUSE_DATABASE=nyc_tlc_data
CLICKHOUSE_SECURE=true

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
OPENAI_API_KEY=sk-...

不要在 shell 中 export 这些变量名：已 export 的值会覆盖 env 文件。

第 10 步：运行预检并启动应用

下面的命令可以从克隆仓库内的任何位置进入正确的目录：

cd "$(git rev-parse --show-toplevel)/workshops/build_workshop/app"
./preflight.sh

只有当最后一行是 Overall: READY 时才继续往下。套用它打印出的任何修复建议并重新运行脚本。然后启动这套技术栈：

docker compose --env-file .env.workshop -f docker-compose.workshop.yml up -d --build
docker compose --env-file .env.workshop -f docker-compose.workshop.yml ps

大约两分钟内，本地的 backend 和 frontend 应用容器应报告 healthy，并且应用应该能在 localhost:8080 加载。本地不会启动任何数据库服务端。在模块 01 之前，看板是空的属于正常情况。

完成检查

clickhousectl cloud service get <service-id> 报告服务已就绪。
clickhouse client ... --query "SELECT version()" 执行成功。
你的 agent 能通过 ClickHouse MCP 列出数据库。
在应用目录下运行 ./preflight.sh，以 Overall: READY 结束。
Docker 服务健康，且本地应用能够加载。

继续前往 01 ClickHouse Cloud。

成果