使用纽约出租车数据的 AI SRE

欢迎阅读 ClickHouse BUILD 实训手册。在接下来的三个小时里，你将拿到一个纽约出租车网约车 分析应用（React 前端、FastAPI 后端、Postgres 源数据库），并使用你自己的 agentic 编码工具 在 ClickHouse Cloud 上把它端到端搭建起来。完成后，你将拥有来自托管 Postgres 的实时变更数据 捕获（CDC）、面向你的数据的对话式 BI、完整的可观测性、一套 AI 辅助的 SRE 工作流，以及一个 端到端追踪的应用内 AI 聊天；你还将练习用 AI SRE 诊断一次真实的线上故障。

同一门课程同时支持 macOS 和 Windows。在页面顶部选择一次你的电脑类型；手册会在 所有位置显示正确的安装步骤。Windows 在 WSL 2 上的 Ubuntu 里运行共用的实训工具链。

结束时你会带走一个可运行的原型和这个仓库，可以展示给你的团队。托管的 ClickHouse、Postgres、 ClickPipes、Agents 和 ClickStack 产物在试用期内持续存在；Langfuse 的追踪数据保存在 Langfuse Cloud。下次回来时用 Docker 重启本地应用和遥测转发器即可。到最后，你可以现场演示 五样东西：

• 一个基于 ClickHouse Cloud 的实时运营看板，
• 一条从托管 Postgres 流式接入的变更数据捕获管道，
• 用 ClickHouse Agents 对你的数据做对话式 BI，
• 一个由 AI 基于你的遥测数据构建的 SRE 看板和告警，
• 以及一个在 Langfuse 中端到端追踪的应用内 AI 聊天。

本手册包含学员指南和讲师指南。学员指南带参与者逐步完成练习；讲师指南则为每个模块提供 时间安排、讲解脚本、常见故障和重置步骤。

面向学员

你将逐个模块地推进。每个模块都会说明起始检查点、解释这一步为什么重要、给出明确目标、 带你走完编号步骤，并以一个你可以自行核对的验证环节结束。你完全不必跟上全场的节奏： 如果你落后了，每个模块的「起点」部分都会准确说明你需要具备哪些条件，你可以从那里按 自己的速度追赶。

当天你需要准备：

• 一台满足 00 环境准备 中前置条件的笔记本电脑。
• 你自己的 agentic 编码工具（Claude Code、Cursor、Codex CLI 或 Windsurf），已登录且订阅有效。
• 一个可见试用额度的 ClickHouse Cloud 账号（在课前准备中创建）。
• 已在本地克隆实训应用仓库，并且 Docker 正在运行。

自主学习？ 即使没有讲师，你也可以独立完成整门课程。参见 自主学习指南，了解有哪些不同、如何把你的 编码助手当作讲师使用，以及涵盖测试中出现过的所有故障的 故障排查 参考。

面向讲师

讲师指南与学员模块一一对应。每个模块都提供时间预算、讲解脚本、现场可能发生的 故障及其解法，以及把某位学员（或全场）恢复到已知良好状态的确切重置步骤。请先阅读 讲师指南首页，了解整场流程和共享资源清单。

课程内容

你要构建的应用

实训应用是一个自包含的纽约出租车网约车业务「作战室」分析栈：

• 前端：一个 React 单页应用，包含两个看板：Ops 看板（实时运营指标）和 Historical 看板（大区间聚合和下钻）。它还承载你在模块 08 中接入的应用内 AI 聊天面板。
• 后端：一个 FastAPI 服务，暴露安全的、参数化的分析接口。
• 源数据库：由 ClickHouse 托管的 Postgres 作为运营层的事实来源，也是变更数据捕获 进入 ClickHouse 的起点。
• 分析仓库：ClickHouse Cloud，你在模块 01 中把后端指向它，它会接收 CDC、 可观测性数据和 BI 查询。

你不需要从零开始构建应用。React/FastAPI 应用在本地运行，而所有有状态的数据或产品服务 从一开始就托管在云上。

你所构建其上的平台

ClickHouse Cloud 是一个覆盖整个技术栈的统一平台，从底层的数据摄取，到在 ClickHouse 中 存储和分析，再到对其进行观测并在顶层叠加 AI。本课程将带你逐一了解这些组成部分： 你用 ClickPipes 摄取数据、在 ClickHouse 中分析、用 Managed ClickStack/HyperDX 观测。 Langfuse 和 OpenAI 是独立的托管服务。

架构（目标最终状态）

首先，按运行位置给各个组件分组：无状态的应用和工具在你的笔记本上，有状态的服务在 ClickHouse Cloud 中，以及独立的托管 AI 服务。

数据如何流动

现在跟随一次实时行程，从本地负载生成器出发，经过托管 Postgres 和 ClickPipes，进入 default.realtime_trips，最后到达应用看板。

上面的图由 workshops/build_workshop/docs/diagrams/gen_diagrams.py 生成 （修改脚本并重新运行即可重新生成 SVG），参见下面的模块流程。

模块

十个核心模块，按顺序进行。应用在 build-workshop-v1 上已经是完整的，所以除模块 07 之外 每个模块都不需要单独 checkout，你是在配置和连接服务，而不是修改应用代码。唯一需要切换 分支的地方是模块 07 中的故障分支。

这些时长加起来约为 2 小时 30 分钟的实操时间；三小时课程的其余部分是开场、过渡和 收尾演示。

如何推进

分支

应用在 build-workshop-v1 上已经完整。本课程的重点是配置和连接服务，实时 CDC、 可观测性、agents、聊天，而不是编辑应用代码，所以并不需要一个分支一个分支地累积构建：

• 在模块 00 克隆一次应用，切换到 build-workshop-v1，除了运行模块 07 的故障场景之外 一直留在这个分支上。
• 迟到的人永远不会被落下：托管资源都在服务端，完整的本地应用只需从实训分支加上 .env.workshop 就能重启。没有需要补做的逐模块 checkout。
• 唯一需要切换分支的地方在模块 07（Break and fix），它使用故障分支 （fault/01-map-not-loading、fault/02-zone-stats-500、fault/03-slow-dashboard）。 你 checkout 其中一个，诊断故障，然后保留修复内容，并通过模块 07 的 stash 并切换重置流程 回到 build-workshop-v1。

环境变量

实训配置集中存放在应用仓库根目录下的一个 .env.workshop 文件中。仓库中提交了一份 安全的 .env.workshop.example；复制它，并只填写属于你自己的那些值：

cp .env.workshop.example .env.workshop

技术栈通过 --env-file 显式读取它：

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

你会在模块 00 的准备过程中填写这些值，只有 ClickStack 那一段例外，它在模块 05 中添加：

• CLICKHOUSE_HOST、CLICKHOUSE_PASSWORD（外加 CLICKHOUSE_PORT=8443、 CLICKHOUSE_USER=default、CLICKHOUSE_DATABASE=nyc_tlc_data、CLICKHOUSE_SECURE=true）， 用于连接你的 Cloud 服务（模块 00）。CLICKHOUSE_HOST 只填写主机名，不含协议前缀和端口。
• OPENAI_API_KEY、LLM_MODEL=gpt-5.4-mini、LLM_BASE_URL，应用内聊天在运行时使用的 LLM（模块 00）。
• LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_BASE_URL，你的 Langfuse 项目（模块 00）。LANGFUSE_BASE_URL 是 Langfuse v4 的环境变量名；使用 https://us.cloud.langfuse.com（美国）或 https://cloud.langfuse.com（欧盟）。
• OTLP_AUTH_TOKEN、CLICKSTACK_DATABASE=otel、OTEL_SERVICE_NAME=nyc-taxi-backend： 可观测性配置，位于同一个 .env.workshop 文件的 ClickStack 部分（模块 05）。

绝不要提交你填好的 .env.workshop；它已被 git 忽略。

仓库结构

所有内容都在一个仓库（ClickHouse_Demos）里，位于 build-workshop-v1 分支。各项实训的 代码都放在 workshops/ 下，所以你构建其上的应用是 workshops/build_workshop/； 你正在阅读的已发布手册位于仓库根目录下的共享站点 site/ 中，同一站点也提供 Agent Arena 实训课程和静态的 RTA 指南。

site/                           # 共用的 Next.js + Fumadocs 站点，包含所有实训
  content/docs/build-workshop/  # this playbook (the site you are reading)
    index.mdx                   # this overview
    learner/                    # self-paced guide, the lessons 00-setup ... 09-wrap-up,
                                #   and a troubleshooting reference
    instructor/                 # facilitator notes: 00-setup ... 09-wrap-up
  src/                          # Next.js + Fumadocs app
  README.md                     # run, build, deploy, and authoring guide

workshops/build_workshop/
  app/                         # the NYC-taxi app you build on (cloned in module 00)
    frontend/                  # React SPA (Ops + Historical dashboards, chat panel)
    backend/                   # FastAPI analytics API + AI chat
    db/cloud/001_cloud_schema.sql   # maintainer fixture; Module 01 contains the copyable SQL
    docker-compose.workshop.yml     # 实训技术栈（Cloud + ClickPipes）
    docker-compose.otel.yml         # the ClickStack observability overlay (module 05)
    .env.workshop.example      # single env template (Cloud + chat + observability);
                               #   copy to .env.workshop and fill in your values

接下来去哪里