# 2026-06-12 远程浏览器（Playwright Worker）上线

## 摘要

在 **66.154.115.131** 部署 `browser-worker`（Playwright Chromium），Nexus 主站桥接 WebSocket + canvas 浮动面板，替代已移除的 iframe 方案。

## 动机

运维需在面板内完整浏览公网站点（不受 X-Frame-Options 限制）；Chromium 运行在独立 Worker，隔离 SSRF 与内存压力。

## 涉及文件

| 区域 | 文件 |
|------|------|
| Worker | `browser-worker/*` |
| 后端 | `server/api/browser.py`, `browser_session.py`, `server/infrastructure/browser/*`, `server/utils/browser_url_safe.py`, `server/utils/browser_ui_state.py`, `server/config.py`, `server/main.py` |
| 前端 | `GlobalBrowserPanel.vue`, `useGlobalBrowser.ts`, `useRemoteBrowserSession.ts`, `BrowserPage.vue`, `App.vue`, `router`, `ServersPage.vue` |
| 测试 | `tests/test_browser_url_safe.py`, `tests/test_browser_ui_state.py` |

## 部署拓扑

```
管理员 SPA → Nexus (20.24.218.235) → Worker (66.154.115.131:8443) → 公网
```

## 生产配置（勿提交 git）

主站 `/var/lib/nexus/.env` 与 `docker/.env.prod` 均需：

```env
NEXUS_BROWSER_ENABLED=1
NEXUS_BROWSER_WORKER_URL=http://66.154.115.131:8443
NEXUS_BROWSER_WORKER_SECRET=<与 Worker .env WORKER_SECRET 相同>
NEXUS_BROWSER_MAX_SESSIONS=2
NEXUS_BROWSER_IDLE_TIMEOUT_SEC=1800
```

Worker：`/opt/nexus-browser-worker/.env`（`WORKER_SECRET` 同上）

防火墙：Worker `8443` 已对 Nexus 主站 IP `20.24.218.235` 放行。

## 迁移 / 重启

- 无 DB 迁移（复用 `admin_ui_preferences` / `embedded_browser`）
- Worker：`docker compose up -d --build`
- 主站：重建/重启 `nexus-prod-nexus-1` + 同步 `web/app`

## 验证

```bash
venv/bin/pytest tests/test_browser_url_safe.py tests/test_browser_ui_state.py -q
cd frontend && npm run type-check && npx vite build
curl -H "Authorization: Bearer $TOKEN" https://api.synaglobal.vip/api/browser/status
# → enabled:true, worker_ok:true
```

浏览器：左下角地球按钮 / 侧栏「浏览器」；输入 `https://example.com` 应出现 canvas 画面。

## 回滚

`NEXUS_BROWSER_ENABLED=0` 重启主站；Worker `docker compose down` 不影响 Nexus 其他功能。

## 2026-06-12 热修 — 画面不显示 / 连不上

**根因**：Worker `CDPSession` 误用 `wait_for_event`（不存在），screencast 立即崩溃；断线后会话残留导致 `409`。

**修复**：`browser-worker/session_manager.py` 改为 `cdp.on("Page.screencastFrame")` + 队列；`POST /api/browser/sessions` 创建前清理该管理员陈旧会话。

**验证**：主站容器内 WS 测试 `SCREENCAST_OK`（example.com JPEG ~4KB）。