README.md

---
title: Private Manual Browser
emoji: 🖥️
colorFrom: gray
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
---

# Private Manual Browser — Hugging Face Docker Space

這是一個只供帳號本人操作的瀏覽器 Space：

```text
Chromium → Xvfb → x11vnc → websockify/noVNC → Nginx :7860
```

用途是讓使用者透過瀏覽器開啟 Hugging Face Space，手動操作遠端 Chromium。它不會自動解 CAPTCHA、不會自動接受條款，也不包含 OpenAI API Bridge。

## 必要 Secrets

在 **Space → Settings → Variables and secrets → Secrets** 建立：

| Secret | 說明 |
|---|---|
| `BROWSER_USERNAME` | noVNC 網頁的 HTTP Basic Auth 使用者名稱。 |
| `BROWSER_PASSWORD` | 強隨機密碼，建議至少 24 個字元。 |

產生密碼：

```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

不要把 Google、Arena 或其他網站密碼設定為 `BROWSER_PASSWORD`。

## 建議 Variables

| Variable | 預設值 | 說明 |
|---|---:|---|
| `BROWSER_WIDTH` | `1920` | 虛擬桌面寬度，640–3840。 |
| `BROWSER_HEIGHT` | `1080` | 虛擬桌面高度，640–2160。 |
| `START_URL` | `https://arena.ai/text/direct` | Chromium 啟動頁面。 |

資源較少時可使用：

```text
BROWSER_WIDTH=1366
BROWSER_HEIGHT=768
```

## 部署

Space repository 根目錄：

```text
Dockerfile
README.md
nginx.conf
supervisord.conf
start.sh
scripts/
  launch-browser.sh
  launch-nginx.sh
  launch-openbox.sh
  launch-x11vnc.sh
```

建立 Docker Space、上傳檔案、設定兩個必要 Secrets，然後 Factory Rebuild。

## 開啟瀏覽器

造訪 Space 的直接網址：

```text
https://YOUR-SPACE.hf.space/
```

瀏覽器會要求 HTTP Basic Auth：

```text
Username: BROWSER_USERNAME
Password: BROWSER_PASSWORD
```

成功後會進入 noVNC，並自動連接遠端桌面。可使用 noVNC 左側控制列調整縮放、全螢幕及剪貼簿。

## 持久化 Chrome Profile

如果 Space 已附加 Hugging Face Persistent Storage，程式會使用：

```text
/data/manual-browser/chromium-profile
```

其中包含：

- Cookies
- Local Storage
- 登入 Session
- 瀏覽器設定
- 網站權限
- 歷史紀錄

如果 `/data` 不存在，會改用：

```text
/home/user/browser-data/chromium-profile
```

並在 Logs 顯示 profile 是暫存的；容器重啟後可能遺失。

## 安全要求

1. **強烈建議使用 Private Space。** Basic Auth 是第二層保護，不應取代 Hugging Face 存取控制。
2. 使用獨立、強隨機的 `BROWSER_PASSWORD`。
3. 不要分享 Space URL 或密碼。
4. `/data` 內的 Chromium profile 等同登入憑證，不能公開或下載分享。
5. 不要在多人共用 Space 中登入私人 Google 帳號。
6. 不使用時應 Pause Space；需要撤銷所有 Session 時，刪除 `/data/manual-browser/chromium-profile`。
7. `x11vnc` 與 `websockify` 只監聽容器內的 `127.0.0.1`，外部只能經過 Nginx Basic Auth。
8. Chromium 在容器中使用 `--no-sandbox`，因此只能在受控的 Private Space 中操作可信網站。

## Google 登入

這是由使用者本人操作的可見 Chromium，不是自動輸入帳密的腳本。但 Google 仍可能因資料中心 IP、新裝置、Chromium 環境或帳號政策要求：

- MFA／2FA
- 裝置確認
- CAPTCHA
- 拒絕登入

請由帳號本人處理；本專案不會繞過 Google 安全驗證。如果 Google 拒絕此環境，請改用自己電腦的一般 Chrome 建立 Arena Storage State。

## Health Check

不需認證的程序存活端點：

```text
https://YOUR-SPACE.hf.space/healthz
```

回傳：

```json
{"status":"alive"}
```

它只表示 Nginx 存活，不代表 Chromium 已登入任何網站。

## Cronitor

可監控：

```text
GET https://YOUR-SPACE.hf.space/healthz
```

Assertions：

```text
response.code = 200
response.body contains "alive"
```

監控請求可能喚醒 Space，但不能保證 Hugging Face 免費 Space 永不休眠。

## 常見問題

### 401 Unauthorized

確認 `BROWSER_USERNAME`、`BROWSER_PASSWORD` 是 Secrets，修改後 Restart／Factory Rebuild。

### 黑畫面

等待 10–20 秒後重新整理；檢查 Logs 中 Xvfb、Openbox、Chromium、x11vnc 是否都進入 RUNNING。

### noVNC 顯示 WebSocket disconnected

確認 Nginx、websockify、x11vnc 都在運行，並使用根網址自動產生的 `path=websockify`。

### 重啟後登出

確認 Space 已附加 Persistent Storage，Logs 應顯示：

```text
Browser profile: persistent /data/manual-browser/chromium-profile
```

### 清除所有登入狀態

在 Space 停止後刪除：

```text
/data/manual-browser/chromium-profile
```

再重新啟動。這會登出所有網站並清除瀏覽器資料。

## 限制

- 這是互動式遠端瀏覽器，不是高效能桌面。
- 音訊、視訊、WebGL 與硬體加速可能受限。
- 免費 Space 可能休眠。
- Persistent Storage 需要 Hugging Face 支援的儲存方案。
- 本專案不會自動化 CAPTCHA、MFA、OAuth 或法律條款同意。