# 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` 殘檔不一定跟著清。）