Xử lý sự cố Polymarket

Cách khắc phục chính xác cho các lỗi khi thiết lập, ở nguồn dữ liệu, ở collector và ở ClickHouse.

Windows và WSL 2

Mọi mục ở đây đều giả định môi trường Windows được hỗ trợ nêu trong 00 Thiết lập: Ubuntu trên WSL 2 với tích hợp Docker Desktop WSL.

Một câu lệnh báo "not recognized" trong PowerShell

Triệu chứng: PowerShell từ chối ./preflight.sh, source, export, hoặc một câu lệnh khác của workshop.

Nguyên nhân: PowerShell chỉ được dùng cho phần bootstrap WSL đã ghi rõ trong Module 00. Mọi câu lệnh của workshop đều chạy bên trong Ubuntu.

Mở Ubuntu từ Start menu, quay lại thư mục lab, và source lại file môi trường -- một shell mới không kế thừa nó:

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

Repository nằm dưới `/mnt/c`

Triệu chứng: bind mount của Docker chậm, ./preflight.sh báo lỗi quyền, hoặc pwd bắt đầu bằng /mnt/c/Users/.

Nguyên nhân: bản clone rơi vào hệ thống file của Windows thay vì hệ thống file Linux của WSL.

Hãy clone một bản mới trong thư mục home Linux của bạn và chỉ mang theo file .env.polymarket đã điền, không gì khác:

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 đang chạy dưới dạng WSL 1

Triệu chứng: wsl --list --verbose hiển thị Ubuntu với VERSION 1, hoặc Docker Desktop không thể tích hợp với distro.

Trong PowerShell as Administrator:

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

`docker` không dùng được bên trong Ubuntu

Triệu chứng: Docker Desktop đang chạy, nhưng Ubuntu báo docker: command not found hoặc không kết nối được daemon.

Bật Docker Desktop -> Settings -> General -> Use the WSL 2 based engine và Settings -> Resources -> WSL Integration -> Ubuntu, áp dụng thay đổi, chạy wsl --shutdown trong PowerShell, rồi mở lại Ubuntu. Khi đó docker version phải hiển thị cả phần Client và phần Server. Không cài thêm Docker Engine thứ hai bằng apt.

WSL hoặc Docker hết bộ nhớ

Triệu chứng: container collector bị kill hoặc lặp vòng khởi động lại, docker compose ... up --build thất bại giữa đường, hoặc docker info --format '{{.MemTotal}}' báo con số thấp hơn 4 GB khá nhiều.

Nguyên nhân: backend WSL 2 của Docker Desktop bị giới hạn bởi máy ảo WSL, mà mức giới hạn mặc định của nó chỉ là một phần RAM máy chủ và có thể rất nhỏ trên máy đang chạy các distro khác.

Đóng Docker Desktop, mở PowerShell, và đặt một giới hạn tường minh:

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

Khởi động Docker Desktop, mở lại Ubuntu, source lại .env.polymarket, và chạy ./preflight.sh một lần nữa.

Một script báo `/usr/bin/env: 'bash\r': No such file or directory`

Triệu chứng: ./preflight.sh thất bại ngay lập tức và lỗi có chứa bash\r hoặc ^M.

Nguyên nhân: ký tự kết thúc dòng CRLF của Windows đã thay thế ký tự LF mà repository yêu cầu, thường là vì core.autocrlf đang là true khi bạn clone.

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

Hãy xem lại git status trước khi loại bỏ bất cứ thứ gì. Nếu bản checkout không chứa công việc nào bạn cần, một bản clone mới dưới ~/ClickHouse_Demos là cách khắc phục an toàn nhất.

File môi trường có ký tự kết thúc dòng của Windows

Triệu chứng: printf hiển thị một host trông hợp lệ, nhưng ./preflight.sh hoặc clickhouse client không phân giải được nó, hoặc bắt tay TLS thất bại mà không có lý do rõ ràng.

Nguyên nhân: .env.polymarket đã được lưu bằng một editor Windows, nên mỗi giá trị kết thúc bằng một ký tự carriage return. set -a; source giữ lại nó, và CLICKHOUSE_HOST trở thành host\r.

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

Mong đợi: dấu ngoặc đóng nằm ngay sau hostname, trên cùng một dòng. Từ giờ hãy sửa file bên trong Ubuntu.

Endpoint health không mở được trong trình duyệt Windows

Triệu chứng: curl http://localhost:8090/health chạy được trong Ubuntu, nhưng cùng URL đó lại thất bại trong trình duyệt Windows.

Nguyên nhân: việc chuyển tiếp localhost của WSL được thiết lập theo từng lần boot và có thể mất hiệu lực sau khi máy ngủ hoặc sau một lần wsl --shutdown.

Hãy xác nhận cổng từ Ubuntu trước; nếu trình duyệt vẫn không truy cập được, chạy wsl --shutdown trong PowerShell rồi mở lại Ubuntu:

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

Terminal là căn cứ chính thức cho mọi bước kiểm chứng trong workshop này; trình duyệt chỉ là tiện lợi thêm.

Mạng lớp học chặn Polymarket

Triệu chứng: preflight không kết nối được Gamma, hoặc health vẫn ở degraded kèm các lỗi từ nguồn.

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

Mong đợi: status là fixture; dữ liệu tăng lên mỗi năm giây.

Health báo `websocket_stale_rest_active`

Trường hợp này có thể tự phục hồi khi last_trade_reconcile_at và last_book_fallback_at tiếp tục tiến lên. Collector kết nối lại với backoff. Không khởi động lại nó liên tục.

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

Chỉ dùng chế độ fixture nếu cả hai timestamp REST vẫn null hoặc đã cũ.

Health báo `clickhouse_write_retrying` hoặc `clickhouse_write_stalled`

Khi tiến trình còn chạy, đúng lô dữ liệu đó vẫn nằm trong bộ nhớ và được thử lại với cùng token loại trùng. Hãy sửa các giá trị Cloud, source lại file, rồi tạo lại collector:

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

Không drop các bảng; việc thử lại là an toàn.

Một lần tạo lại cưỡng bức sẽ làm mất các quote tick còn chỉ nằm trong bộ nhớ. Collector sau khi khởi động lại sẽ nạp lại các book hiện thời qua REST và đối chiếu các giao dịch công khai từ checkpoint được xác nhận cuối cùng. Workshop không khẳng định có một hàng đợi cục bộ bền vững.

Xuất hiện `missing ClickHouse tables`

Module 02 đã bị bỏ qua hoặc đã chạy trên một service khác. Hãy source file hiện tại và kiểm tra:

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"

Quay lại Module 02 nếu thiếu một đối tượng nào.

Truy vấn về thị trường biến động mạnh trả về rỗng

Nó cần có quan sát ở cả hai phía của mốc năm phút. Hãy chờ đến khi collector đã chạy ít nhất sáu phút, hoặc dùng chế độ fixture cho một buổi học có giới hạn thời gian.

Cổng 8090 đã bị chiếm

Đổi POLYMARKET_HEALTH_PORT trong .env.polymarket, source lại, và tạo lại:

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