这是一个关于 OpenBrowser 的详细部署教程。OpenBrowser 是一个本地的指纹浏览器桌面应用，用于管理多个隔离的 Chromium 环境。

本教程将涵盖从环境准备、源码运行到不同平台（Windows、macOS、Ubuntu）的打包构建全过程。

📋 部署前准备

在开始前，请确保你的系统满足以下要求：

  • 操作系统：Windows (x86_64)、macOS (x86_64/arm64) 或 Ubuntu (x86_64)。
  • Node.js：需要安装 Node.js LTS 版本。
  • 包管理器：npm（通常与 Node.js 一同安装）。

🚀 快速启动（开发/测试模式）

如果你希望直接从源码运行应用进行开发或测试，可以按照以下步骤操作。

  1. 克隆仓库

    1
    2
    git clone https://github.com/lyu0805/OpenBrowser.git
    cd OpenBrowser

  2. 进入应用目录并安装依赖

    1
    2
    cd Browserapp
    npm ci --include=dev

    这里使用 npm ci 而非 npm install，可以确保安装的依赖版本与 package-lock.json 完全一致，更可靠。

  3. 运行自检（推荐）
    在首次启动前，运行自检脚本以验证环境：

    1
    npm run selftest

    你还可以运行更具体的测试（如自动化、协议、隔离性等）：

    1
    2
    3
    4
    5
    npm run selftest:automation
    npm run selftest:protocol
    npm run selftest:isolation
    npm run selftest:kernel
    npm run selftest:cloud

  4. 启动应用

    1
    npm start

或使用根目录的启动脚本（一键运行）：

平台 脚本文件
macOS start-test.command
Windows start-test.cmd
Ubuntu start-test.sh

在对应平台直接双击或运行该脚本即可完成依赖安装和启动。

📦 打包为独立应用（生产部署）

如果你想将 OpenBrowser 打包成无需源码即可运行的可执行文件或安装包，请使用其内置的打包流程。

  1. 进入应用目录

    1
    cd Browserapp

  2. （仅限 Ubuntu x86_64）准备 Linux 内核
    如果你在 Ubuntu x86_64 平台上打包，需要先显式获取 Chrome for Testing 内核包：

    1
    npm run prepare:linux-kernel

  3. 执行打包

    1
    npm run package:portable

打包完成后，输出文件会生成在 Browserapp/dist/ 目录下。

各平台输出说明：

平台 输出内容 备注
Windows 包含 START.cmd 启动脚本的文件夹 可直接运行
macOS 包含 OpenBrowser.app 和 启动.command 脚本 可直接运行 .app
Ubuntu x86_64 一个 .tar.gz 压缩包（如 OpenBrowser-….tar.gz） 解压后运行其中的启动脚本

🔧 Ubuntu 平台补充说明

在 Ubuntu 上运行打包后的应用，可能需要安装一些系统依赖库。如果启动失败，请执行以下命令安装：

1
sudo apt-get install libatk-bridge2.0-0 libatk1.0-0 libatspi2.0-0 libcups2 libdrm2 libgbm1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libxcomposite1 libxdamage1 libxfixes3 libxkbcommon0 libxrandr2

重要提示：

  • Ubuntu 包已经内置了 Chrome for Testing 内核，应用在运行时不会再次下载内核。
  • 请使用普通桌面用户身份运行应用，不要使用 sudo。

⚙️ 核心功能与配置

OpenBrowser 的核心功能围绕多环境隔离展开，部署完成后，你可以通过应用界面进行配置：

功能模块 说明
环境隔离 每个浏览器环境拥有独立的 Chromium 配置（Cookie、缓存、存储等）
指纹控制 可自定义平台、语言、时区、User-Agent、Canvas、WebGL、WebRTC 等指纹参数
代理支持 可为每个环境单独配置 HTTP/HTTPS/SOCKS 代理，并支持出口检查
本地 API 默认在 127.0.0.1:50325 提供本地 API 和 MCP 集成，可设置 OPENBROWSER_API_KEY 增强安全
备份选项 支持将配置备份到本地、WebDAV、GitHub 或云盘（需显式配置）
窗口同步 基于 CDP 的窗口同步，包括点击、滚动、输入和标签页同步
本地 RPA 内置流程自动化，支持导航、等待、点击、输入和截图

❓ 常见问题

  • 问：打包后的应用无法启动？
    • Windows/macOS：检查是否有安全软件拦截，确保以管理员/普通用户身份正确运行。
    • Ubuntu：请确认已安装上文列出的所有系统依赖库，并以普通用户身份运行。
  • 问：如何更新应用？
    • 由于仓库不存储内核二进制文件，更新时请拉取最新代码，并重新执行 npm ci 和打包步骤。官方包会从更新源获取匹配的内核。
  • 问：数据存储在哪里？
    • 用户数据（如配置文件、日志）存储在系统用户目录下，不会存储在源码仓库内。启动失败时可查看 browser-startup.log。

🔗 更多资源

按照以上步骤，你应该能够成功在本地运行或打包 OpenBrowser。如果在特定平台遇到问题，可以查阅项目仓库的 README.md 或提交 Issue。