Auto headless + Xvfb for headless servers

Enable Chromium on machines without DISPLAY: Python auto headless
with Xvfb hints, and start.sh installs/starts Xvfb (xvfb-run or
persistent :99) so registration can run headed under a virtual display.

README.md

@@ -51,12 +51,30 @@
 
 | 依赖 | 说明 |
 |------|------|
-| Linux / macOS | 协议 mint **不需要**浏览器；回退浏览器时需要桌面 `DISPLAY` |
+| Linux / macOS | 协议 mint **不需要**浏览器；注册 / 回退浏览器需要 Chromium |
+| 无桌面服务器 | **`./start.sh` 自动 Xvfb**（无 DISPLAY 时）；失败再回退 Python headless |
 | `uv` + Python 3.13 | 见 `pyproject.toml` / `uv.lock`；可选 `mise` |
-| Chromium | 注册流程 + 协议失败回退时需要 |
+| Chromium / Chrome | 注册流程 + 协议失败回退时需要 |
 | 代理（按需） | 访问 xAI / accounts.x.ai 不通时配置 `proxy` / `cpa_proxy` |
 | 可选 | grok2api `:8000`、CLIProxyAPI(CPA) `:8317` |
 
+无头服务器（推荐直接 `./start.sh`）：
+
+```bash
+# 一键：缺啥装啥 + 无 DISPLAY 自动 xvfb-run / 常驻 Xvfb
+./start.sh --extra 1 --threads 1
+
+# 跳过 Xvfb，强制走 Python 自动 headless
+SKIP_XVFB=1 ./start.sh --extra 1
+
+# 即使已有 DISPLAY 也包一层 xvfb-run
+FORCE_XVFB=1 ./start.sh --extra 1
+
+# 手动（不经过 start.sh）
+sudo apt install -y xvfb google-chrome-stable
+xvfb-run -a uv run python -u register_cli.py --extra 1 --threads 1
+```
+
 ```bash
 cd /path/to/grok-reg-protocol-cpa
 uv sync
@@ -305,7 +323,8 @@ cpa_proxy  >  proxy  >  环境变量 https_proxy/http_proxy
 | `cpa_copy_to_hotload` | `false` | 是否复制到 CPA 热加载目录 |
 | `cpa_hotload_dir` | `""` | CPA `auth-dir`（仅 copy 时） |
 | `cpa_base_url` | `https://cli-chat-proxy.grok.com/v1` | 免费 Build **必须**此上游 |
-| `cpa_headless` | `false` | 回退浏览器建议有头 |
+| `browser_headless` | `auto` | 注册浏览器：`auto`=无 DISPLAY 自动 headless；`true`/`false` 强制 |
+| `cpa_headless` | `false` | 回退浏览器：有 DISPLAY 时建议有头；无 DISPLAY 时强制 headless |
 | `cpa_force_standalone` | `true` | 回退时独立 Chromium |
 | `cpa_mint_cookie_inject` | `true` | 回退时注入注册 cookie |
 | `cpa_mint_workers` | `-1` | mint 并发：`-1` 自动；`0` 内联；`1-10` 固定 |
@@ -463,7 +482,8 @@ uv run python -u scripts/backfill_cpa_xai_from_accounts.py \
 | `--out-dir` | 主导出目录 |
 | `--cpa-dir` | 成功后复制到 CPA 热加载目录 |
 | `--probe` | 检查是否列出 `grok-4.5` |
-| `--headless` | 回退浏览器时无头（不推荐） |
+| `--headless` | 强制无头浏览器（无 DISPLAY 时默认也会自动 headless） |
+| `--headed` | 强制有头（需 DISPLAY / xvfb-run；无显示仍回退 headless） |
 
 ### C. 从 `~/.grok/auth.json` 导出
 
@@ -523,7 +543,8 @@ curl -sS http://127.0.0.1:8317/v1/chat/completions \
 | 协议 `sso invalid` | SSO 过期/无效；会回退浏览器；检查账本第三段 |
 | 协议 verify/approve 失败 | 会话态变化 / 风控；看日志后自动回退浏览器 |
 | 一直 `authorization_pending` | 浏览器路径未完成 consent；需到「设备已授权」且 token 200 |
-| Cloudflare / Turnstile | 回退浏览器时关 headless、开 turnstilePatch、检查代理 |
+| Cloudflare / Turnstile | 优先 `xvfb-run` 有头；纯 headless 易拦；Chromium+turnstilePatch、检查代理 |
+| 浏览器 connection fails / no interface | 无 DISPLAY：已自动 headless；仍失败则装 Chrome 并用 `xvfb-run -a ...` |
 | Hotmail 收不到码 | 检查四段凭证、ClientID/Token、IMAP 主机与 alias 计数 |
 | 有 token 但无 grok-4.5 | `cpa_base_url` 是否为 `cli-chat-proxy` |
 | 注册成功但无 `cpa_auths` | `cpa_export_enabled`？看 `cpa_auths/cpa_auth_failed.txt` |