BlitzBrowser

BlitzBrowser是一款开源无头浏览器管理项目，核心价值在于将各类浏览器封装进Docker容器中，实现便捷的部署、运行与管理，支持本地或云端部署，同时兼容Chrome DevTools协议（CDP）。

对于开发者而言，手动管理浏览器往往会面临诸多棘手问题：内存泄漏、僵尸进程残留、运维配置繁琐、多实例并行难实现等，这些问题会大量占用开发精力，影响项目推进。而BlitzBrowser恰好能包揽所有与浏览器部署、扩展相关的繁琐工作，让开发者无需关注底层基础设施，专心聚焦核心业务代码的编写与优化。

此外，BlitzBrowser支持通过Puppeteer、Playwright等主流框架进行交互，还提供S3用户数据存储、HTTP代理连接等实用功能，满足自动化测试、网页爬取、自动化操作等多场景需求。

核心功能特性：高效、便捷、无需运维

BlitzBrowser的功能围绕“简化浏览器管理、提升开发效率”展开，核心特性覆盖多场景使用需求，具体如下：

1. 并行处理能力：支持同时启动并运行多个浏览器实例，无需逐个手动部署，大幅提升批量处理任务（如批量网页测试、批量数据爬取）的效率，满足高并发场景需求。
2. 原生兼容CDP协议：无需依赖专用SDK，可直接通过Puppeteer、Playwright或任何支持Chrome DevTools协议的框架连接浏览器，降低学习与接入成本，适配开发者已有技术栈。
3. 图形界面（GUI）模式支持：除了无头运行模式，还支持以GUI形式运行浏览器，既能绕过部分网站的机器人检测机制，又能完全按照普通用户所见的界面进行页面渲染，方便开发者调试与验证效果。
4. 持久化会话存储：集成S3存储功能，可将浏览器的用户数据（如登录状态、缓存、配置偏好等）持久化保存，下次连接时可直接复用，无需重复配置，提升会话连续性。
5. 灵活HTTP代理支持：可将浏览器与任意HTTP代理服务器连接，轻松实现IP切换、区域模拟等需求，适配需要规避IP限制的场景。
6. 自动队列管理：当多个CDP连接请求同时抵达，而浏览器尚未完成启动时，系统会自动将连接请求排队等待，避免请求拥堵或失败，保障服务稳定性。
7. 零运维负担：所有浏览器运行相关的基础设施管理、僵尸进程清理、异常恢复等工作，均由Docker容器自动处理，开发者无需编写自定义运维脚本，也无需关注底层细节。

快速上手：几秒完成部署，两种方式可选

BlitzBrowser的核心优势之一是“开箱即用”，基于Docker生态，只需简单几步即可完成部署，支持纯Docker运行与Docker Compose运行两种方式，满足不同使用场景。

前置准备

提前在本地或服务器安装Docker（推荐最新稳定版），若使用Docker Compose方式，需额外安装Docker Compose。

方式1：纯Docker快速启动

这是最简单的部署方式，适合快速测试功能，无需复杂配置，执行以下命令即可：

# 拉取最新镜像并启动容器，映射9999端口，分配2G共享内存
docker run -p=9999:9999 --shm-size=2g ghcr.io/blitzbrowser/blitzbrowser:latest

• 说明：--shm-size=2g 是为浏览器分配2G共享内存，避免因内存不足导致浏览器崩溃，可根据实际需求调整内存大小。
• 启动成功后，浏览器服务将监听本地9999端口，可直接通过CDP协议连接使用。

方式2：Docker Compose启动（推荐生产环境）

Docker Compose方式支持配置持久化、自动重启等功能，更适合长期运行或生产环境，配置文件如下：

services:
  blitzbrowser:
    image: ghcr.io/blitzbrowser/blitzbrowser:latest # 拉取最新BlitzBrowser镜像
    ports:
      - "9999:9999" # 端口映射：主机9999端口 -> 容器9999端口
    shm_size: "2gb" # 分配2G共享内存
    restart: always # 容器异常退出时自动重启，保障服务可用性

将上述配置保存为docker-compose.yml，在文件所在目录执行以下命令启动：

# 后台启动容器
docker-compose up -d

方式3：Docker Compose + S3（Rustfs）实现用户数据持久化

若需要使用BlitzBrowser的用户数据持久化功能，可搭配Rustfs（轻量级S3兼容存储）进行部署，步骤如下：

1. 部署前，先通过Rustfs的Web控制台（http://localhost:9001）创建名为`user-data`的存储桶，用于存放浏览器用户数据。
2. 编写docker-compose.yml配置文件，内容如下：

services:
  blitzbrowser:
    image: ghcr.io/blitzbrowser/blitzbrowser:latest
    ports:
      - "9999:9999"
    environment:
      # 配置S3服务端点
      S3_ENDPOINT: http://s3:9000
      # S3访问密钥
      S3_ACCESS_KEY_ID: rustfsadmin
      # S3秘密密钥
      S3_SECRET_ACCESS_KEY: rustfsadmin
      # 存储用户数据的S3存储桶名称
      S3_USER_DATA_BUCKET: user-data
    shm_size: "2gb"
    restart: always
    # 依赖S3服务，确保S3先启动
    depends_on:
      - s3
  s3:
    image: rustfs/rustfs
    ports:
      - "9000:9000" # S3服务端口
      - "9001:9001" # Rustfs Web控制台端口
    environment:
      RUSTFS_VOLUMES: /data
      RUSTFS_ADDRESS: :9000
      RUSTFS_ACCESS_KEY: rustfsadmin
      RUSTFS_SECRET_KEY: rustfsadmin
      RUSTFS_CONSOLE_ENABLE: true # 启用Web控制台
    restart: always
    volumes:
      - s3_data:/data # 持久化Rustfs数据
  # RustFS卷权限修复服务，避免数据目录权限问题
  volume-permission-helper:
    image: alpine
    volumes:
      - s3_data:/data
    command: >
      sh -c "
      chown -R 10001:10001 /data &&
      echo 'Volume Permissions fixed' &&
      exit 0
      "
    restart: "no" # 仅启动一次，完成权限修复后退出
volumes:
  s3_data: # 定义持久化卷，保存Rustfs数据

3. 在配置文件所在目录执行docker-compose up -d，即可启动包含S3存储的BlitzBrowser服务，实现浏览器用户数据的持久化保存。

代码连接：适配Puppeteer与Playwright

BlitzBrowser部署成功后，可通过主流前端自动化框架连接使用，以下提供Puppeteer与Playwright（NodeJS）的完整连接示例，开发者可直接复用。

示例1：Puppeteer连接

1. 提前在项目中安装Puppeteer依赖：

npm install puppeteer

2. 编写连接代码：

// 导入puppeteer
import puppeteer from 'puppeteer';

// 异步函数封装连接逻辑
async function connectToBlitzBrowser() {
  // 通过CDP协议连接BlitzBrowser（ws://localhost:9999为默认连接地址）
  const browser = await puppeteer.connect({
    browserWSEndpoint: `ws://localhost:9999`
  });

  // 创建浏览器上下文
  const context = await browser.createBrowserContext();
  // 新建一个页面
  const page = await context.newPage();

  // 此处可添加你的业务逻辑（如访问网页、模拟操作等）
  // 示例：访问百度首页
  await page.goto('https://www.baidu.com');
  console.log('已成功访问百度首页');

  // 业务逻辑执行完成后，关闭浏览器连接
  await browser.close();
}

// 调用函数执行连接
connectToBlitzBrowser();

示例2：Playwright + NodeJS连接

1. 提前在项目中安装Playwright依赖：

npm install playwright

2. 编写连接代码：

// 导入playwright的chromium模块
import { chromium } from 'playwright';

// 异步函数封装连接逻辑
async function connectToBlitzBrowserWithPlaywright() {
  // 通过CDP协议连接BlitzBrowser
  const browser = await chromium.connectOverCDP(`ws://localhost:9999`);

  // 创建浏览器上下文
  const context = await browser.newContext();
  // 新建一个页面
  const page = await context.newPage();

  // 此处可添加你的业务逻辑
  // 示例：访问谷歌首页
  await page.goto('https://www.google.com');
  console.log('已成功访问谷歌首页');

  // 业务逻辑执行完成后，关闭浏览器连接
  await browser.close();
}

// 调用函数执行连接
connectToBlitzBrowserWithPlaywright();

详细配置：自定义参数与环境变量

BlitzBrowser支持通过CDP连接参数与容器环境变量进行自定义配置，满足不同场景的个性化需求，开发者可根据实际使用场景调整。

1. CDP连接参数

在通过WS地址连接BlitzBrowser时，可附加查询参数自定义浏览器行为，核心参数如下：

• proxyUrl：指定HTTP代理地址，用于路由浏览器的所有HTTP请求，格式如http://proxy.com:8080，默认使用主机的公网IP。
• timezone：设置浏览器的时区，格式如Asia/Shanghai（中国标准时间），默认根据浏览器公网IP自动匹配时区。
• userDataId：指定用户数据ID，浏览器关闭后，对应的用户数据会持久化保存到S3存储桶中，下次使用相同ID连接可复用数据；若不提供该参数，会话数据不会保存（需提前配置S3存储）。
• userDataReadOnly：指定只读用户数据ID，使用该参数连接时，可复用对应ID的用户数据，但浏览器关闭后，任何修改都不会被保存，适合需要复用基础配置但无需持久化新修改的场景。

使用示例（带参数的WS连接地址）：

ws://localhost:9999?proxyUrl=http://127.0.0.1:7890&userDataId=user_001&timezone=Asia/Shanghai

2. 容器环境变量

通过修改Docker容器的环境变量，可配置BlitzBrowser的核心服务行为，核心环境变量如下：

• PORT：指定Web服务器的HTTP端口，默认值为9999，若需要修改端口，可通过该变量配置（如PORT=8888）。
• MAX_BROWSER_INSTANCES：指定可并发运行的最大浏览器实例数量，默认值为99，可根据服务器配置调整（配置过高可能导致服务器资源不足）。
• S3_ENDPOINT：指定S3存储服务的端点地址，用于连接S3兼容存储（如Rustfs、MinIO），实现用户数据持久化。
• S3_ACCESS_KEY_ID：连接S3存储服务的访问密钥ID，用于身份验证。
• S3_SECRET_ACCESS_KEY：连接S3存储服务的秘密访问密钥，用于身份验证。
• S3_USER_DATA_BUCKET：指定存储浏览器用户数据的S3存储桶名称，需提前创建该存储桶。
• TAGS：用于标识浏览器池的标签，格式为key1=value1,key2=value2，默认无标签，可用于多实例管理与筛选。

配置示例（Docker run命令添加环境变量）：

docker run -p=8888:8888 --shm-size=2g -e PORT=8888 -e MAX_BROWSER_INSTANCES=50 ghcr.io/blitzbrowser/blitzbrowser:latest

版本选择：云端版 vs 自托管版

BlitzBrowser提供云端版与自托管版两种选择，两者核心功能完全一致，仅部署方式与运维责任不同，开发者可根据自身需求选择。

1. 自托管版

• 适用场景：本地测试、自有服务器部署、需要完全掌控基础设施、垂直扩展需求（单台服务器处理多个浏览器，搭配S3存储用户数据）。
• 核心优势：完全开源、可自定义修改、数据自主掌控、无额外付费成本、适配个性化运维需求。
• 注意事项：需要自行负责服务器部署、维护、版本更新与故障排查，需要具备一定的Docker与运维基础。

2. 云端版

• 适用场景：无需关注基础设施、追求快速上线、需要水平扩展、希望获得专业技术支持。
• 核心优势：零运维负担（由官方处理基础设施、版本更新、僵尸进程清理、S3存储管理）、无需本地部署、提供优先技术支持、快速接入使用。
• 额外福利：官方提供独立的HTTP代理服务，无需使用云端版也可单独购买，价格实惠，且与自托管版完全兼容，可满足IP切换等需求。