# 内置 Web 浏览器 — 设计说明

## 背景与目标

运维需在 Nexus 内快速预览子机站点（域名），不必切换外部浏览器；与终端、文件管理并列的运维入口。

## 方案对比

| 方案 | 优点 | 缺点 |
|------|------|------|
| **iframe 嵌入** | 无后端、实现快、无 SSRF | 部分站点 `X-Frame-Options` 禁止嵌入 |
| HTTP 反向代理 | 可绕过 frame 限制 | SSRF 风险、需维护代理与 Cookie |
| 仅外链新标签 | 零风险 | 非「内置」 |

**选定（2026-06-11 前）**：iframe + 地址栏 + 新标签兜底；首版不做 HTTP 代理。

> **2026-06-11 变更**：用户拒绝 iframe 方案，改为 **服务端 Playwright Chromium + WebSocket 画面流**。  
> 见 [2026-06-11-server-browser-chromium-design.md](./2026-06-11-server-browser-chromium-design.md)。  
> 本文档仍有效部分：路由入口、URL 白名单原则、UI 状态 API；**iframe 渲染已废弃**。

## 接口与路由

- 前端 `#/browser?url=https://example.com`
- 服务器列表「站点」→ 带 `url`（由 `domain` 推导 `https://{host}`，不含 SSH 端口）

## 安全

- 仅允许 `http:` / `https:`；拒绝 `javascript:`、`data:`、凭据 URL
- iframe `sandbox`：`allow-scripts allow-same-origin allow-forms allow-popups allow-downloads`
- 无后端 fetch，不引入 SSRF
- 不记录浏览审计（被动预览，非 CUD）

## 验收

- [x] 全局浮动面板、最小化可拖、不可关闭（见 global-floating-browser changelog）
- [ ] 侧栏「浏览器」或左下角入口打开浮动窗
- [ ] 地址栏输入 URL 可导航；刷新 / 新标签打开
- [ ] 服务器列表「站点」跳转并加载域名
- [ ] 非法 URL 拒绝并提示
- [ ] **网站导航（收藏）** — 见 [browser-nav-bookmarks-design.md](./2026-06-11-browser-nav-bookmarks-design.md)
