browser-gateway

browser-gateway

面向云端浏览器的开放路由器。
通过一个端点路由至你使用的所有浏览器提供商：自动故障转移、持久化配置文件、会话回放、REST API、MCP 服务和控制面板。
无需任何改动，即可与 Puppeteer、Playwright、Stagehand、browser-use 和任何 MCP 客户端配合使用。

     

网站  ·  快速入门  ·  MCP  ·  配置文件  ·  回放  ·  REST API  ·  控制面板  ·  Discord

---

概述

一个端点，多个提供商。当某个提供商达到容量上限或不可用时，自动故障转移。

你的应用连接到 ws://gateway:9500/v1/connect。网关会根据健康状况、容量和你的路由策略，选择最佳可用提供商。提供商可以是云端 CDP 服务、Docker 容器或本地 Chrome 实例。

---

仪表板

每次安装都会附带一个 Web 仪表板。启动网关后，打开 http://localhost:9500/web。

概览。 查看活动会话、队列深度、提供商健康状态、连接端点，以及适用于 Puppeteer、Playwright、Stagehand、browser-use 和原始 CDP 的复制粘贴式快速入门。

REST API。 通过表单驱动的界面调用截图、内容提取和结构化抓取端点，并可直接查看配置文件选择和参数参考。

Playground。 在浏览器中实时驱动任意提供商。选择提供商和配置文件，像使用本地浏览器一样在画布中输入，并实时查看远程会话。

---

功能

路由与可靠性

• 自动故障转移 - 某个提供商发生故障时，下一个提供商会立即接管，无需更改客户端
• 五种负载均衡策略 - 优先级链、轮询、最少连接数、延迟优化、加权
• 按提供商设置并发限制 - 网关会在每个后端强制执行 maxConcurrent
• 请求队列 - 当所有提供商都已饱和时，连接会等待，而不是立即失败
• 冷却机制 - 跳过发生故障的提供商，并在 TTL 后自动恢复
• 健康检查 - 定期探测连接状态，在客户端连接之前将不健康的提供商标记出来
• 平滑关闭 - 收到 SIGTERM 和 SIGINT 时，让活动会话正常结束
• 会话重连 - 客户端断开连接后，可通过 ?sessionId=<X-Session-Id> 重新连接；对于会发放恢复令牌的提供商（启用了恢复窗口的 browserserve），会恢复同一个浏览器及其页面、Cookie 和存储；否则，会在同一提供商上启动一个新浏览器
• Webhooks - 在提供商离线、恢复以及队列溢出事件发生时触发

REST API

• 截图 - POST /v1/screenshot 将任意 URL 截取为 PNG 或 JPEG，可截取整页，也可限定到某个选择器
• 内容提取 - POST /v1/content 返回 Markdown、纯文本、HTML 或经过清理的文章
• 抓取 - POST /v1/scrape 通过 CSS 选择器或整页格式提取结构化数据
• 会话池 - 在多个请求间复用浏览器连接，类似数据库连接池
• 自动重试 - 请求失败时，在新页面上重试

Profiles — 持久化浏览器状态

• 跨会话保留 - 离开每个页面以及断开连接时都会捕获 cookies 和 localStorage，并在下次使用相同 id 连接时恢复（browserserve 还支持 IndexedDB）
• 可由任意提供方保存 - 每个提供方都能加载和保存任意配置文件；只有将某个提供方固定到一个配置文件，才能将该配置文件的会话路由到该提供方
• 配置文件绝不混用 - 仍保留其他配置文件的浏览器会被拒绝。复用的浏览器中其他已有内容（来自未使用配置文件的会话）会与该配置文件一并保存
• 一行即可启用 - 在 WebSocket URL 中添加 ?profile=acme，其余操作会自动完成
• 静态加密 - 使用 AES-256-GCM 信封加密、防调包绑定，以及通过 scrypt 派生的 KEK
• 与提供方无关 - 状态在 CDP 层捕获，因此可在任意提供方上恢复
• 按配置文件锁定 - 并发连接到同一 id 时会返回 HTTP 409，以防数据损坏
• 导出和导入 - 加密的 .bgp 文件可在不同网关安装之间移植
• 一键启用 - 仪表板向导会在浏览器中生成强密钥并将其写入配置

完整指南、安全模型、REST 端点和限制请参阅 Profiles 文档。

会话回放 — 查看 Agent 看到的内容

• 帧级精确的视觉记录，通过 CDP Page.startScreencast 捕获每个路由会话
• 零注入 - 不会在客户页面中运行脚本，捕获完全在带外进行
• 与提供方无关 - 适用于任何支持页面录制的后端
• 仪表板播放器 - 浏览录制的帧，并在捕获的浏览器目标之间切换
• 保留控制 - 可配置保留期限、单个会话的字节上限和每日清理

存储布局、REST 端点和调优选项请参阅 Replays 文档。

面向 AI Agent 的 MCP 服务

• 单次调用工具 - fetch_page 可将任意 url 读取为 markdown，screenshot_page 可截取页面；每个工具都通过一次调用自行启动并关闭浏览器
• 会话工具 - browser_session、browser_navigate、browser_snapshot、browser_act、browser_extract、browser_screenshot、browser_wait、browser_tabs、browser_evaluate、browser_observe，用于登录、填写表单和多步骤操作
• 为编码 Agent 提供回退方案 - 内置网页抓取受阻、返回空内容或需要 JavaScript 时，Claude Code 插件会让 Claude 改用 fetch_page（/plugin marketplace add browser-gateway/browser-gateway）；Codex、Cursor 和 Gemini CLI 的设置说明见 plugins/browser-gateway
• 零配置 - 自动检测 Chrome，并在首次使用工具时启动
• 并发会话 - 每个 Agent 都有自己的浏览器，状态互不共享
• 原生 CDP - 不依赖 Playwright 或 Puppeteer
• 兼容性 - 兼容 Claude Code、Cursor 和任何兼容 MCP 的客户端

为 Claude 和 Gemini 提供计算机使用能力

• 模型可在任意浏览器中使用自身的浏览器工具 - 可通过网关在任意提供方上运行 Claude 的浏览器和计算机使用工具，以及 Gemini 计算机使用功能
• 约十行代码 - runClaudeLoop / runGeminiLoop 接收你自己的模型调用，并处理操作、截图和结果
• 安全默认设置 - 仅允许 http 和 https，阻止私有网络，可选网站允许列表，并提供 Gemini 针对高风险操作的确认步骤
• 无需额外依赖 - browser-gateway/agent-tools/computer-use，已在 Node.js、Bun、Deno 和 Cloudflare Workers 运行时上测试

管理

• 仪表板 - 在浏览器中管理提供方、查看会话和编辑配置
• 提供方 CRUD - 可通过仪表板或 API 添加、编辑、删除和测试提供方
• 配置编辑器 - 在浏览器中编辑 gateway.yml，支持语法高亮和验证
• 身份验证 - 基于令牌，并为仪表板使用安全的 HttpOnly Cookie
• 协议无关 - 适用于 Playwright、Puppeteer 和任意 WebSocket 协议

---

快速开始

作为 WebSocket 代理（供应用程序使用）

npm install -g browser-gateway

创建 gateway.yml：

version: 1

providers:
  primary:
    url: wss://provider.example.com?token=${PROVIDER_TOKEN}
    limits:
      maxConcurrent: 5
    priority: 1

  fallback:
    url: ws://my-playwright-server:4000
    limits:
      maxConcurrent: 10
    priority: 2

browser-gateway serve

从应用程序连接：

// For CDP providers
const browser = await chromium.connectOverCDP('ws://localhost:9500/v1/connect');

// For Playwright run-server providers
const browser = await chromium.connect('ws://localhost:9500/v1/connect');

也可以使用 REST API，无需管理 WebSocket：

# Screenshot
curl -X POST http://localhost:9500/v1/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}' --output screenshot.png

# Extract content as markdown
curl -X POST http://localhost:9500/v1/content \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}'

这些端点仅接受公共主机上的 http 和 https URL。回环、链路本地和私有范围地址会被拒绝，并且主机名会被解析并重新检查。若要访问内部主机，请在 gateway.yml 的 rest.allowedPrivateHosts 下列出该主机。

控制面板位于 http://localhost:9500/web。

作为 MCP 服务（供 AI Agent 使用）

添加到 Claude Code 或 Cursor 配置中：

{
  "mcpServers": {
    "browser-gateway": {
      "command": "npx",
      "args": ["browser-gateway", "mcp"]
    }
  }
}

无需配置文件。Agent 可通过网关的路由层使用 navigate、snapshot、screenshot、click、type 和 evaluate 工具。

有关所有选项，请参阅 MCP 文档。

---

身份验证

设置 BG_TOKEN 以要求提供令牌（或将其放入 .env 文件）：

BG_TOKEN=my-secret-token browser-gateway serve

• WebSocket 客户端通过 ?token= 查询参数传递令牌
• API 客户端使用 Authorization: Bearer <token> 标头
• 控制面板会显示登录表单，并设置安全的 HttpOnly Cookie
• 健康检查端点（/health）始终公开

未设置 BG_TOKEN 时，所有 /v1/* 路由都无需身份验证，因此网关会绑定到 127.0.0.1，而非所有网络接口。设置令牌（或显式设置 HOST）即可为其他机器提供服务。未设置令牌时，BG_ALLOWED_HOSTS 可允许 /mcp 使用其他 Host 值。

---

CLI

# Proxy server
browser-gateway serve                    # Start the gateway + dashboard
browser-gateway serve --port 8080        # Custom port
browser-gateway serve --config path.yml  # Custom config

# MCP server for AI agents
browser-gateway mcp                      # Auto-detect Chrome, zero config
browser-gateway mcp --headless           # Headless mode (for CI/Docker)
browser-gateway mcp --cdp-endpoint ws:// # Connect to existing browser
browser-gateway mcp --config gateway.yml # Multi-provider with failover

# Utilities
browser-gateway check                    # Test provider connectivity
browser-gateway version                  # Print version
browser-gateway help                     # Show help

---

API

端点	方法	描述
/v1/connect	WebSocket	连接到浏览器（核心功能）
/v1/screenshot	POST	对任意 URL 截图（文档）
/v1/content	POST	将页面内容提取为 Markdown、文本或 HTML（文档）
/v1/scrape	POST	通过 CSS 选择器或整页格式提取数据（文档）
/v1/status	GET	网关健康状态 + 提供方状态 + 池状态
/v1/sessions	GET	活动会话
/v1/providers	GET/POST	列出或添加提供方
/v1/providers/:id	PUT/DELETE	更新或移除提供方
/v1/providers/:id/test	POST	测试提供方连通性
/v1/config	GET/PUT	读取或保存配置
/v1/config/validate	POST	验证 YAML，但不保存
/mcp	POST	MCP Streamable HTTP 端点
/json/version	GET	CDP 发现（供 browser-use、Playwright、Stagehand 使用）
/health	GET	健康检查

---

Docker

推荐使用 Docker Compose。随附的 docker-compose.yml 会为状态挂载一个命名卷，并从主机以只读方式挂载 gateway.yml。

# Drop your gateway.yml next to docker-compose.yml, then:
docker compose up -d

普通的 docker run：

docker run -d \
  -p 9500:9500 \
  -v bg_data:/data \
  -v ./gateway.yml:/app/gateway.yml:ro \
  -e PROVIDER_TOKEN=xxx \
  ghcr.io/browser-gateway/server:latest

持久化

网关写入磁盘的所有内容都位于单个目录 BG_DATA_DIR 下（在镜像中默认为 /data）。将其挂载为命名卷或绑定挂载，即可在容器重启和镜像升级后保留所有状态。目前其中包含：

• profiles/ — 加密的配置文件数据块（启用配置文件时）

未来版本可能会在同一根目录下添加更多子目录（冷却状态、会话快照、捕获内容）。将 BG_DATA_DIR 挂载为一个卷，即可持久保存所有子系统的数据，无需后续更改配置。

升级

状态保存在卷中，代码保存在镜像中。拉取新镜像并重新创建容器即可，不会丢失数据：

docker compose pull
docker compose up -d

容器会读取相同的 BG_DATA_DIR 和 gateway.yml。配置文件数据块带有版本信息，网关能够透明读取旧格式。

镜像标签

标签	更新时机
:0.3.0（以及后续每个版本）	发布后手动推送
:latest	始终指向最新版本

镜像支持多种架构（linux/amd64、linux/arm64），使用 Sigstore 构建来源证明签名，并附带 SBOM。使用 GitHub CLI 验证：

gh attestation verify oci://ghcr.io/browser-gateway/server:0.3.0 \
  --repo browser-gateway/browser-gateway

---

工作原理

不使用配置文件／录制／可观测性功能的会话（默认）会走字节管道快速通道：

1. 客户端连接到 ws://gateway:9500/v1/connect
2. Gateway 根据你的路由策略选择提供方
3. Gateway 与提供方建立原始 TCP 连接
4. 转发 HTTP 升级请求，提供方返回 101 Switching Protocols
5. 双向 TCP 管道：client <-> gateway <-> provider
6. 透明转发所有 WebSocket 消息（绝不解析或修改）
7. 断开连接时：清理会话、释放槽位、更新指标
8. 如果所有提供方都已满：连接会在队列中等待，直到有槽位可用

使用配置文件注入、会话录制、实时视图或可观测性功能的会话（例如 ?profile=X、?session_record=true、/v1/live）则会通过支持 CDP 的管道运行：每个会话使用一个 WebSocket，由 N 个插件监视线路。路由和故障转移方式相同；空闲时逐字节透传，仅在请求相应功能时才会触发插件。架构和插件编写指南：docs/PIPELINE.md。

---

自托管提供方：browserserve

browserserve 是此技术栈自有的自托管浏览器服务：一个容器即可通过 CDP 分发相互隔离的 Chrome 会话。像添加其他提供方一样添加它：

providers:
  browserserve:
    url: ws://your-host:9222
  cloud-provider:
    url: <websocket-url-with-auth>
    priority: 2

由于 Gateway 控制该运行环境，browserserve 提供方会被自动检测，并解锁外部提供方不具备的两项功能：

• 自动容量。 无需设置 maxConcurrent。browserserve 会检测其主机的资源限制（内存、线程和 CPU），并公布安全上限，Gateway 会采用该上限。仪表板会将其显示为 (auto)。
• 完整配置文件。 每个会话都会启动一个全新的浏览器，保存的配置文件会保留完整的浏览器状态，包括 IndexedDB 和 service worker。其他提供方只会保存 Cookie 和站点存储数据。

一种常见的配置方式是：在自有硬件上将 browserserve 设为主提供方，并将云提供方设为较低优先级，以便故障转移。

---

兼容工具

browser-gateway 兼容现有的浏览器工具。只需传入 Gateway URL——它会通过 /json/version 自动解析。

AI Agent 框架：

# browser-use (Python) — HTTP URL auto-resolves
BrowserSession(cdp_url="http://localhost:9500")

// Stagehand (TypeScript)
new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { cdpUrl: "http://localhost:9500" } })

Playwright MCP（通过 Gateway 路由调用全部 70 个 Playwright 工具）：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--cdp-endpoint", "http://localhost:9500"]
    }
  }
}

Puppeteer / Playwright：

// Playwright — HTTP or WebSocket
const browser = await chromium.connectOverCDP("http://localhost:9500");

// Puppeteer — WebSocket
const browser = await puppeteer.connect({ browserWSEndpoint: "ws://localhost:9500/v1/connect" });

---

文档

完整文档请访问 docs.browsergateway.com。

• 快速入门
• 配置参考
• 支持的提供方
• 配置文件 — 持久化浏览器状态
• 会话回放
• 会话生命周期
• REST API
• 面向 AI Agent 的 MCP 服务
• 计算机使用（Claude 和 Gemini）
• CLI 参考
• Web 仪表板
• 故障转移原理
• 负载均衡策略
• 请求队列
• Webhooks
• Docker 部署
• 集成 — Playwright、Puppeteer、browser-use、Stagehand、Playwright MCP

---

贡献

欢迎贡献。请参阅 CONTRIBUTING.md 了解指南。

许可证

MIT — 请参阅 LICENSE。

链接

• browsergateway.com
• docs.browsergateway.com
• GitHub
• npm

联系方式

如有疑问、安全问题报告或合作咨询，请联系：[email protected]。