---
title: browser
canonical_url: "https://www.modelscope.ai/studios/pichulin/browser"
md_url: "https://www.modelscope.ai/studios/pichulin/browser.md"
repository: pichulin/browser
last_updated: 2026-08-15
sdk_type: docker
sdk_version: 6.17.3
downloads: 0
stars: 0
---

# browser

> browser - An interactive demo by pichulin on ModelScope. Private Manual Browser — Hugging Face Docker Space

pichulin/browser is an interactive demo (Studio) on ModelScope. built with docker 6.17.3.

- **Repository**: pichulin/browser
- **SDK**: docker
- **SDK version**: 6.17.3
- **Downloads**: 0
- **Stars**: 0
- **Last updated**: 2026-08-15

Source: https://www.modelscope.ai/studios/pichulin/browser

---

# Private Manual Browser — Hugging Face Docker Space

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

```text
Google Chrome Stable → Xvfb → x11vnc → websockify/noVNC → Nginx :7860
```

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

在建議架構中，這個瀏覽器只負責 `arena-playwright-api` 的第一次 Bootstrap：帳號本人登入、處理條款／人工驗證、送出一則測試訊息，然後匯出 `ARENA_STORAGE_STATE_B64`。完成後即可 Pause 瀏覽器 Space，日常 API 由另一個 `arena-playwright-api` Space 執行。

## 必要 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`。

如果部署在 ModelScope Studio，HTTP Basic Auth 可能和 Studio 的反向代理衝突。此時可設定普通 Variable：

```text
PLATFORM_AUTH_ONLY=true
```

該模式不需要 `BROWSER_USERNAME`／`BROWSER_PASSWORD`，而是依賴 ModelScope 的短期 `studio_token` 與平台存取控制。可另外設定 `VNC_PASSWORD` Secret，讓 noVNC 連線後再要求一層原生 VNC 密碼。

只能在確認平台確實攔截無 token 的直接網址時使用；不要在一般公開 Docker 主機或 Hugging Face Public Space 啟用。

## noVNC 原生密碼（ModelScope 建議）

新增 Secret：

```text
Name: VNC_PASSWORD
Value: 至少 8 個字元的隨機密碼
```

啟用後 Logs 會顯示：

```text
Native noVNC/VNC password authentication: enabled
```

打開 noVNC 時，連線畫面會要求 VNC Password。傳統 RFB/VNC 驗證實際只使用密碼前 8 個字元，因此它只能作為 ModelScope `studio_token`／HTTPS 後方的額外保護，不能單獨取代平台存取控制。請讓前 8 個字元本身就是隨機值。

產生 8 字元隨機值：

```bash
python -c "import secrets,string; a=string.ascii_letters+string.digits; print(''.join(secrets.choice(a) for _ in range(8)))"
```

## 建議 Variables

| Variable | 預設值 | 說明 |
|---|---:|---|
| `BROWSER_WIDTH` | `1920` | 虛擬桌面寬度，640–3840。 |
| `BROWSER_HEIGHT` | `1080` | 虛擬桌面高度，640–2160。 |
| `START_URL` | `https://arena.ai/text/direct` | Google Chrome 啟動頁面。 |
| `PLATFORM_AUTH_ONLY` | `false` | ModelScope Studio 專用；設為 `true` 時依賴平台 token，停用 Nginx Basic Auth。 |

資源較少時可使用：

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

## 部署

Space repository 根目錄：

```text
Dockerfile
README.md
index.html
nginx.conf
supervisord.conf
start.sh
export_arena_state.py
```

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

## 開啟瀏覽器

造訪 Space 的直接網址：

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

瀏覽器會要求 HTTP Basic Auth：

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

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

## 開啟 Terminal

最新版已安裝 `xterm`。在遠端桌面的黑色背景按滑鼠右鍵，選擇：

```text
Terminal emulator
```

Terminal 會以非 root 使用者 `user` 開啟，預設目錄為：

```text
/home/user
```

內建常用工具：

```text
bash
curl
git
nano
procps
python
python3
pip
```

### Python 虛擬環境

Debian 不建議直接對系統 Python 執行全域 `pip install`。請建立 venv：

```bash
python --version
python -m venv /mnt/workspace/venvs/main
source /mnt/workspace/venvs/main/bin/activate
python -m pip install --upgrade pip
```

之後可以安裝一般 Python 套件：

```bash
pip install requests httpx playwright
```

如果沒有 `/mnt/workspace`，可改成暫存位置：

```bash
python -m venv ~/venv
source ~/venv/bin/activate
```

放在 `/mnt/workspace` 的 venv 可隨持久化儲存保留，但若基礎映像或 Python 版本改變，建議刪除並重建 venv。

### 匯出給 arena-playwright-api 的第一次狀態

先在可見 Google Chrome 中由帳號本人完成：

1. 登入 Arena。
2. 閱讀並決定是否接受條款。
3. 完成人工驗證。
4. 在 Direct 模式送出一則訊息並確認模型回答。

保持 Google Chrome 開啟，在 xterm 執行：

```bash
export-arena-state
```

工具只會從本機 `127.0.0.1:9222` 的 Google Chrome 讀取資料，並只保留 `arena.ai`／`lmarena.ai` 的 Cookie 與 Local Storage，不會匯出 Google 網域 Cookie。輸出位置依序選擇 `/mnt/workspace`、`/data`、`/home/user`：

```text
arena_storage_state.json
arena_storage_state.b64
```

查看 Base64 Secret 值：

```bash
cat /mnt/workspace/arena_storage_state.b64
```

將完整內容設定到 API Space 的 Secret：

```text
ARENA_STORAGE_STATE_B64
```

確認 API Space `/health` 與 `/v1/models` 正常後，即可 Pause 這個手動瀏覽器 Space。兩個輸出檔都等同登入憑證，不可提交 Git 或公開分享；完成 Secret 設定後應刪除：

```bash
rm -f /mnt/workspace/arena_storage_state.json /mnt/workspace/arena_storage_state.b64
```

容器以 UID 1000 執行，Terminal 沒有 sudo/root 權限；需要的系統套件必須預先寫入 Dockerfile 再重新 Build。瀏覽器 profile 若位於 ModelScope 持久化空間，可在 Terminal 查看：

```bash
ls -la /mnt/workspace/manual-browser/chromium-profile
```

## 持久化 Chrome Profile

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

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

其中包含：

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

如果 `/data` 不存在但平台提供可寫的 ModelScope／PAI workspace，會使用：

```text
/mnt/workspace/manual-browser/chromium-profile
```

兩者都不存在時才改用：

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

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

## 安全要求

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

## Google 登入

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

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

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

## Health Check

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

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

回傳：

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

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

## 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。

### ModelScope 顯示 `ERR_TOO_MANY_RETRIES`

這通常是 Studio proxy 與後端 HTTP Basic Auth 重試衝突。在 ModelScope 的普通 Variables 設定：

```text
PLATFORM_AUTH_ONLY=true
```

重新 Build，然後必須從 ModelScope Studio App 頁進入，讓平台附加有效 `studio_token`；不要使用不含 token 的裸 `ms.fun` 書籤。此模式移除第二層 Basic Auth，因此必須依賴 ModelScope 平台存取控制。

### `export-arena-state` 顯示 `ECONNREFUSED 127.0.0.1:9222`

先在 xterm 執行：

```bash
grep -n remote-debugging /home/user/app/start.sh
ps -eo pid,args | grep '[c]hrome'
curl -sS http://127.0.0.1:9222/json/version
```

`start.sh` 與 Google Chrome process args 都必須包含 `--remote-debugging-port=9222`。最新版啟動 Log 會顯示：

```text
Google Chrome CDP ready: http://127.0.0.1:9222
```

如果沒有，代表仍在執行舊版 `start.sh` 或容器只 Restart 而沒有重新 Build；請覆蓋 `start.sh`、`Dockerfile` 後完整重新部署。

### Nginx 顯示 `/var/lib/nginx/fastcgi` Permission denied

請使用最新版 `nginx.conf` 與 `start.sh`。所有 client/proxy/FastCGI/uWSGI/SCGI temp paths 都必須指向 `/tmp`，因為 Space 以 UID 1000 執行。

### 黑畫面

等待 10–20 秒後重新整理；檢查 Logs 中 Xvfb、Openbox、Google Chrome、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 或法律條款同意。