内容
<p align="center">
<img src="https://raw.githubusercontent.com/browser-gateway/browser-gateway/main/docs/assets/logo.png" alt="browser-gateway" width="120" />
</p>
<h1 align="center">浏览器网关</h1>
<p align="center">
<strong>浏览器的开放路由器。</strong>
<br />
一个可以跨多个浏览器提供商路由的端点：自动故障转移、持久化配置文件、会话重放、REST API、MCP 服务器、仪表盘。
<br />
与 Puppeteer、Playwright、Stagehand、browser-use 和任何 MCP 客户端无缝协作。
</p>
<p align="center">
<a href="https://www.npmjs.com/package/browser-gateway"><img src="https://img.shields.io/npm/v/browser-gateway?style=flat-square&logo=npm&logoColor=white" alt="npm version" /></a>
<a href="https://www.npmjs.com/package/browser-gateway"><img src="https://img.shields.io/npm/dm/browser-gateway?style=flat-square&label=downloads" alt="npm downloads" /></a>
<a href="./LICENSE"><img src="https://img.shields.io/npm/l/browser-gateway?style=flat-square" alt="MIT license" /></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/node/v/browser-gateway?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js" /></a>
<a href="https://github.com/browser-gateway/browser-gateway"><img src="https://img.shields.io/github/stars/browser-gateway/browser-gateway?style=flat-square&logo=github&logoColor=white" alt="GitHub stars" /></a>
</p>
<p align="center">
<a href="https://railway.com/new/template/browser-gateway?utm_medium=integration&utm_source=button&utm_campaign=browser-gateway"><img src="https://railway.com/button.svg" alt="Deploy on Railway" height="32" /></a>
<a href="https://render.com/deploy?repo=https://github.com/browser-gateway/browser-gateway"><img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render" height="32" /></a>
<a href="https://cloud.digitalocean.com/apps/new?repo=https://github.com/browser-gateway/browser-gateway/tree/main"><img src="https://www.deploytodo.com/do-btn-blue.svg" alt="Deploy to DigitalOcean" height="32" /></a>
<a href="https://app.koyeb.com/deploy?type=docker&name=browser-gateway&image=ghcr.io/browser-gateway/server:latest&ports=9500;http;/&env%5BBG_DATA_DIR%5D=/data"><img src="https://www.koyeb.com/static/images/deploy/button.svg" alt="Deploy to Koyeb" height="32" /></a>
</p>
<p align="center">
<a href="https://browsergateway.com">官网</a>
·
<a href="https://docs.browsergateway.com/quickstart">快速开始</a>
·
<a href="https://docs.browsergateway.com/mcp">MCP</a>
·
<a href="https://docs.browsergateway.com/profiles">配置文件</a>
·
<a href="https://docs.browsergateway.com/replays">会话重放</a>
·
<a href="https://docs.browsergateway.com/rest-api">REST API</a>
·
<a href="https://docs.browsergateway.com/dashboard">仪表盘</a>
</p>
<p align="center">
<img src="https://raw.githubusercontent.com/browser-gateway/browser-gateway/main/docs/assets/routing.gif" alt="browser-gateway routes traffic across multiple browser providers, filling them by priority and failing over when one is saturated" width="720" />
</p>
---
## 概述
一个端点，多个提供商，在一个提供商饱和或宕机时自动故障转移。
您的应用程序连接到 `ws://gateway:9500/v1/connect`。网关根据健康状况、容量和路由策略选择最佳的可用提供商。提供商可以是云 CDP 服务、Docker 容器或本地 Chrome 实例。
---
## 仪表盘
每个安装都附带一个网页仪表盘。在启动网关后，打开 `http://localhost:9500/web`。
**概述。** 活动会话、队列深度、提供商健康状况、连接端点，以及 Puppeteer、Playwright、Stagehand、browser-use 和原始 CDP 的一键式快速入门。
<p align="center">
<img src="https://raw.githubusercontent.com/browser-gateway/browser-gateway/main/docs/assets/overview.png" alt="Dashboard overview page showing active sessions, queue depth, provider health, masked connection endpoint, and a tabbed quickstart with Puppeteer code" width="860" />
</p>
**REST API。** 从表单驱动的 UI 运行截图、内容提取和结构化抓取端点，支持配置文件选择和参数引用。
<p align="center">
<img src="https://raw.githubusercontent.com/browser-gateway/browser-gateway/main/docs/assets/api.png" alt="REST API page in the dashboard with three tabs (screenshot, content, scrape) and a form to capture a screenshot of a target URL with format and profile options" width="860" />
</p>
**游乐场。** 直接在浏览器中驱动任何提供商。选择提供商和配置文件，在画布中输入并实时查看远程会话。
<p align="center">
<img src="https://raw.githubusercontent.com/browser-gateway/browser-gateway/main/docs/assets/playground.jpg" alt="Live playground page streaming a remote Chrome session showing yahoo.com loaded inside the dashboard canvas" width="860" />
</p>
---
## 功能
### 路由和可靠性
- **自动故障转移** - 当一个提供商失败时，下一个提供商立即接管，无需客户端更改
- **五种负载均衡策略** - 优先级链、轮询、最少连接、延迟优化、加权
- **每个提供商的并发限制** - 网关在每个后端强制执行 `maxConcurrent`
- **请求队列** - 当所有提供商都饱和时，连接等待而不是立即失败
- **冷却** - 失败的提供商被跳过，并在 TTL 后自动恢复
- **健康检查** - 定期连接探测标记提供商不健康，客户端在探测到之前不会受到影响
- **优雅关闭** - 活动会话在 SIGTERM 和 SIGINT 上干净地耗尽
- **会话重新连接** - 断开的客户端使用相同的提供商和 cookies 以及页面状态恢复
- **Webhook** - 在提供商宕机、恢复和队列溢出事件上触发
### REST API
- **截图** - `POST /v1/screenshot` 返回任何 URL 作为 PNG 或 JPEG，全页或限定为选择器
- **内容提取** - `POST /v1/content` 返回 markdown、纯文本、HTML 或清理的文章
- **抓取** - `POST /v1/scrape` 通过 CSS 选择器或全页格式提取结构化数据
- **连接池会话** - 浏览器连接在请求之间重复使用，如数据库连接池
- **自动重试** - 失败的请求会重试以获取新的页面
### 配置文件 — 持久化浏览器状态
- **跨会话存活** - cookie、`localStorage`、`sessionStorage` 和 `IndexedDB` 在断开连接时捕获，并在具有相同 ID 的下一个连接时重放
- **一键式启用** - 在 WebSocket URL 中添加 `?profile=acme`，其余部分是自动的
- **静止加密** - 使用 AES-256-GCM 加密，具有信封加密、反交换绑定和 scrypt 派生的 KEK
- **提供商无关** - 状态在 CDP 级别捕获，因此它可以与任何提供商一起重放
- **每个配置文件的锁定** - 对同一 ID 的并发连接返回 HTTP 409 以防止损坏
- **导出和导入** - 加密的 `.bgp` 数据块可在网关安装之间移植
- **一键式启用** - 仪表盘向导在浏览器中生成一个强密钥并将其写入配置文件
查看 [配置文件文档](https://docs.browsergateway.com/profiles) 以获取完整指南、安全模型、REST 端点和限制。
### 会话重放 — 查看代理看到的内容
- **帧准确的视觉记录** - 每个路由会话的视觉记录，通过 CDP `Page.startScreencast` 捕获
- **零注入** - 没有脚本在客户页面中运行，捕获完全独立于页面
- **提供商无关** - 与任何支持页面屏幕截图的后端配合使用
- **仪表盘播放器** - 遍历记录的帧，切换捕获的浏览器目标
- **保留控制** - 可配置的范围、每个会话的字节上限、每日清理
查看 [重放文档](https://docs.browsergateway.com/replays) 以获取存储布局、REST 端点和调优旋钮。
### 用于 AI 代理的 MCP 服务器
- **八种浏览器工具** - 导航、快照、截图、视口、交互、评估、关闭、状态
- **零配置** - 自动检测 Chrome 并在首次使用工具时启动
- **并发会话** - 每个代理都有自己的浏览器，无共享状态
- **原始 CDP** - 无 Playwright 或 Puppeteer 依赖
- **兼容** - Claude Code、Cursor 和任何 MCP 兼容的客户端
### 管理
- **仪表盘** - 从浏览器管理提供商、查看会话和编辑配置
- **提供商 CRUD** - 从仪表盘或 API 添加、编辑、删除和测试提供商
- **配置编辑器** - 在浏览器中编辑 `gateway.yml`，具有语法高亮和验证
- **身份验证** - 基于令牌，具有用于仪表盘的安全 HttpOnly cookie
- **协议无关** - 与 Playwright、Puppeteer 和任何 WebSocket 协议配合使用
---
## 快速开始
### 作为 WebSocket 代理（适用于应用程序）
```bash
npm install -g browser-gateway
```
创建 `gateway.yml`:
```yaml
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
```
```bash
browser-gateway serve
```
从您的应用程序连接：
```typescript
// 适用于 CDP 提供商
const browser = await chromium.connectOverCDP('ws://localhost:9500/v1/connect');
// 适用于 Playwright run-server 提供商
const browser = await chromium.connect('ws://localhost:9500/v1/connect');
```
或者使用 REST API - 无需 WebSocket 管理：
```bash
# 截图
curl -X POST http://localhost:9500/v1/screenshot \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}' --output screenshot.png
# 提取内容为 markdown
curl -X POST http://localhost:9500/v1/content \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com", "formats": ["markdown"]}'
```
在 `http://localhost:9500/web` 访问仪表盘。
### 作为 MCP 服务器（适用于 AI 代理）
将以下内容添加到您的 Claude Code 或 Cursor 配置中：
```json
{
"mcpServers": {
"browser-gateway": {
"command": "npx",
"args": ["browser-gateway", "mcp"]
}
}
}
```
无需配置文件。代理通过网关的路由层为 navigate、snapshot、screenshot、click、type 和 evaluate 工具提供访问权限。
查看 [MCP 文档](https://docs.browsergateway.com/mcp) 以获取所有选项。
---
## 身份验证
设置 `BG_TOKEN` 以要求令牌（或将其放入 `.env` 文件）：
```bash
BG_TOKEN=my-secret-token browser-gateway serve
```
- **WebSocket 客户端** 通过 `?token=` 查询参数传递令牌
- **API 客户端** 使用 `Authorization: Bearer <token>` 头部
- **仪表盘** 显示登录表单，设置安全的 HttpOnly cookie
- **健康端点** (`/health`) 始终是公开的
---
## CLI
```bash
# 代理服务器
browser-gateway serve # 启动网关 + 仪表盘
browser-gateway serve --port 8080 # 自定义端口
browser-gateway serve --config path.yml # 自定义配置
# 用于 AI 代理的 MCP 服务器
browser-gateway mcp # 自动检测 Chrome，零配置
browser-gateway mcp --headless # 无头模式（适用于 CI/Docker）
browser-gateway mcp --cdp-endpoint ws:// # 连接到现有浏览器
browser-gateway mcp --config gateway.yml # 多提供商，故障转移
# 实用工具
browser-gateway check # 测试提供商连接
browser-gateway version # 打印版本
browser-gateway help # 显示帮助
```
---
## API
| 端点 | 方法 | 描述 |
|----------|--------|-------------|
| `/v1/connect` | WebSocket | 连接到浏览器（核心功能） |
| `/v1/screenshot` | POST | 拍摄任何 URL 的截图（[文档](https://docs.browsergateway.com/rest-api)) |
| `/v1/content` | POST | 提取页面的内容为 markdown、text 或 HTML（[文档](https://docs.browsergateway.com/rest-api)) |
| `/v1/scrape` | POST | 通过 CSS 选择器或全页格式提取数据（[文档](https://docs.browsergateway.com/rest-api)) |
| `/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 流式 HTTP 端点 |
| `/json/version` | GET | CDP 发现（browser-use、Playwright、Stagehand） |
| `/health` | GET | 健康检查 |
---
## Docker
推荐：Docker Compose。捆绑的 `docker-compose.yml` 挂载一个命名卷用于状态和一个只读的 `gateway.yml` 来自主机。
```bash
# 将 gateway.yml 放在 docker-compose.yml 旁边，然后：
docker compose up -d
```
纯 `docker run`:
```bash
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` 作为一个卷保留每个子系统持久化，无需后续配置更改。
### 升级
状态存在于卷中，代码存在于镜像中。拉取新镜像，重建容器 - 无数据丢失：
```bash
docker compose pull
docker compose up -d
```
容器读取相同的 `BG_DATA_DIR` 和相同的 `gateway.yml`。配置文件块是版本化的，网关读取旧格式透明地。
### 镜像标签
| 标签 | 更新于 |
|---|---|
| `:0.3.0`（和后续版本） | 发布后手动发布 |
| `:latest` | 始终指向最新版本 |
镜像是多架构（`linux/amd64`、`linux/arm64`）、使用 [Sigstore](https://www.sigstore.dev/) 的构建证明，并附带 SBOM。验证 [GitHub CLI](https://cli.github.com/):
```bash
gh attestation verify oci://ghcr.io/browser-gateway/server:0.3.0 \
--repo browser-gateway/browser-gateway
```
---
## 它如何工作
1. 客户端连接到 `ws://localhost:9500/v1/connect`
2. 网关使用您的路由策略选择提供商
3. 网关打开与提供商的原始 TCP 连接
4. HTTP 升级转发，提供商响应 `101 Switching Protocols`
5. 双向 TCP 管道：`client <-> gateway <-> provider`
6. 断开连接时：清理会话，释放插槽，更新指标
7. 如果所有提供商都已满载：连接 [等待队列](https://docs.browsergateway.com/operating/queue) 直到插槽打开
---
## 兼容
browser-gateway 与现有的浏览器工具兼容。只需传递网关 URL - 它会自动通过 `/json/version` 解析。
**AI 代理框架：
```python
# browser-use（Python）- HTTP URL 自动解析
BrowserSession(cdp_url="http://localhost:9500")
```
```typescript
// Stagehand（TypeScript）
new Stagehand({ env: "LOCAL", localBrowserLaunchOptions: { cdpUrl: "http://localhost:9500" } })
```
**Playwright MCP**（所有 70 个 Playwright 工具通过网关路由）：
```json
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--cdp-endpoint", "http://localhost:9500"]
}
}
}
```
**Puppeteer / Playwright：
```typescript
// Playwright - HTTP 或 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](https://docs.browsergateway.com)**。
- [开始使用](https://docs.browsergateway.com/quickstart)
- [配置参考](https://docs.browsergateway.com/configuration)
- [支持的提供商](https://docs.browsergateway.com/providers)
- [配置文件 - 持久化浏览器状态](https://docs.browsergateway.com/profiles)
- [会话重放](https://docs.browsergateway.com/replays)
- [会话生命周期](https://docs.browsergateway.com/sessions)
- [REST API](https://docs.browsergateway.com/rest-api)
- [MCP 服务器用于 AI 代理](https://docs.browsergateway.com/mcp)
- [CLI 参考](https://docs.browsergateway.com/cli)
- [网页仪表盘](https://docs.browsergateway.com/dashboard)
- [故障转移工作原理](https://docs.browsergateway.com/operating/failover)
- [负载均衡策略](https://docs.browsergateway.com/operating/load-balancing)
- [请求队列](https://docs.browsergateway.com/operating/queue)
- [Webhook](https://docs.browsergateway.com/operating/webhooks)
- [Docker 部署](https://docs.browsergateway.com/operating/docker)
- [集成](https://docs.browsergateway.com/operating/integrations) - Playwright、Puppeteer、browser-use、Stagehand、Playwright MCP
---
## 贡献
欢迎贡献。有关指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT - 请参阅 [LICENSE](LICENSE)。
## 链接
- [browsergateway.com](https://browsergateway.com)
- [GitHub](https://github.com/browser-gateway/browser-gateway)
- [npm](https://www.npmjs.com/package/browser-gateway)
<small>由 <a href="https://monostellar.com">Monostellar Labs</a> 维护。</small>
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器