新增 CT124 Browserless 操作手冊

端點/設定/限制說明,並註記 browserless-tmp 已達 1.2G 的清理步驟。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CT124_Browserless操作手冊_20260622.md

@@ -0,0 +1,85 @@
+# CT124 Browserless（自架 headless Chromium）— 操作手冊
+
+> 主機:CT124（192.168.42.124，Ubuntu 24.04 LXC）　|　位置:`/opt/browserless`
+> 用途:程式化截圖 / 轉 PDF / 抓內容 / 跑 Puppeteer・Playwright
+
+---
+
+## 一、基本資訊
+
+- 版本:**v2.53.0**（image `ghcr.io/browserless/chromium`，2026-06 更新）
+- 容器:`browserless_chromium`（`restart: unless-stopped`）
+- 埠:`13000 → 3000`,端點 `http://192.168.42.124:13000`
+- Token:見 `.env` 的 `BROWSERLESS_TOKEN`（每個請求都要帶 `?token=<TOKEN>`）
+- 對外:**未經 NPM,僅 LAN**（`browserless/chromium.lotimmy.com` 皆不解析）
+- 官方文件:https://docs.browserless.io/
+
+## 二、操作
+
+```bash
+cd /opt/browserless
+docker compose up -d                          # 啟動 / 套用設定
+docker compose pull && docker compose up -d   # 更新到最新 image
+docker compose logs -f
+docker compose ps
+```
+（`Makefile` 也包了 `make up/down/restart/logs/ps` 等捷徑。）
+
+## 三、設定（docker-compose.yml 環境變數）
+
+| 變數 | 值 | 說明 |
+|---|---|---|
+| `CONCURRENT` | 2 | 同時並發 session 數 |
+| `TOKEN` | 見 .env | 存取權杖 |
+| `ENABLE_FUNCTIONS` | true | 開啟 `/function` 自訂腳本 |
+| `DEFAULT_STEALTH` | true | 預設隱身模式（對付一般 bot 偵測） |
+| `DEFAULT_BLOCK_ADS` | true | 預設擋廣告 |
+| `TIMEOUT` / `FUNCTION_TIMEOUT` | 60000 | 逾時 (ms) |
+| 資源限制 | 2 CPU / 2G / shm 2g | `deploy.resources` |
+
+## 四、可用端點（REST,已實測）
+
+帶 `?token=<TOKEN>`，POST + `Content-Type: application/json`:
+
+```bash
+T=<TOKEN>
+# 截圖
+curl -X POST "http://192.168.42.124:13000/chromium/screenshot?token=$T" \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://example.com","options":{"type":"png"}}' --output shot.png
+# HTML 內容
+curl -X POST "http://192.168.42.124:13000/chromium/content?token=$T" \
+  -H "Content-Type: application/json" -d '{"url":"https://example.com"}'
+# PDF
+curl -X POST "http://192.168.42.124:13000/chromium/pdf?token=$T" \
+  -H "Content-Type: application/json" -d '{"url":"https://example.com"}' --output out.pdf
+# 結構化抓取
+curl -X POST "http://192.168.42.124:13000/chromium/scrape?token=$T" \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://example.com","elements":[{"selector":"h1"}]}'
+```
+
+其他:`/chromium/function`（自訂 JS）、`/chromium/performance`、`/chromium/download`、`/chromium/playwright`。
+
+Puppeteer / Playwright 連線（WebSocket）:
+```js
+const b = await puppeteer.connect({ browserWSEndpoint: "ws://192.168.42.124:13000?token=<TOKEN>" });
+```
+
+API 文件 UI:`http://192.168.42.124:13000/docs?token=<TOKEN>`（OpenAPI:`/docs/swagger.json`）。
+
+## 五、這個 image 沒有的功能（重要）
+
+- **BrowserQL（BQL）**:`/chromium/bql` 回 404。BQL 是**獨立產品**（另一顆 image `ghcr.io/browserless/browserql`,自架屬 Enterprise）。
+- **驗證碼破解（solve / verify）**:屬 BQL 功能,本 image 沒有,也沒有 `/unblock`。
+  - 自架要解 captcha 的務實做法:在 `/function` 或 Playwright 流程中接第三方（2Captcha / CapSolver 等）。
+- `DEFAULT_STEALTH` 只降低被偵測機率,**不等於**破解驗證碼。
+
+## 六、維運注意
+
+- **`browserless-tmp/` 會脹**:bind-mount 進容器的 `/tmp`,Chromium 暫存累積,2026-06-22 已達 **1.2G**。要清就停容器後清空:
+  ```bash
+  cd /opt/browserless && docker compose down
+  rm -rf browserless-tmp/* && docker compose up -d
+  ```
+  （`CHROME_REFRESH_TIME=3600000` 每小時回收 Chrome,但 `/tmp` 殘檔不一定跟著清。）

README.md

@@ -13,3 +13,4 @@ Claude Code 工作規範見 [`CLAUDE.md`](CLAUDE.md)。
 | [CT124_故障復原_20260529.md](CT124_故障復原_20260529.md) | CT124 | 硬斷電後 Docker/Tailscale 全面當機的連鎖故障復原(38/38 容器、零資料遺失) |
 | [CT124_Jellyfin播放-11850_20260622.md](CT124_Jellyfin播放-11850_20260622.md) | CT124 | iOS 原生 AVPlayer 播 AC3-in-fMP4 報 `-11850`,關「原生播放器」即解;伺服器無誤 |
 | [CT124_Registry操作手冊_20260622.md](CT124_Registry操作手冊_20260622.md) | CT124 | 私有 Docker Registry(`registry.lotimmy.com` / UI)推拉、刪除回收、維運說明 |
+| [CT124_Browserless操作手冊_20260622.md](CT124_Browserless操作手冊_20260622.md) | CT124 | 自架 headless Chromium(`:13000`,僅 LAN)截圖/PDF/抓取/Puppeteer 端點與維運 |