Linux_Export_Guide.md

# 在 Linux 桌面提取 `ARENA_STORAGE_STATE_B64`

本指南只在 Linux 電腦完成第一次人工登入與狀態匯出，不會在 Linux 部署 API。

## 0. 適用條件

你需要：

- 有圖形桌面的 Linux，而不是只有 SSH 的純伺服器。
- x86_64/amd64 架構，或已經能正常運行 Google Chrome 的其他架構。
- 自己有權使用的 Google/Arena 帳號。
- 能在官方 Arena 頁面自行處理條款、MFA、CAPTCHA。

檢查架構：

```bash
uname -m
```

一般 Google Chrome `.deb` 適用：

```text
x86_64
```

## 1. 安裝基本工具

Ubuntu/Debian：

```bash
sudo apt update
sudo apt install -y python3 python3-pip python3-venv unzip curl wget
```

確認：

```bash
python3 --version
curl --version
unzip -v | head
```

## 2. 解壓專案

假設 ZIP 在 `~/Downloads`：

```bash
mkdir -p ~/arena-state-export
unzip ~/Downloads/arena-playwright-api-space.zip -d ~/arena-state-export
cd ~/arena-state-export
```

確認工具：

```bash
test -f tools/export_storage_state.py && echo "export tool found"
```

若顯示 `export tool found` 才繼續。

## 3. 建立 Python venv

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install playwright==1.62.0
```

確認套件：

```bash
python -c "import playwright; print('Playwright Python ready')"
```

這裡只透過 CDP 連接一般 Google Chrome，不需要執行 `playwright install chromium`。

## 4. 安裝／確認 Google Chrome

先檢查：

```bash
command -v google-chrome-stable || command -v google-chrome
```

若已安裝：

```bash
google-chrome-stable --version 2>/dev/null || google-chrome --version
```

Ubuntu/Debian x86_64 尚未安裝時：

```bash
cd /tmp
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install -y ./google-chrome-stable_current_amd64.deb
rm -f google-chrome-stable_current_amd64.deb
```

## 5. 啟動專用 Google Chrome

不要使用日常 Chrome Profile。專用 Profile 包含暫時的 Google/Arena Session，完成後會刪除。

先建立目錄：

```bash
mkdir -p ~/.cache/arena-google-profile
```

在第一個 Terminal 執行：

```bash
google-chrome-stable \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.cache/arena-google-profile" \
  --new-window \
  "https://arena.ai/text/direct"
```

若系統指令是 `google-chrome`：

```bash
google-chrome \
  --remote-debugging-address=127.0.0.1 \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.cache/arena-google-profile" \
  --new-window \
  "https://arena.ai/text/direct"
```

請保持第一個 Terminal 和 Chrome 都開著。

## 6. 確認 CDP

開第二個 Terminal：

```bash
curl -sS http://127.0.0.1:9222/json/version
```

正常應包含：

```text
Browser
Protocol-Version
webSocketDebuggerUrl
```

只查看必要欄位：

```bash
curl -sS http://127.0.0.1:9222/json/version | \
python3 -c 'import json,sys; x=json.load(sys.stdin); print(x.get("Browser")); print(x.get("webSocketDebuggerUrl"))'
```

如果 Connection refused：

```bash
ps -eo pid,args | grep '[c]hrome'
```

確認參數包含：

```text
--remote-debugging-port=9222
--user-data-dir=/home/.../.cache/arena-google-profile
```

## 7. 在 Chrome 完成人工操作

在專用 Chrome 中：

1. 使用自己的 Google 帳號登入 Arena。
2. 由帳號本人完成 MFA、裝置確認或 CAPTCHA。
3. 回到 `https://arena.ai/text/direct`。
4. 自行閱讀並決定是否接受 Arena 條款。
5. 選擇任意模型。
6. 發送：`請回答：Linux Storage State 測試成功`。
7. 等待模型實際回答。
8. 不要關閉 Chrome。

只登入但沒有發送訊息可能不會建立完整條款與對話狀態。

## 8. 執行匯出

在第二個 Terminal：

```bash
cd ~/arena-state-export
source .venv/bin/activate
python tools/export_storage_state.py --cdp-url http://127.0.0.1:9222
```

按照提示確認操作已完成，再按 Enter。

成功輸出：

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

## 9. 驗證輸出，不顯示 Secret 值

```bash
ls -lh arena_storage_state.json arena_storage_state.b64
wc -c arena_storage_state.b64
```

檢查只包含 Arena 網域，不列出 Cookie value：

```bash
python - <<'PY'
import base64, gzip, json
from pathlib import Path

encoded = Path("arena_storage_state.b64").read_text().strip()
state = json.loads(gzip.decompress(base64.b64decode(encoded)).decode())
print("Cookie domains:", sorted({c.get("domain") for c in state.get("cookies", [])}))
print("Origins:", [o.get("origin") for o in state.get("origins", [])])
print("Cookie count:", len(state.get("cookies", [])))
PY
```

預期只出現：

```text
arena.ai
*.arena.ai
lmarena.ai
*.lmarena.ai
```

不應出現：

```text
google.com
accounts.google.com
```

## 10. 複製 Base64

Wayland：

```bash
sudo apt install -y wl-clipboard
wl-copy < arena_storage_state.b64
```

X11：

```bash
sudo apt install -y xclip
xclip -selection clipboard < arena_storage_state.b64
```

沒有剪貼簿工具：

```bash
cat arena_storage_state.b64
```

複製完整單行內容；不要增加引號或 `ARENA_STORAGE_STATE_B64=` 前綴。

## 11. 設定 API Space

新增／更新 Secret：

```text
ARENA_STORAGE_STATE_B64
```

Google Storage State 模式保留：

```text
ADMIN_PASSWORD
BRIDGE_API_KEY
ARENA_STORAGE_STATE_B64
```

刪除：

```text
SETUP_CODE
ARENA_EMAIL
ARENA_PASSWORD
```

重新 Build API Space，檢查：

```text
/health
/v1/models
/v1/chat/completions
```

## 12. 安全清理

確認 API 正常後：

```bash
cd ~/arena-state-export
rm -f arena_storage_state.json arena_storage_state.b64
deactivate
rm -rf ~/.cache/arena-google-profile
```

如果曾把檔案提交 Git 或公開分享，請立即撤銷 Arena/Google Session 並重新建立狀態。

## 常見問題

### Google 顯示瀏覽器不安全

確認你使用的是一般 `google-chrome-stable`，而不是 Playwright 內建 Chromium；Google 登入必須由本人手動完成。

### `No Arena cookies or Local Storage were found`

確認在同一個專用 Chrome 中登入 Arena、處理條款、送出訊息並看到回答，再匯出。

### API 仍回傳 `account_consent_required`

可能在條款確認前就匯出。刪除舊輸出，回到專用 Chrome 再確認條款與聊天，重新執行匯出。

### API 回傳 503

查看 API Space Logs 與 `/health`；確認 Secret 是完整單行 Base64，沒有引號、前綴或截斷。