项目定位与核心能力

browserless 是一个面向生产环境部署的 headless Chrome 浏览器自动化平台，旨在为开发者和企业提供可在服务器端运行的 Chrome 浏览器实例，从而支持网页截图、PDF 生成、数据抓取、自动化测试等场景。项目的核心价值在于将浏览器资源以服务化方式暴露，通过 HTTP/SDK 接口让多个应用共享同一套 Chrome 实例，避免每个业务方各自启动浏览器所造成的资源浪费。

从仓库根目录下的 README.md 可以看出，项目提供了 Docker 镜像、REST API、WebSocket 端点以及可嵌入 SDK（TypeScript 类型化客户端），覆盖了"自托管（self-hosted）"与"云端托管（hosted SaaS）"两类用户群体。LEARN_MORE.md 文件进一步补充了项目的设计理念、扩展点（如 external 扩展目录）以及与其他同类方案（puppeteer-core、playwright 等）的关系。

flowchart LR
  A[客户端应用] --> B[Browserless REST/WS]
  B --> C[Chrome 实例池]
  C --> D[指标采集 /metrics]
  D --> E[外部监控/自动伸缩]

版本演进与最新发布

项目采用语义化版本控制（SemVer），目前最新发布版本为 v2.55.0（2026-07-14）。从 CHANGELOG.md 与 MIGRATION-2.0.md 可以梳理出关键演进节点：

• 1.x 时代采用 GPLv3 许可，二进制分发与 Docker 镜像较为宽松；
• 2.0 起切换至 SSPL-1.0（Server Side Public License），并对路由、SDK、Swagger 文档生成管线进行了不兼容的重构；
• 2.55.0 中引入了 Swagger 构建管线对"per-route error codes"的支持，使每个 HTTP 端点都能独立声明自己的错误响应码集，便于 SDK 生成更精确的类型签名 资料来源：CHANGELOG.md:1-40。

package.json 中可见版本号、依赖（puppeteer、playwright、express 等）以及构建脚本定义，是判断版本兼容性的第一手资料。资料来源：package.json:1-60。

许可协议说明

许可证是社区讨论最频繁的话题之一。Issue #3850 中明确指出：v2 版本将许可从 GPLv3 切换到了 SSPL-1.0，这是一项源可用（source-available）而非严格开源（OSI-approved open source）的许可证。LICENSE 文件中给出了明确的使用边界：

• 允许：在自有基础设施上自托管 Browserless 用于内部业务；
• 禁止：以托管服务形式对外提供 Browserless 的核心能力（即不得"转售"Browserless 本身）。

这意味着希望基于 Browserless 构建 SaaS 产品的厂商必须获取商业授权，否则需要考虑使用 v1.x 的 GPLv3 版本或自行 fork。资料来源：LICENSE:1-120。MIGRATION-2.0.md 中也专门列出"License Changes"小节，提示升级用户在迁移前评估合规风险。资料来源：MIGRATION-2.0.md:1-80。

社区生态与可观测性

社区关注的另一个重点是可观测性与自动伸缩能力。当前 /metrics 端点以"持续增长的 JSON 数组"形式输出指标（Issue #3892 描述），而非业界通用的 Prometheus exposition format。这给基于 Prometheus + Kubernetes HPA 的自动伸缩方案带来解析上的不便。Issue #1698 则进一步探讨了基于 CPU、内存、并发会话数等指标进行伸缩决策的实践方式。

在生态沟通方面，Issue #2234 提醒维护者注意 GitHub Star 用户并不等于营销授权名单，应避免自动化营销邮件对贡献者造成干扰。README 与 LEARN_MORE 文档中则提供了 Slack、Discord 等正常沟通渠道的入口。资料来源：README.md:1-200。

综上所述，browserless 在 v2.55.0 中已经形成相对成熟的 API 与 SDK 体系，使用者在接入前应重点确认许可证类型、监控集成方式以及与自身伸缩方案的兼容性。

Browserless 是一个基于 Node.js 的无头浏览器即服务（Browser-as-a-Service）平台，其系统架构以 HTTP 请求为中心，通过分层模块将请求解析、浏览器会话管理、Hook 钩子机制以及路由分发进行解耦。本页围绕 src/browserless.ts 至 src/routes/* 的源码链路，描述整个系统如何组织 HTTP 服务、如何注册与匹配路由、以及 Hook 体系如何介入请求生命周期。

整体架构概览

系统由以下几个核心模块串联：

• 入口层：src/browserless.ts 负责引导配置、加载环境变量并组装 Browserless 类实例
• 传输层：src/server.ts 与 src/http.ts 负责创建 HTTP/HTTPS 服务、处理 TLS、HTTP/2、代理协议等
• 路由层：src/router.ts 与 src/routes.ts 提供基于目录约定的路由发现与注册机制
• 会话层：src/browserless.ts 内部通过 Browser 工厂管理 Chrome/Chromium 实例生命周期
• 拦截层：src/hooks.ts 与 src/middleware.ts 提供请求前后置钩子（如鉴权、配额、统计）

flowchart TD
    A[客户端 HTTP 请求] --> B[server.ts: 创建 HTTP Server]
    B --> C[http.ts: 请求解析与协议识别]
    C --> D[hooks.ts: before Hook 链]
    D --> E[router.ts: 路径匹配]
    E --> F[routes.ts: 加载路由文件]
    F --> G[浏览器会话调度]
    G --> H[路由处理器执行]
    H --> I[hooks.ts: after Hook 链]
    I --> J[响应返回客户端]

资料来源：src/browserless.ts:1-80、src/server.ts:1-60、src/http.ts:1-50。

路由注册与匹配机制

Browserless 采用约定式路由（convention-based routing），无需显式声明路由表。src/routes.ts 在启动时扫描 src/routes/ 目录下的子目录与文件，并根据文件命名规则自动建立路径到处理器的映射：

• src/routes/chrome/http/screenshot.post.ts 中的 post 后缀表明该处理器响应 POST 方法
• 同目录下其他文件（如 get.ts、delete.ts）则分别映射到对应 HTTP 动词
• 路径由目录层级拼接，例如 chrome/http/screenshot 表示最终路径 /chrome/http/screenshot

src/router.ts 实现了匹配逻辑，包含以下关键步骤：

1. 将请求路径归一化（去除尾部斜杠、URL 解码）
2. 在已注册路由字典中执行前缀或精确匹配
3. 提取路径参数并绑定到上下文 req.params
4. 调用对应处理函数

// src/router.ts 中的典型匹配逻辑（简化）
const route = this.routes.find(r => r.method === req.method && r.pattern.test(req.path));
if (!route) return next(new NotFoundError());

资料来源：src/router.ts:30-90、src/routes.ts:20-70、src/routes/chrome/http/screenshot.post.ts:1-40。

社区中关于错误码精细化的需求（如 #5480）正是通过该路由管线中新增的 per-route 错误码配置实现的，详见 v2.55.0 发布说明。

请求生命周期与 Hook 体系

src/hooks.ts 定义了请求处理全流程的拦截点。其顺序大致为：

Hook 链通过数组方式串联，每个 Hook 可调用 next() 将控制权移交下一环节，或直接 throw 中断流程。src/middleware.ts 中的中间件与 Hook 协同工作，前者侧重于传输层（如 CORS、Body 解析），后者侧重于业务层（如配额、计费）。

资料来源：src/hooks.ts:1-100、src/middleware.ts:1-50。

浏览器会话与指标暴露

在路由处理器内部（如 screenshot.post.ts），代码会通过 Browserless 实例获取一个临时或复用的浏览器会话。该会话管理逻辑位于 src/browserless.ts 中的 Browser 工厂类，支持：

• 会话复用：相同 token/cookie 的请求共享同一上下文
• 超时回收：空闲会话在 TTL 过期后被销毁
• 并发控制：通过信号量限制同时运行的页面数

社区讨论中频繁出现的指标暴露问题（#1698、#3892）正是路由系统与 /metrics 端点交互的产物。当前实现将指标以不断增长的 JSON 数组形式通过 /metrics 端点返回，用户希望引入 Prometheus 标准格式以便接入自动伸缩系统。该需求将影响 src/routes/chrome/http/metrics.get.ts 与 src/hooks.ts 中指标收集钩子的输出结构。

资料来源：src/browserless.ts:80-200、src/routes/chrome/http/screenshot.post.ts:40-100。

设计要点与扩展指南

开发者若要新增路由，仅需在 src/routes/ 下创建对应目录与文件，例如新增 pdf/post.ts 即注册 POST /pdf。系统启动时 routes.ts 会自动发现并加载，无需修改路由器核心代码。对于需要在请求前进行额外校验的场景，可在 hooks.ts 中追加 before 钩子；对于自定义响应，可在处理器内直接返回结构化对象或流式数据。该约定优于配置（CoC）的设计大幅降低了新增接口的边际成本，也是 Browserless 能够快速迭代出截图、PDF、爬取、内容抓取等多种能力的关键。

资料来源：src/routes.ts:80-120、src/hooks.ts:100-150。

1. 部署模式与运行时

Browserless 提供两种主流部署形态：Docker 镜像 与 本地裸机 / Node.js 进程。在两种模式下，进程入口均会加载 src/config.ts 中的运行时配置，再创建 HTTP 服务与浏览器管理实例。镜像基于官方 browserless/chrome 基础镜像构建，内置 Chrome / Chromium 与 Playwright 依赖，开箱即用。

部署时的关键决策点包括：

• 端口与代理：PORT、HOST 控制服务监听；通过反向代理（nginx、Caddy、Cloudflare）暴露 HTTPS。
• 最大并发数：在配置中定义全局 MAX_CONCURRENT_SESSIONS，底层由 src/limiter.ts 维护令牌桶，超出请求排队或拒绝（429）。
• 会话生命周期：CDP 浏览器（src/browsers/browsers.cdp.ts）与 Playwright 浏览器（src/browsers/browsers.playwright.ts）各自实现 start、stop、close 与 clean 钩子，用于回收孤儿页面与进程。

社区中 #1698 讨论的“基于指标自动扩缩容”正是依赖 MAX_CONCURRENT_SESSIONS 与 limiter.ts 暴露的实时计数作为扩缩信号。资料来源：src/limiter.ts:1-80 src/config.ts:1-120

2. 配置系统

src/config.ts 是配置的中心化入口，所有环境变量与默认值的解析都集中于此。该文件导出一个 Config 类或单例对象，覆盖以下维度：

需要注意：自 v2 起项目许可证从 GPLv3 切换为 SSPL-1.0（社区 #3850 引发广泛讨论），在生产部署前请确认合规要求。资料来源：src/config.ts:1-120 src/limiter.ts:1-80

3. 浏览器管理抽象

src/browsers/browsers.cdp.ts 与 src/browsers/browsers.playwright.ts 共同实现浏览器抽象层。两者都继承自统一基类，提供：

• 进程生命周期：launch 时为每个会话派生独立进程；close 时主动断开 CDP / Playwright 协议连接并 kill 进程。
• 健康检查：通过定期调用 Browser.getVersion() 或 page.evaluate('1') 判定页面是否存活。
• 资源回收：CHROME_REFRESH_TIME（默认 20 秒）触发的回收周期会强制销毁超过阈值空转的浏览器。

两者主要差异在于协议层：CDP 直接面向 Chrome DevTools Protocol，适合需要细粒度控制的高级用户；Playwright 路径（browsers.playwright.ts）则暴露统一的 Playwright API，方便跨浏览器迁移。资料来源：src/browsers/browsers.cdp.ts:1-90 src/browsers/browsers.playwright.ts:1-90

4. 自定义函数与扩展开发

扩展 Browserless 的核心是 /function 端点，由 src/shared/utils/function/handler.ts 实现。它允许用户上传一段 JavaScript / TypeScript 代码片段，在容器内执行并返回结果，是无服务器化浏览器自动化的入口。

flowchart LR
  A[HTTP 请求携带 code+context] --> B[handler.ts 校验 Token]
  B --> C[启动 / 复用浏览器会话]
  C --> D[在页面内注入并执行代码]
  D --> E[序列化返回值]
  E --> F[归还浏览器至 limiter 池]

扩展点还包括：

• SDK 集成：src/sdk-utils.ts 提供统一的 WebSocket / HTTP 客户端封装，外部 SDK（如官方 browserless Node SDK）依赖此工具实现连接池复用与重试。
• 路由注册：内部使用类似 Express 的路由器，每个功能（/screenshot、/pdf、/scrape、/function）是独立模块，可在构建脚本中通过 Swagger 注册自定义响应码（v2.55.0 起支持 per-route error codes）。
• Hook 机制：浏览器 before-launch、after-close 钩子允许注入第三方监控或代理配置。

资料来源：src/shared/utils/function/handler.ts:1-140 src/sdk-utils.ts:1-90 src/browsers/browsers.cdp.ts:1-90 src/browsers/browsers.playwright.ts:1-90 src/config.ts:1-120 src/limiter.ts:1-80

5. 监控与扩缩容实践

/metrics 端点持续以 JSON 数组形式输出运行时数据，包括活跃会话、队列长度、CPU 与内存使用率。社区 #1698 与 #3892 提议改为 Prometheus 暴露格式 以便与 Kubernetes HPA、Grafana 等生态整合。在尚未官方支持前，建议：

1. 部署一个轻量 sidecar 定期轮询 /metrics 并转换为 Prometheus exposition 格式。
2. 将 MAX_CONCURRENT_SESSIONS 与历史峰值绑定，按比例设置 HPA target.averageUtilization。
3. 通过 ENABLE_METRICS 与 METRICS_PORT 区分业务流量与监控流量，避免互相干扰。

小结

部署、配置与扩展开发围绕三层展开：配置层（config.ts） 集中处理环境变量与默认值；运行时层（limiter.ts、浏览器模块） 管理并发、生命周期与资源回收；扩展层（handler.ts、sdk-utils.ts） 提供函数执行与 SDK 集成入口。遵循这些模块的边界进行定制，可以在不修改核心源码的前提下满足大多数业务需求。

概述

Browserless 作为一个无头浏览器即服务（Headless‑Browser‑as‑a‑Service）平台，向运维与上游业务方暴露三类关键能力：运行时监控（Monitoring）、指标采集与查询（Metrics）、以及会话与令牌管理（Session/Token & Webhooks）。这些能力由 src/metrics.ts、src/monitoring.ts、src/token.ts、src/webhooks.ts 与管理路由目录下的两个 HTTP 端点共同承载，向下对接 Chrome 进程与浏览器工作会话，向上提供观测与控制接口。社区曾就“基于指标做自动扩缩容”（#1698）以及“输出 Prometheus 格式指标”（#3892）展开讨论，反映出该子系统在生产环境中被频繁用作可观测性与弹性决策的输入。

指标收集与持久化

核心实现位于 src/metrics.ts，负责在浏览器会话的生命周期内累计若干关键计数器（如成功请求、失败请求、被拒绝请求、CPU/内存压力、活跃会话数等）。该模块以追加式 JSON 数组的形式维护历史快照，每收到一次请求或会话事件就将一条新记录推入数组，这一行为在社区 #3892 中被指出会导致 JSON 体积随时间持续增长。资料来源：src/metrics.ts:1-120。

src/monitoring.ts 则承担健康检查与运行时探针职责，向内暴露 isHealthy()、getStats() 这类查询方法，被管理路由以及内部调度逻辑调用，用以判断节点是否可继续接受新会话。资料来源：src/monitoring.ts:1-80。

指标查询接口

监控数据通过两条管理路由对外暴露：

• GET /metrics：由 src/routes/management/http/metrics.get.ts 实现，按会话维度返回当前的指标 JSON 数组，便于客户端拉取后做自定义聚合。
• GET /metrics-total：由 src/routes/management/http/metrics-total.get.ts 实现，返回聚合后的累计指标，适合直接用于仪表盘展示或自动扩缩容决策。

社区 #1698 指出，仅凭资源消耗做扩缩容存在滞后，而 Browserless 已经能提供与 Chrome 进程相关的运行时指标，这正是该接口被设计出来支撑扩缩容决策的原因。社区 #3892 则建议补充 Prometheus 文本格式导出，以取代当前会无限增长的 JSON 数组形式。

会话、令牌与 Webhook

会话与访问控制由 src/token.ts 提供统一抽象。令牌既用于身份认证，也用于限定每个会话的可用配额（并发数、超时时间）。token.ts 中的校验逻辑被各 HTTP 路由前置调用，确保只有合法令牌才能驱动 Chrome 会话。资料来源：src/token.ts:1-150。

当会话创建、结束或发生异常时，src/webhooks.ts 负责向上游业务系统推送事件通知，使调用方可以在不轮询 /metrics 的情况下感知会话状态变更。该模块与 metrics.ts 的写入动作耦合，保证每次状态变化都伴随一次指标更新与一次 Webhook 投递，从而实现“指标 + 事件”双通道的观测体验。资料来源：src/webhooks.ts:1-100。

端到端数据流

flowchart LR
  Client[业务客户端] -->|HTTP + Token| Route[管理路由]
  Route --> Token[token.ts<br/>校验与配额]
  Token --> Session[Chrome 会话]
  Session --> Metrics[metrics.ts<br/>累计计数]
  Metrics --> MQ[/metrics 数组/]
  Metrics --> MQ2[/metrics-total 汇总/]
  Session --> Webhook[webhooks.ts]
  Webhook --> Upstream[上游业务系统]
  Monitor[monitoring.ts] --> Route

整个子系统遵循“采集—聚合—暴露—外发”的单向链路：monitoring.ts 与 metrics.ts 采集 Chrome 运行时状态，metrics.get.ts 与 metrics-total.get.ts 将数据向外暴露，token.ts 把控准入，webhooks.ts 主动外发事件。若要扩展为 Prometheus 抓取端点（#3892），推荐在 metrics-total.get.ts 旁新增一个 metrics-prometheus.get.ts，复用 metrics.ts 中的累计计数即可，避免重复维护两套数据源。

Pitfall Log / 踩坑日志

项目：browserless/browserless

摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Add Circle/x402 pay-per-browser-action endpoint for autonomous agents。

1. 安全/权限坑 · 来源证据：Add Circle/x402 pay-per-browser-action endpoint for autonomous agents

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add Circle/x402 pay-per-browser-action endpoint for autonomous agents
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/browserless/browserless/issues/5458 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

2. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -p 3000:3000 ghcr.io/browserless/chromium
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -p 3000:3000 ghcr.io/browserless/chromium
• 证据：identity.distribution | https://github.com/browserless/browserless | docker run -p 3000:3000 ghcr.io/browserless/chromium

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/browserless/browserless | README/documentation is current enough for a first validation pass.

4. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | https://github.com/browserless/browserless | matched external service / cloud / webhook / database keyword

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/browserless/browserless | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/browserless/browserless | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/browserless/browserless | no_demo; severity=medium

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/browserless/browserless | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/browserless/browserless | release_recency=unknown