Skip to content

SCALING.md

Latest commit

 

History

History
175 lines (133 loc) · 7.36 KB

SCALING.md

File metadata and controls

175 lines (133 loc) · 7.36 KB
Raw

TraceAPI 可擴展部署指南

本文件說明如何將 TraceAPI 部署為可水平擴展的架構。

架構概覽

                    ┌─────────────────────────────────────┐
                    │  Load Balancer (optional)            │
                    └─────────────────┬───────────────────┘
                                      │
         ┌────────────────────────────┼────────────────────────────┐
         │                            │                            │
         ▼                            ▼                            ▼
  ┌─────────────┐             ┌─────────────┐             ┌─────────────┐
  │ traceapi    │             │ traceapi    │             │ traceapi    │
  │ serve -w 4 │             │ serve -w 4 │             │ serve -w 4  │
  └──────┬──────┘             └──────┬──────┘             └──────┬──────┘
         │                            │                            │
         └────────────────────────────┼────────────────────────────┘
                                      │
         ┌────────────────────────────┼────────────────────────────┐
         │                            │                            │
         ▼                            ▼                            ▼
  ┌─────────────┐             ┌─────────────┐             ┌─────────────┐
  │ PostgreSQL  │             │   Redis     │             │ S3 / MinIO   │
  │ (metadata)  │             │ (queue+    │             │ (CAS)       │
  │             │             │  rate limit│             │             │
  └─────────────┘             └──────┬─────┘             └─────────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         │                           │                           │
         ▼                           ▼                           ▼
  ┌─────────────┐             ┌─────────────┐             ┌─────────────┐
  │ Celery      │             │ Celery      │             │ Scheduler   │
  │ worker      │             │ worker      │             │ (1 實例)    │
  └─────────────┘             └─────────────┘             └─────────────┘

必要元件

元件 用途 單機替代
PostgreSQL 元資料儲存，支援高併發 SQLite
Redis Celery 佇列、per_host_rpm 限流、Scheduler 分散式鎖 -
S3/MinIO 分散式 CAS（多節點時共用） 本機檔案系統

環境變數

# 資料庫
export TRACEAPI_DB_URL_OVERRIDE="postgresql+asyncpg://user:pass@host:5432/traceapi"

# Worker 佇列
export TRACEAPI_REDIS_URL="redis://localhost:6379/0"
export TRACEAPI_USE_CELERY_WORKER=true

# CAS（多節點時建議）
export TRACEAPI_STORAGE_BACKEND=s3
export TRACEAPI_S3_ENDPOINT_URL="http://minio:9000"
export TRACEAPI_S3_BUCKET=traceapi-cas
export TRACEAPI_S3_ACCESS_KEY=minioadmin
export TRACEAPI_S3_SECRET_KEY=minioadmin

啟動方式

1. Docker Compose（推薦）

# 建置並啟動完整堆疊
docker compose up -d --build

# API: http://localhost:8787
# 包含：API (2 workers)、2 個 Celery worker、1 個 Scheduler、Redis、PostgreSQL

調整 Celery worker 數量：

docker compose up -d celery-worker --scale celery-worker=4

2. 本機多進程

# 終端 1：API（多 worker，需 PostgreSQL）
traceapi serve --workers 4

# 終端 2–N：Celery workers
traceapi celery-worker

# 終端 N+1：Scheduler（單一實例，Redis 鎖保證）
traceapi scheduler

3. 單機快速驗證

traceapi serve
traceapi worker
# SQLite + 本機 CAS，不適合生產

API 水平擴展

  • 使用 traceapi serve --workers N 啟動多個 uvicorn worker
  • 必須搭配 PostgreSQL：SQLite 多寫入會有鎖競爭
  • 後方可再加負載平衡（Nginx、Traefik 等）

Worker 水平擴展

  • 使用 Celery 時，啟動多個 traceapi celery-worker 實例
  • 每個 worker 可設 --concurrency：celery -A traceapi.worker.celery_app worker -c 4
  • 透過 Redis 共用限流（per_host_rpm）和佇列

Scheduler 單一領導者

  • 設定 TRACEAPI_REDIS_URL 時，Scheduler 使用 Redis 分散式鎖
  • 多個 scheduler 實例中，僅取得鎖的會執行排程
  • 不需手動指定單一實例

S3 儲存（多節點部署）

多主機部署時，CAS 需使用 S3/MinIO 讓所有 worker 共用：

export TRACEAPI_STORAGE_BACKEND=s3
export TRACEAPI_S3_ENDPOINT_URL="http://minio:9000"
export TRACEAPI_S3_BUCKET=traceapi-cas
# 首次使用前需建立 bucket

MinIO 建立 bucket：

docker compose --profile s3 up -d minio
# 至 http://localhost:9001 建立 bucket: traceapi-cas

瓶頸與效能調校

參數 預設 說明 高負載建議
TRACEAPI_PER_HOST_RPM 60 每 host 每分鐘 fetch 次數（0=關閉限流） 120 或 0
TRACEAPI_PER_DATASET_CONCURRENCY 4 單 dataset 同時 run 數 8
TRACEAPI_WORKER_CONCURRENCY 8 單一 in-process worker 並行數 16
TRACEAPI_ADMISSION_MAX_GLOBAL 300 全域 queued+leased+running 上限 500
TRACEAPI_MAX_QUEUE_DEPTH 200 Queue 深度上限 400

解決 SQLite 瓶頸：多 worker 或高並行時請改用 PostgreSQL：

export TRACEAPI_DB_URL_OVERRIDE="postgresql+asyncpg://user:pass@host:5432/traceapi"

解決 CAS I/O 瓶頸：多節點分散式部署時請改用 S3：

export TRACEAPI_STORAGE_BACKEND=s3
export TRACEAPI_S3_BUCKET=traceapi-cas
# 搭配 TRACEAPI_S3_ENDPOINT_URL（MinIO）或 AWS 預設

效能優化（已內建）

  • HTTP 連線複用：fetch 使用共享 httpx.AsyncClient，跨 run 複用 keepalive 連線
  • CAS Metrics：啟用 traceapi[metrics] 時，/metrics 會包含 traceapi_cas_puts_total、traceapi_cas_gets_total
  • Playwright 預熱：Worker 啟動時若 playwright_pool_size > 0，會預熱 browser pool
  • Worker 參數：traceapi worker -c 16 可覆寫並行數，traceapi celery-worker -c 8 設定 Celery concurrency

監控

  • Prometheus：pip install traceapi[metrics]，端點 /metrics
  • Health：/health 回傳 queue_depth、storage、redis、worker_mode 等