Files

T

Nexus Agent e833b923c8 feat(browser): 远程浏览器 Worker 桥接与顶栏固定悬浮窗

接入 Playwright Worker、会话 WebSocket 与全局浏览器面板（固定于 App Bar 下）；
含验证码 stealth、设置项默认音与 URL 安全校验；附带 worker 部署与设计文档。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-12 06:49:20 +08:00

8.5 KiB

Raw Blame History

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

目标：在单独一台 VPS 上运行 Playwright Chromium，Nexus 主站（api.synaglobal.vip）通过内网 API 桥接，管理员在浮动面板 canvas 操作。
设计：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）：

# 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 分钟）

# 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 交付后）

# 在 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 联调）

# 在 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 联调 继续。

8.5 KiB Raw Blame History Unescape Escape