Polymarket 故障排查

针对环境准备、数据源、采集器和 ClickHouse 故障的精确恢复步骤。

Windows 与 WSL 2

本节的每一条都假设你使用的是 00 环境准备中受支持的 Windows 环境：WSL 2 上的 Ubuntu，并启用 Docker Desktop 的 WSL 集成。

某个命令在 PowerShell 中"无法识别"

现象：PowerShell 拒绝执行 ./preflight.sh、source、export 或其他实训命令。

原因：PowerShell 只用于模块 00 中明确标注的 WSL 初始化步骤。所有实训命令都在 Ubuntu 内部运行。

从开始菜单打开 Ubuntu，回到实验目录，并重新 source 环境变量文件，新的 shell 不会继承它：

cd "$(git rev-parse --show-toplevel)/workshop_public/polymarket"
set -a; source ./.env.polymarket; set +a
./preflight.sh

仓库位于 `/mnt/c` 下

现象：Docker 绑定挂载很慢、./preflight.sh 报权限错误，或者 pwd 以 /mnt/c/Users/ 开头。

原因：克隆落在了 Windows 文件系统上，而不是 WSL 的 Linux 文件系统上。

在你的 Linux 家目录中重新克隆一份干净的副本，除了你已填好的 .env.polymarket，什么都不要带过去：

cd ~
git config --global core.autocrlf input
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

Ubuntu 运行在 WSL 1 上

现象：wsl --list --verbose 显示 Ubuntu 的 VERSION 1，或者 Docker Desktop 无法与该发行版集成。

在以管理员身份运行的 PowerShell 中：

wsl --set-version Ubuntu 2
wsl --set-default-version 2
wsl --list --verbose

Ubuntu 内部无法使用 `docker`

现象：Docker Desktop 正在运行，但 Ubuntu 报 docker: command not found，或者连不上守护进程。

启用 Docker Desktop -> Settings -> General -> Use the WSL 2 based engine 和 Settings -> Resources -> WSL Integration -> Ubuntu，应用更改，在 PowerShell 中运行 wsl --shutdown，然后重新打开 Ubuntu。此时 docker version 必须同时显示 Client 和 Server 两部分。不要用 apt 再安装第二个 Docker Engine。

WSL 或 Docker 内存不足

现象：采集器容器被杀掉或反复重启、docker compose ... up --build 执行到一半失败，或者 docker info --format '{{.MemTotal}}' 显示远低于 4 GB。

原因：Docker Desktop 的 WSL 2 后端受 WSL 虚拟机限制，而后者的默认上限只是主机内存的一部分，在同时运行其他发行版的机器上可能很小。

关闭 Docker Desktop，打开 PowerShell，设置一个明确的上限：

@('[wsl2]', 'memory=4GB', 'processors=2') |
  Set-Content -Encoding ascii "$env:USERPROFILE\.wslconfig"
wsl --shutdown

启动 Docker Desktop，重新打开 Ubuntu，重新 source .env.polymarket，然后再次运行 ./preflight.sh。

某个脚本报 `/usr/bin/env: 'bash\r': No such file or directory`

现象：./preflight.sh 立刻失败，错误信息中包含 bash\r 或 ^M。

原因：Windows 的 CRLF 换行替换了仓库要求的 LF 换行，通常是因为你克隆时 core.autocrlf 是 true。

git config --global core.autocrlf input
git status --short
git add --renormalize .

在丢弃任何内容之前先检查 git status。如果这个 checkout 中没有你需要的工作成果，在 ~/ClickHouse_Demos 下重新做一次干净的克隆是最稳妥的恢复方式。

环境变量文件带有 Windows 换行符

现象：printf 显示的主机名看起来正常，但 ./preflight.sh 或 clickhouse client 无法解析它，或者 TLS 握手莫名失败。

原因：.env.polymarket 是用 Windows 编辑器保存的，因此每个值末尾都带一个回车符。set -a; source 会保留它，于是 CLICKHOUSE_HOST 变成了 host\r。

sed -i 's/\r$//' .env.polymarket
set -a; source ./.env.polymarket; set +a
printf 'host=[%s]\n' "$CLICKHOUSE_HOST"
./preflight.sh

预期：右方括号紧跟在主机名之后，位于同一行。从现在开始，请在 Ubuntu 内部编辑这个文件。

健康检查端点在 Windows 浏览器中打不开

现象：curl http://localhost:8090/health 在 Ubuntu 中可用，但同样的 URL 在 Windows 浏览器中失败。

原因：WSL 的 localhost 转发是每次启动时建立的，在系统休眠或执行 wsl --shutdown 之后可能失效。

先从 Ubuntu 确认端口；如果浏览器仍然访问不到，在 PowerShell 中运行 wsl --shutdown 并重新打开 Ubuntu：

curl --fail --silent http://localhost:8090/health | python3 -m json.tool

本课程中所有验证步骤都以终端为准；浏览器只是一种便利手段。

课堂网络屏蔽了 Polymarket

现象：preflight 连不上 Gamma，或者健康状态一直是 degraded 并伴有数据源错误。

sed -i.bak 's/^POLYMARKET_MODE=.*/POLYMARKET_MODE=fixture/' .env.polymarket
set -a; source ./.env.polymarket; set +a
docker compose --env-file .env.polymarket up -d --build --force-recreate collector
curl --fail --silent http://localhost:8090/health | python3 -m json.tool

预期：status 为 fixture；数据每五秒增长一次。

健康检查显示 `websocket_stale_rest_active`

只要 last_trade_reconcile_at 和 last_book_fallback_at 在持续推进，这种状态是可以自行恢复的。采集器会带退避重连。不要反复重启它。

docker compose --env-file .env.polymarket logs --tail=50 collector
sleep 35
curl --fail --silent http://localhost:8090/health | python3 -m json.tool

只有当两个 REST 时间戳都保持为 null 或陈旧时，才切换到 fixture 模式。

健康检查显示 `clickhouse_write_retrying` 或 `clickhouse_write_stalled`

只要进程还在运行，那一批数据就仍留在内存中，并会用同一个去重 token 重试。修正 Cloud 相关的配置值，source 该文件，然后重建采集器：

${EDITOR:-vi} .env.polymarket
set -a; source ./.env.polymarket; set +a
./preflight.sh
docker compose --env-file .env.polymarket up -d --force-recreate collector

不要删表；重试是安全的。

强制重建会丢弃那些仅存在于内存中的报价 tick。重启后的采集器会通过 REST 重新填充当前盘口，并从最后一个已确认的检查点开始对账公开交易。本课程并不提供持久化的本地队列。

出现 `missing ClickHouse tables`

说明模块 02 被跳过，或者当时是针对另一个服务执行的。source 当前的文件并检查：

set -a; source ./.env.polymarket; set +a
clickhouse client \
  --host "$CLICKHOUSE_HOST" \
  --port "$CLICKHOUSE_PORT" \
  --user "$CLICKHOUSE_USER" \
  --password "$CLICKHOUSE_PASSWORD" \
  --secure \
  --query "SHOW TABLES FROM polymarket"

如果缺少任何对象，请回到模块 02。

涨跌榜查询结果为空

它需要五分钟边界两侧都有观测数据。等采集器至少运行六分钟，或者在有时间限制的课堂上使用 fixture 模式。

端口 8090 已被占用

修改 .env.polymarket 中的 POLYMARKET_HEALTH_PORT，source 它，然后重建：

sed -i.bak 's/^POLYMARKET_HEALTH_PORT=.*/POLYMARKET_HEALTH_PORT=8091/' .env.polymarket
set -a; source ./.env.polymarket; set +a
docker compose --env-file .env.polymarket up -d --force-recreate collector
curl --fail --silent http://localhost:8091/health | python3 -m json.tool