artifacts/turnstile-solver/README.md

Turnstile Solver — 自建 Cloudflare Turnstile 求解服務

使用 Playwright + Headless Chromium 自動求解 Cloudflare Turnstile，免第三方 API 費用。

部署到 Vercel

1. Fork / 上傳此目錄到 GitHub

將 artifacts/turnstile-solver/ 的內容推送為一個 GitHub repo（或 monorepo 子目錄）。

2. 在 Vercel 建立新項目

1. Vercel Dashboard → Add New Project
2. 匯入你的 GitHub repo
3. Framework Preset: 選 Other
4. Root Directory: 如果是獨立 repo，留空；monorepo 則設為 artifacts/turnstile-solver
5. Build Command: 留空（Vercel 自動處理 TypeScript）
6. Output Directory: 留空

3. 設定環境變數（可選）

變數	說明	範例
SOLVER_SECRET	保護 API 的密鑰，設定後呼叫需帶 X-Solver-Secret header	my-secret-key-123
CHROMIUM_PACK_URL	自定義 Chromium 下載 URL（預設使用 v133）	留空即可

4. 部署後設定到星光工坊

部署完成後，將 Vercel 網址填入 Admin → Config → 「Playwright 求解器 URL」：

https://your-solver.vercel.app/api/solve

API 說明

POST /api/solve

返回一個有效的 Turnstile token。

Request Headers（若設定了 SOLVER_SECRET）：

X-Solver-Secret: your-secret

Query Params：

• ?force=1 — 強制清除快取，重新求解

Response：

{
  "token": "0.xyz...",
  "cached": false,
  "solvedInMs": 4200
}

Error：

{ "error": "Solver failed: ..." }

GET /api/health

健康檢查端點。

本機測試

cd artifacts/turnstile-solver
npm install
npx playwright install chromium   # 安裝本機 Chromium
npx vercel dev                    # 啟動本機 Vercel dev server
curl -X POST http://localhost:3000/api/solve

注意事項

• Vercel Hobby 方案函數大小上限 50MB，而 @sparticuz/chromium-min 在執行時動態下載 Chromium（不計入 bundle），應能通過
• 若遇到 Turnstile 無法求解（Cloudflare 偵測到機器人），建議：
  1. 加入更多 Stealth 修補（見 src/solver.ts）
  2. 換用付費服務（CapSolver）
• Token 快取 4.5 分鐘，不會每次請求都啟動瀏覽器