@cjwddz/browser-server

面向 AI Agent 的自托管常驻浏览器服务。

解决的问题

AI Agent 在无 GUI 的远程服务器上操作浏览器时面临的核心难题：

• 浏览器生命周期绑定 Agent 对话，对话结束状态全丢
• 跨天登录态无法保持，每次都要重新登录
• 验证码、密码等场景 AI 无法处理，卡住无解
• 多 Agent 共用浏览器互相干扰

核心特性

• 常驻浏览器 — 浏览器 7×24 运行，不因 Agent 会话结束而关闭
• 状态完整保持 — Cookie、localStorage、页面 JS 上下文持续存活，跨天登录态不丢
• Web 端实时操控 — 用户随时从浏览器打开管理页面，直接查看和操作浏览器（验证码、密码等）
• Agent 隔离 — 每个会话独立 BrowserContext，Cookie/存储完全隔离
• MCP 集成 — 15 个浏览器操控工具，支持 Streamable HTTP 协议
• 代理调试台 — 在管理端内嵌 whistle，只保留 Rules/Network 视图
• 进程守护 — Chromium 崩溃自动重启

系统依赖

# Ubuntu/Debian
sudo apt-get install -y xvfb x11vnc chromium-browser

安装

npm install -g @cjwddz/browser-server

使用

启动服务

browser-server start -u admin -p mypassword

完整参数

browser-server start \
  -u admin \           # Web 管理登录用户名（必填）
  -p mypassword \      # Web 管理登录密码（必填）
  -w 33000 \           # Web 管理端口（默认 33000）
  -m 33001 \           # MCP 服务端口（默认 33001）
  -d ~/.browser-server \ # 服务根目录（默认 ~/.browser-server）
  --host 0.0.0.0       # 监听地址（默认 0.0.0.0）

其他命令

browser-server stop       # 停止服务
browser-server restart -u admin -p mypassword  # 重启
browser-server status     # 查看状态

使用流程

1. 启动服务
2. 浏览器打开 http://localhost:33000，输入账号密码
3. 点「新建会话」，输入名称
4. 在会话列表中复制该会话的 ID
5. 组装 MCP 地址：http://<host>:33001/mcp/<session-id>
6. 粘贴到 Cursor / Claude Desktop 的 MCP 配置中
7. Agent 开始操作浏览器
8. 需要人工介入时（验证码等），在管理页面点「查看浏览器」直接操作

Whistle 集成说明（源码部署）

为避免把 whistle 暴露为独立系统，管理端将其以“内嵌调试台”方式接入，并裁剪成仅保留：

• Rules 配置（按会话隔离）
• Network 面板（请求调试）

运行机制：

• 仅启动 一个 whistle 实例
• 每个浏览器会话有独立本地代理入口端口（会注入 x-whistle-rule-name 与 x-whistle-client-id）
• 每个会话规则保存为 whistle 独立 rules 文件（文件名=会话 ID），不走全局 Default 合并
• 通过 x-whistle-rule-name 选择会话规则，通过 x-whistle-client-id 隔离抓包视图
• 启动时会自动应用内置 whistle 兼容补丁，保证 HTTPS 解密链路也能识别会话规则文件
• 浏览器代理始终开启：用户只维护 rules（空规则即等价于透传）
• 镜像内会自动启用 HTTPS 捕获并导入 whistle 根证书到 Chromium 信任库

如果你是从本仓源码运行 browser-server，默认会优先使用 third_party/whistle（内置固定源码）。 首次拉取仓库后，请先安装 whistle 依赖：

npm ci --omit=dev --prefix third_party/whistle

如需覆盖 whistle 启动文件，可设置环境变量：

export BROWSER_SERVER_WHISTLE_BIN=/path/to/whistle/bin/whistle.js

架构

browser-server
├── Web 管理 (:33000)          ← 用户浏览器访问
│   ├── 会话列表（创建/删除）
│   ├── 查看浏览器（noVNC 实时画面 + 操作）
│   └── 代理调试（Whistle Rules/Network）
│
├── MCP 服务 (:33001)          ← Agent 连接
│   └── 15 个浏览器操控工具
│
├── Whistle (单实例，多会话并发规则隔离)
├── 会话代理入口 (每会话一个本地端口，转发到 whistle)
│
└── 每个会话 = 独立进程组
    ├── Xvfb (虚拟显示器)
    ├── Chromium (--user-data-dir 持久化)
    └── x11vnc (VNC 服务)

MCP 工具列表

| 工具 | 说明 | |------|------| | navigate_page | 导航到指定 URL | | click | 点击页面元素 | | fill | 填写输入框 | | hover | 悬停在元素上 | | press_key | 按下键盘按键 | | take_screenshot | 截取页面截图 | | take_snapshot | 获取页面 DOM 快照 | | evaluate_script | 执行 JavaScript | | list_pages | 列出所有标签页 | | new_page | 打开新标签页 | | close_page | 关闭当前标签页 | | select_page | 切换标签页 | | wait_for | 等待元素出现或指定时间 | | emulate | 模拟移动设备 | | resize_page | 调整视口大小 |

数据目录结构

~/.browser-server/
├── server.pid          # 守护进程 PID
├── server.json         # 运行配置
├── sessions.json       # 会话列表
├── server.log          # 服务日志
├── <session-id>/       # 会话目录
│   ├── chrome-data/    # Chromium 用户数据（cookie/storage 等）
│   └── chrome.log      # Chromium 日志
└── ...

Docker 部署

适用于 macOS / Windows / 任何不想手动安装系统依赖的场景：

# 构建镜像
npm run build
docker build -f packages/browser-server/Dockerfile -t browser-server .

# 运行
docker run -d \
  -p 33000:33000 \
  -p 33001:33001 \
  -v ~/.browser-server:/data \
  -v /etc/localtime:/etc/localtime:ro \
  -v /etc/timezone:/etc/timezone:ro \
  -e BROWSER_SERVER_USER=admin \
  -e BROWSER_SERVER_PASS=mypassword \
  browser-server

镜像内已包含 Chromium、Xvfb、x11vnc、中文字体、时区数据与证书工具（libnss3-tools），无需额外配置。
建议挂载宿主机 /etc/localtime 和 /etc/timezone，容器会在启动时自动对齐时区；也可直接传入 -e TZ=Asia/Shanghai。 可选环境变量：

• BROWSER_SERVER_HOST（默认 0.0.0.0）
• BROWSER_SERVER_WEB_PORT（默认 33000）
• BROWSER_SERVER_MCP_PORT（默认 33001）
• BROWSER_SERVER_DATA_DIR（默认 /data）
• BROWSER_SERVER_WHISTLE_BIN（默认 /app/third_party/whistle/bin/whistle.js）
• BROWSER_SERVER_STRICT_CERT（默认 1，证书导入失败时启动直接失败）
• BROWSER_SERVER_IGNORE_CERT_ERRORS（默认 0，设为 1 开启宽松模式兜底）

说明：默认使用严格证书模式（推荐）。
只有在临时排障时，才建议设置 BROWSER_SERVER_IGNORE_CERT_ERRORS=1 作为兜底。 证书导入会同时写入 Chromium 常见 NSS 路径：~/.pki/nssdb 与 ~/.local/share/pki/nssdb。

License

MIT