00 环境准备

准备 macOS 或 WSL 2、创建 ClickHouse Cloud 服务，并加载一个环境变量文件。

在页面顶部选择 macOS 或 Windows。Windows 的命令在 WSL 2 上的 Ubuntu 中运行，而不是在 PowerShell 中，除非页面明确写了 PowerShell。

成果

你已装好 Docker、Git、Python、clickhousectl、ClickHouse 客户端，创建了 Cloud 服务，并且已经 source 了 .env.polymarket。preflight 打印出 READY。

第 1 步：检查笔记本电脑

安装 Docker Desktop for Mac。在 Terminal 中运行：

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

第 2 步：克隆实训仓库

git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
git switch build-workshop-v1
cd "$(git rev-parse --show-toplevel)/workshop_public/polymarket"
cp .env.polymarket.example .env.polymarket

切换分支是必需的：build-workshop-v1 是可直接使用的完整版本。

后续命令都在 ClickHouse_Demos/workshop_public/polymarket 中运行。

第 3 步：安装 `clickhousectl` 和 ClickHouse 客户端

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

local use 只安装客户端二进制文件。它不会启动数据库服务器；所有查询都指向 ClickHouse Cloud。

第 4 步：认证并创建 Cloud 服务

线下培训： 使用讲师通过安全渠道提供的、专属于学员的组织 API key。

交互式登录可以让密钥不进入 shell 历史：

clickhousectl cloud auth login --interactive
clickhousectl cloud auth status
clickhousectl cloud org list

可信的自动化流程可以使用显式写法：

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

创建一个服务。只有在讲师另有指定时才更改区域：

clickhousectl cloud service create \
  --name polymarket-workshop \
  --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

保存好服务 ID 和一次性显示的 default 用户密码。等到服务就绪：

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

第 5 步：填写并 source `.env.polymarket`

打开服务的 Connect 对话框。把纯主机名和密码填入 .env.polymarket；主机名中不要包含 https:// 或 :8443。

${EDITOR:-vi} .env.polymarket
set -a; source ./.env.polymarket; set +a

确认 shell 已加载这些非敏感值：

printf 'host=%s database=%s mode=%s\n' \
  "$CLICKHOUSE_HOST" "$CLICKHOUSE_DATABASE" "$POLYMARKET_MODE"

预期：Cloud 主机名、polymarket 和 live。

第 6 步：运行 preflight

chmod +x ./preflight.sh
./preflight.sh

预期：

READY: Docker, ClickHouse Cloud, Gamma, Data API, and CLOB REST are reachable

在屏蔽了 Polymarket 的网络上使用 fixture 模式时，最后一行会变成：

READY: Docker and ClickHouse Cloud are reachable; fixture mode will supply data

如果只有 Polymarket API 检查失败，请使用故障排查中的 fixture 回退方案。

完成标准

clickhouse client --version 执行成功；
clickhousectl cloud service get <service-id> 显示服务已就绪；
printf 输出了预期的 host/database/mode；以及
./preflight.sh 打印出 READY。

下一步：发现你要监控的市场。

成果