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：**
```json
{
  "token": "0.xyz...",
  "cached": false,
  "solvedInMs": 4200
}
```

**Error：**
```json
{ "error": "Solver failed: ..." }
```

### `GET /api/health`

健康檢查端點。

## 本機測試

```bash
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 分鐘，不會每次請求都啟動瀏覽器