# 浏览器 Worker 独立服务器 — 采购与部署计划

> **目标**：在**单独一台 VPS** 上运行 Playwright Chromium，Nexus 主站（`api.synaglobal.vip`）通过内网 API 桥接，管理员在浮动面板 canvas 操作。  
> **设计**：[`2026-06-11-server-browser-chromium-design.md`](../specs/2026-06-11-server-browser-chromium-design.md)  
> **状态**：待购机 → 装机 → Nexus 代码联调 → 生产接入

---

## 1. 为什么要单独买一台

| 项 | 全部塞进 Nexus 主站 | **独立 Worker（本计划）** |
|----|---------------------|---------------------------|
| 主站内存 | 每会话 +200～500MB | 主站几乎不增 |
| Docker 镜像 | +300～500MB | 主镜像不变 |
| SSRF 风险面 | 与 API/DB 同机 | 隔离在 Worker |
| 扩缩容 | 和 API 绑死 | 可单独升配 Worker |

你已确认：**任意公网 https + Chromium**；**不要 iframe**。Worker 分离是推荐部署形态。

---

## 2. 购机规格（下单前对照）

### 2.1 最低可用（单人运维、≤2 并发会话）

| 项 | 建议 |
|----|------|
| **CPU** | 2 vCPU（x86_64） |
| **内存** | **4 GB**（Chromium 单会话约 300～800MB，留系统与缓冲） |
| **磁盘** | 40 GB SSD（系统 + Chromium 缓存） |
| **系统** | **Ubuntu 22.04 LTS** 或 **24.04 LTS**（x86_64） |
| **带宽** | ≥ 5 Mbps 出站（画面 JPEG 流；10 Mbps 更稳） |
| **地域** | 与 Nexus 主站**同区域或近区**（降延迟） |

### 2.2 推荐配置（留余量、偶尔双标签）

| 项 | 建议 |
|----|------|
| CPU | 4 vCPU |
| 内存 | **8 GB** |
| 磁盘 | 60 GB SSD |

### 2.3 不建议

- **1 GB / 2 GB 内存** — Chromium 易 OOM，会话被 kill
- **ARM 除非验证 Playwright** — 优先 x86_64，减少兼容问题
- **与 Nexus 主站共用同一台** — 违背隔离目的（若预算极紧可临时同机，不推荐）

### 2.4 厂商与形态

任意支持 **Ubuntu + 公网 IP** 的 VPS 即可（Azure、阿里云、腾讯云、Vultr 等）。  
**不必**买 Windows；Worker 只跑 Linux + Docker。

---

## 3. 网络与安全（购机时一并规划）

### 3.1 拓扑

```
[ 管理员浏览器 ] ──HTTPS──► [ Nexus 主站 20.24.218.235 :443 ]
                                    │
                          内网/VPN/专线（推荐）
                                    ▼
                          [ Browser Worker :8443 ]
                                    │
                                    └──► 任意公网站点
```

### 3.2 防火墙（Worker 上）

| 方向 | 规则 |
|------|------|
| 入站 | **仅允许 Nexus 主站 IP** 访问 Worker 服务端口（默认 `8443/tcp`） |
| 入站 | SSH `22/tcp` 仅你的运维 IP（或跳板机） |
| 入站 | **禁止** 0.0.0.0/0 访问 8443 |
| 出站 | 允许 `80/443` 访问公网（浏览器上网） |
| 出站 | 禁止 Worker 访问 Nexus 内网/MySQL/Redis（Worker 不需要） |

> 若 Nexus 与 Worker **同云厂商同 VPC**，用**内网 IP** 通信，Worker **不要绑公网 8443**。

### 3.3 密钥

购机后生成一对：

- `NEXUS_BROWSER_WORKER_SECRET` — 随机 ≥ 32 字节，Worker 与 Nexus 主站 `.env` **各存一份相同值**
- Worker **不**存 Nexus `SECRET_KEY` / `DATABASE_URL`

---

## 4. 购机后你要收集的信息（交给 Agent 联调）

买好后请记录（可写在本地 `.env` 片段，**勿提交 git**）：

```bash
# Browser Worker（新机器）
BROWSER_WORKER_PUBLIC_IP=          # 若无内网则用
BROWSER_WORKER_PRIVATE_IP=         # 与 Nexus 同 VPC 时优先
BROWSER_WORKER_SSH=user@ip
BROWSER_WORKER_SSH_KEY=/path/to/key.pem

# Nexus 主站侧（deploy/nexus-1panel.secrets.sh 或生产 .env）
NEXUS_BROWSER_ENABLED=1
NEXUS_BROWSER_WORKER_URL=https://<worker-ip-or-internal>:8443
NEXUS_BROWSER_WORKER_SECRET=<与 Worker 相同>
NEXUS_BROWSER_MAX_SESSIONS=2
NEXUS_BROWSER_IDLE_TIMEOUT_SEC=1800
```

并确认：

- [ ] 从 **Nexus 主站** `curl -k https://<worker>:8443/health` 能通（部署 Worker 后）
- [ ] 从 **公网随机 IP** 访问 Worker 8443 **应失败**（防火墙生效）

---

## 5. Worker 机上安装步骤（购机后执行）

> 代码侧将提供 `browser-worker/` 目录与 `docker-compose.worker.yml`；以下为计划步骤，**Agent 实现后按 changelog 为准**。

### Phase A — 基础环境（约 15 分钟）

```bash
# 1. SSH 登录新机器
ssh -i key.pem ubuntu@<WORKER_IP>

# 2. 系统更新 + Docker
sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y ca-certificates curl
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# 重新登录使 docker 组生效

# 3. 防火墙（示例 ufw）
sudo ufw default deny incoming
sudo ufw allow from <NEXUS_MAIN_IP> to any port 8443 proto tcp
sudo ufw allow from <YOUR_OPS_IP> to any port 22 proto tcp
sudo ufw enable
```

### Phase B — 部署 Browser Worker 容器（Agent 交付后）

```bash
# 在 Worker 上
git clone http://66.154.115.8:3000/admin/Nexus.git /opt/nexus-worker
cd /opt/nexus-worker/browser-worker   # 待实现路径
cp .env.example .env
# 编辑 WORKER_SECRET、BIND、日志级别
docker compose up -d --build
docker compose logs -f   # 确认 Chromium 就绪
curl -s http://127.0.0.1:8443/health   # 应返回 ok
```

### Phase C — Nexus 主站接入（Agent 联调）

```bash
# 在 Nexus 主站 .env 增加 NEXUS_BROWSER_* 
# 重启 API：supervisorctl restart nexus 或 docker compose restart nexus
bash scripts/local_verify.sh          # 开发机
# 生产：bash deploy/pre_deploy_check.sh && bash deploy/deploy-production.sh
```

### Phase D — 验收

| # | 检查项 | 通过标准 |
|---|--------|----------|
| 1 | Worker health | `/health` → ok |
| 2 | 公网站点 | 面板打开 `https://example.com` 有画面 |
| 3 | iframe 曾白屏的站 | 能显示（抽 1～2 个已知站） |
| 4 | SSRF | 面板输入 `http://127.0.0.1` → 明确错误，Worker 日志无成功请求 |
| 5 | 隔离 | 未授权 IP 无法连 Worker 8443 |
| 6 | 持久化 | 刷新 Nexus 后标签/收藏仍在（MySQL） |
| 7 | 重启 Worker | Nexus 会话断开可重建，不拖垮主站 |

---

## 6. Nexus 代码实施顺序（与购机并行）

你可**先买服务器**；Agent 在仓库内并行开发，**不阻塞购机**。

| 阶段 | 内容 | 依赖 Worker 机器 |
|------|------|------------------|
| **W1** | `browser-worker/` 独立服务 + Docker + health | 否（本地 Docker 可测） |
| **W2** | SSRF 校验、Playwright screencast、Worker WS 协议 | 否 |
| **W3** | Nexus 主站 `browser_bridge` 桥接 + `/ws/browser` | 否（mock Worker） |
| **W4** | 前端 canvas 替换 iframe | 否 |
| **W5** | 你在 Worker VPS 部署 + 主站 `.env` 联调 | **是** |
| **W6** | changelog、audit、门控、生产部署 | 是 |

**购机前可完成 W1～W4**；**W5 需要你的 Worker IP + SSH**。

---

## 7. Worker 服务接口（预定，实现以代码为准）

Nexus 主站 → Worker（内网，Header `X-Nexus-Worker-Key`）：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 就绪探测 |
| POST | `/v1/sessions` | 创建 `{ session_id, viewport }` |
| DELETE | `/v1/sessions/{id}` | 销毁 |
| WS | `/v1/sessions/{id}/stream` | 双向：帧 + navigate/键鼠 |

管理员浏览器 **只连 Nexus**；不直连 Worker（Worker 不对管理员暴露）。

---

## 8. 预算参考（仅供参考）

| 配置 | 大致月费（国内/海外 VPS） |
|------|---------------------------|
| 2C4G | ¥50～150 / $5～20 |
| 4C8G | ¥100～300 / $15～40 |

另计：出站流量（画面流持续使用时略高于纯 API）。

---

## 9. 购机 Checklist（打印勾选）

**下单前**

- [ ] 2 vCPU + **4 GB RAM** 及以上
- [ ] Ubuntu 22.04/24.04 x86_64
- [ ] 与 Nexus 主站同区域或近区
- [ ] 可配置安全组 / ufw
- [ ] 独立公网 IP 或与 Nexus **同 VPC 内网**

**到手后**

- [ ] SSH 可登录
- [ ] 记录公网 IP / 内网 IP
- [ ] ufw：8443 仅 Nexus 主站 IP
- [ ] 生成 `NEXUS_BROWSER_WORKER_SECRET`
- [ ] 把 §4 信息发给 Agent / 写入本地 secrets
- [ ] 等 `browser-worker/` 合并后执行 Phase B～D

**回滚**

- [ ] 主站 `NEXUS_BROWSER_ENABLED=0` 即关闭，Worker 可关机不影响 Nexus

---

## 10. 与现有文档关系

| 文档 | 关系 |
|------|------|
| `server-browser-chromium-design.md` | 功能与安全 SSOT |
| `server-browser-chromium.md` | Nexus 主站 + 前端实现清单 |
| **本文** | **购机、网络、Worker 装机、联调验收** |

购机完成后，在新会话说：「Worker 已就绪，IP 是 …」并提供 SSH（secrets 本地），Agent 从 **W5 联调** 继续。