# https://github.com/steel-dev/steel-browser 项目说明书

生成时间：2026-06-21 08:41:16 UTC

## 目录

- [项目概述与快速入门](#page-1)
- [系统架构与组件](#page-2)
- [核心功能：会话、操作、反检测](#page-3)
- [部署、插件开发与故障排除](#page-4)

<a id='page-1'></a>

## 项目概述与快速入门

### 相关页面

相关主题：[系统架构与组件](#page-2), [核心功能：会话、操作、反检测](#page-3), [部署、插件开发与故障排除](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/steel-dev/steel-browser/blob/main/README.md)
- [api/package.json](https://github.com/steel-dev/steel-browser/blob/main/api/package.json)
- [ui/package.json](https://github.com/steel-dev/steel-browser/blob/main/ui/package.json)
- [repl/package.json](https://github.com/steel-dev/steel-browser/blob/main/repl/package.json)
- [repl/README.md](https://github.com/steel-dev/steel-browser/blob/main/repl/README.md)
- [api/src/utils/schema.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/schema.ts)
- [api/src/utils/scrape/index.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/scrape/index.ts)
- [api/src/utils/requests.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/requests.ts)
- [api/src/utils/casting.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/casting.ts)
- [api/extensions/recorder/package.json](https://github.com/steel-dev/steel-browser/blob/main/api/extensions/recorder/package.json)
</details>

# 项目概述与快速入门

## 一、项目定位与核心能力

Steel 是一个面向 AI Agent 与应用的开源浏览器 API，旨在让开发者无需从零搭建浏览器自动化基础设施即可驱动真实的 Chrome 实例。其内部使用 Puppeteer 与 Chrome DevTools Protocol (CDP)，因此客户端可以继续使用 Puppeteer、Playwright 或 Selenium 直接连接到 Steel 暴露的 WebSocket 端点。资料来源：[README.md:1-30]()。

主要能力包括：

| 能力维度 | 说明 |
| --- | --- |
| 浏览器控制 | 通过 Puppeteer / CDP 全权控制 Chrome |
| 会话管理 | 在请求间持久化 Cookie、Local Storage 等浏览器状态 |
| 代理与反检测 | 内置 `proxy-chain`、`socks-proxy-agent` 与 `fingerprint-generator/injector` |
| 扩展加载 | 支持加载自定义 Chrome 扩展（如 `steel-recording-extension`） |
| 内容抽取 | 提供 HTML 清洗、JSON/Markdown 转换、PDF 解析与 Readability 抽取 |

上述能力与依赖可在 [api/package.json:30-50]() 中直接看到，包括 `puppeteer-core@23.6.0`、`fingerprint-generator@2.1.82`、`fingerprint-injector@2.1.82`、`proxy-chain@^2.5.6` 等。

## 二、仓库结构

项目采用 monorepo 形式，主要由三个 npm 包组成：

```mermaid
graph LR
    A[steel-browser 仓库] --> B[api/]
    A --> C[ui/]
    A --> D[repl/]
    B --> E[Fastify HTTP API + CDP]
    B --> F[extensions/recorder/]
    C --> G[React + Vite 调试界面]
    D --> H[基于 puppeteer-core 的 REPL]
```

各包职责如下：

- **api/**：基于 Fastify 5 的 HTTP 服务，承载会话、页面、CDP 转发与抓取/截图/PDF 等动作端点；并使用 [api/src/utils/schema.ts:1-30]() 的 `buildJsonSchemas` 将 Zod Schema 转写为 OpenAPI 3 文档，供 `/documentation` 展示。
- **ui/**：基于 React 18 + Radix UI + Tailwind 的调试与录制回放界面，依赖 [ui/package.json:1-50]() 中的 `rrweb-player` 进行会话回放，使用 `@hey-api/openapi-ts` 自动生成 API 客户端。
- **repl/**：极简命令行 REPL，通过 [repl/package.json:1-15]() 中的 `puppeteer-core@^24.2.0` 直接连接到 API 暴露的 WebSocket，便于快速试验。
- **api/extensions/recorder/**：基于 `rrweb@^2.0.0-alpha.4` 的 Chrome 扩展，用于录制用户操作；构建产物由 [api/extensions/recorder/package.json:1-12]() 描述。

## 三、快速入门

### 3.1 通过 Docker 启动

最快的运行方式是从 GitHub Container Registry 拉取预构建镜像：

```bash
docker run -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser
```

- `3000` 端口对应 HTTP API（含 Swagger UI，路径 `/documentation`）。
- `9223` 端口对应 CDP WebSocket，可由 Puppeteer/Playwright/Selenium 连接。

部署按钮与一键模板（Railway、Render）同样收录在 README 表格中。资料来源：[README.md:55-80]()。

### 3.2 通过 REPL 连接已运行的实例

`repl/` 包提供交互式脚本，约定 WebSocket 端点已对外暴露。启动方式：

```bash
cd repl
npm install
npm start
```

随后在 `src/script.ts` 中编写 Puppeteer 逻辑并重复执行即可，无需重启 API 服务。资料来源：[repl/README.md:1-15]()。

### 3.3 常用动作示例

API 同时提供短路径动作端点（无需持有 CDP 会话），例如：

```bash
# 抓取页面 HTML
curl -X POST http://0.0.0.0:3000/v1/scrape \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "delay": 1000 }'

# 截屏
curl -X POST http://0.0.0.0:3000/v1/screenshot \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "fullPage": true }' --output screenshot.png

# 导出 PDF
curl -X POST http://0.0.0.0:3000/v1/pdf \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }' --output output.pdf
```

后端在 `api/src/utils/scrape/index.ts` 中聚合了 HTML 清洗、Readability 抽取（`defuddle`）、JSON 转 Markdown 与 base64 图片剥离等能力，并在 [api/src/utils/scrape/jsonToMarkdown.ts:1-10]() 与 [api/src/utils/scrape/pdfToHtml.ts]() 中实现。

## 四、常见陷阱与社区反馈

- **指纹注入失败**：在自托管 `steel-browser-api`（v0.5.3 / `fingerprint-generator@2.1.82`）下，部分 Chrome 146 + 固定 `1920x1080` 的组合会触发 `Failed to generate a consistent fingerprint after 10 attempts`，此时可用 `SKIP_FINGERPRINT_INJECTION` 环境变量临时绕过（参考 issue #295、#302）。
- **本地 `npm run dev` 报错 `File is not defined`**：通常与 Node 版本低于 22 或 Web API polyfill 缺失有关，请使用仓库要求的 Node ≥ 22（参考 issue #230）。
- **API 文档不完整**：社区多次反馈希望补齐集群、代理链路、扩展加载等高级主题的文档（参考 issue #123、#144）。当前仓库通过 [api/src/utils/requests.ts:1-15]() 的 `compileUrlPatterns` 与 `isUrlMatchingPatterns` 提供请求级黑白名单/匹配能力，可作为请求路由的参考实现。

## See Also

- [API 路由与会话管理（Session 生命周期、CDP 转发）](#)
- [抓取与内容抽取管线（scrape utilities、PDF/JSON 转换）](#)
- [指纹与反检测配置（fingerprint-generator / fingerprint-injector）](#)
- [录制扩展与回放（rrweb、rrweb-player）](#)

---

<a id='page-2'></a>

## 系统架构与组件

### 相关页面

相关主题：[项目概述与快速入门](#page-1), [核心功能：会话、操作、反检测](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/steel-dev/steel-browser/blob/main/README.md)
- [api/package.json](https://github.com/steel-dev/steel-browser/blob/main/api/package.json)
- [ui/package.json](https://github.com/steel-dev/steel-browser/blob/main/ui/package.json)
- [repl/package.json](https://github.com/steel-dev/steel-browser/blob/main/repl/package.json)
- [repl/README.md](https://github.com/steel-dev/steel-browser/blob/main/repl/README.md)
- [api/extensions/recorder/package.json](https://github.com/steel-dev/steel-browser/blob/main/api/extensions/recorder/package.json)
- [api/src/utils/schema.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/schema.ts)
- [api/src/utils/casting.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/casting.ts)
- [api/src/utils/scrape/index.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/scrape/index.ts)
- [api/src/utils/scrape/jsonToMarkdown.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/scrape/jsonToMarkdown.ts)
- [api/src/utils/scrape/pdfToHtml.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/scrape/pdfToHtml.ts)
</details>

# 系统架构与组件

## 总体架构概述

Steel Browser 是一个面向 AI Agent 与自动化应用的开源浏览器 API 项目，其设计目标是将浏览器会话管理、CDP（Chrome DevTools Protocol）控制、页面抓取与反检测能力以 HTTP / WebSocket 接口的形式对外暴露，调用方可以使用 Puppeteer、Playwright 或 Selenium 直接连接 ([README.md:55-65]())。

整个系统由多个相互协作的包组成，源代码按职责划分为 `api`（核心服务）、`ui`（调试控制台）、`repl`（本地脚本入口）以及 `api/extensions/recorder`（会话录制扩展）四个主要模块 ([README.md:1-15](), [api/package.json:1-15](), [ui/package.json:1-15](), [repl/package.json:1-10](), [api/extensions/recorder/package.json:1-10]())。这种「API + UI + REPL + 扩展」的组合方式让开发者既能以服务方式部署，也可以通过脚本直接驱动浏览器实例。

## 核心包与组件结构

仓库采用 monorepo 风格的多包布局，每个子目录都是一个独立的 Node 包，依赖通过 `package.json` 分别管理。

| 包路径 | 名称 | 主要职责 | 关键依赖 |
| --- | --- | --- | --- |
| `api/` | `@steel-browser/api` | 提供 HTTP / WebSocket API、CDP 服务、会话与抓取工具 | `fastify`, `puppeteer-core`, `fingerprint-generator`, `fingerprint-injector`, `proxy-chain`, `mupdf` ([api/package.json:30-65]()) |
| `ui/` | `@steel-browser/ui` | 基于 Vite + React 的会话调试 UI，使用 `rrweb-player` 回放录制 | `react`, `rrweb-player`, `@radix-ui/themes` ([ui/package.json:15-30]()) |
| `repl/` | `@steel-browser/repl` | 通过 `puppeteer-core` 连接 API 暴露的 WebSocket 端点 | `puppeteer-core@^24.2.0` ([repl/package.json:8-12]()) |
| `api/extensions/recorder/` | `steel-recording-extension` | 浏览器内录制扩展，使用 `rrweb` 捕获 DOM 事件 | `rrweb`, `@rrweb/packer` ([api/extensions/recorder/package.json:6-10]()) |

`repl/README.md` 中明确说明，REPL 仅依赖一个本地脚本 `src/script.ts`，运行前需要确保 Steel Browser 已经启动，且 WebSocket 端点可达 ([repl/README.md:5-15]())。这种轻量的连接器让本地调试可以复用服务实例，避免重复启动 Chrome。

## API 服务关键模块

`api` 包基于 Fastify 5 构建，并集成 `@fastify/swagger` 与 `@scalar/fastify-api-reference` 自动生成 OpenAPI 文档 ([api/package.json:30-50]())。其内部工具模块按职责进一步切分：

- **Schema 工具**：`api/src/utils/schema.ts` 封装了 `buildJsonSchemas`，基于 `zod` 与 `zod-to-json-schema` 将 Zod 模型转换为 OpenAPI 3 JSON Schema，并以 `$ref` 形式复用 ([api/src/utils/schema.ts:1-40]())。
- **会话投射（casting）工具**：`api/src/utils/casting.ts` 实现了 `navigatePage`、`getPageTitle`、`getPageFavicon` 等对 `puppeteer-core` `Page` 对象的封装，处理前进 / 后退 / 刷新等导航事件 ([api/src/utils/casting.ts:1-20]())。

值得注意的是，`api/package.json` 同时依赖 `fingerprint-generator@2.1.82` 与 `fingerprint-injector@2.1.82`，这是项目反检测能力的核心实现 ([api/package.json:50-60]())。社区中已经出现与指纹生成相关的故障报告（如 Chrome 146 + 1920x1080 解析失败），说明该模块在升级时需要重点回归测试（参见 [Issue #302](https://github.com/steel-dev/steel-browser/issues/302)）。

## 数据采集与转换工具

`api/src/utils/scrape/` 目录提供了页面抓取后处理流水线，由 `index.ts` 统一导出 ([api/src/utils/scrape/index.ts:1-5]())：

```mermaid
flowchart LR
  A[原始 HTTP 响应] --> B{Content-Type}
  B -- HTML --> C[cleanHtml / readability]
  B -- application/json --> D["jsonToMarkdown<br/>(jsonToMarkdown.ts)"]
  B -- application/pdf --> E["pdfToHtml<br/>(mupdf 解析)"]
  C --> F[Markdown / 纯文本输出]
  D --> F
  E --> F
```

- `jsonToMarkdown.ts` 通过 `isJsonContentType` 正则匹配 `+json` 或 `/json`，并将原始 JSON 字符串包裹在 ``` ```json ``` 代码块中返回 ([api/src/utils/scrape/jsonToMarkdown.ts:1-10]())。
- `pdfToHtml.ts` 使用 `mupdf`（`mupdf@^1.27.0`）打开 PDF 缓冲，按页遍历 `toStructuredText` 输出 HTML，并提取外部链接以及元数据（标题、创建日期、修改日期） ([api/src/utils/scrape/pdfToHtml.ts:1-30](), [api/package.json:60-65]())。
- 其他模块如 `cleanHtml`、`readability`（`defuddle`）、`stripBase64Images` 也都通过 `index.ts` 暴露，用于实现 README 中提到的「页面转 Markdown、Readability、截图、PDF」等 Browser Tools ([README.md:60-65](), [api/src/utils/scrape/index.ts:1-5]())。

## 部署与组件协作

README 在「Quick Deploy」一节中推荐使用 GitHub Container Registry 上的预构建 Docker 镜像同时部署 API 与 UI，并暴露 `3000`（API）与 `9223`（CDP）两个端口 ([README.md:85-105]())。REPL 在此基础上作为可选客户端，连接到 API 暴露的 WebSocket 端点即可复用同一个 Chrome 实例 ([repl/README.md:5-15]())。这种「单实例多入口」的部署方式减少了浏览器进程数量，但同时也意味着水平扩展时需要自行实现会话亲和性（社区 [Issue #144](https://github.com/steel-dev/steel-browser/issues/144) 正是关于集群路由的讨论）。

## See Also

- 入门与部署：参见 [README.md](https://github.com/steel-dev/steel-browser/blob/main/README.md)
- 本地 REPL 使用：参见 [repl/README.md](https://github.com/steel-dev/steel-browser/blob/main/repl/README.md)
- 相关社区话题：[Issue #302 指纹生成故障](https://github.com/steel-dev/steel-browser/issues/302)、[Issue #295 指纹一致性失败](https://github.com/steel-dev/steel-browser/issues/295)、[Issue #144 集群会话路由](https://github.com/steel-dev/steel-browser/issues/144)

---

<a id='page-3'></a>

## 核心功能：会话、操作、反检测

### 相关页面

相关主题：[系统架构与组件](#page-2), [部署、插件开发与故障排除](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [api/src/modules/sessions/sessions.controller.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/modules/sessions/sessions.controller.ts)
- [api/src/modules/sessions/sessions.routes.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/modules/sessions/sessions.routes.ts)
- [api/src/modules/sessions/sessions.schema.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/modules/sessions/sessions.schema.ts)
- [api/src/modules/actions/actions.controller.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/modules/actions/actions.controller.ts)
- [api/src/modules/actions/actions.routes.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/modules/actions/actions.routes.ts)
- [api/src/services/cdp/plugins/core/plugin-manager.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/services/cdp/plugins/core/plugin-manager.ts)
- [api/src/services/cdp/plugins/builtin/fingerprint.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/services/cdp/plugins/builtin/fingerprint.ts)
- [api/src/utils/casting.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/casting.ts)
- [api/src/utils/context.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/context.ts)
- [api/package.json](https://github.com/steel-dev/steel-browser/blob/main/api/package.json)
- [README.md](https://github.com/steel-dev/steel-browser/blob/main/README.md)
</details>

# 核心功能：会话、操作、反检测

Steel 是一个面向 AI Agent 与应用的开放源代码浏览器 API。其核心抽象建立在三层之上：**会话（Session）** 负责浏览器生命周期，**操作（Actions）** 提供即用型页面交互，**反检测（Anti-Detection）** 通过指纹注入与隐身插件规避自动化检测。本文基于源码梳理这三层的设计与协作方式。

## 1. 会话（Session）：浏览器生命周期的根对象

会话是 Steel 与 Chrome 实例交互的根抽象。每个 Session 对应一个隔离的 Puppeteer/Chromium 进程，并通过 CDP（Chrome DevTools Protocol）暴露 WebSocket 端点，供 Puppeteer、Playwright 或 Selenium 直接接入。

会话控制器由 `api/src/modules/sessions/sessions.controller.ts` 负责，路由定义在 [sessions.routes.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/modules/sessions/sessions.routes.ts)，数据契约由 Zod Schema 强制校验（见 [sessions.schema.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/modules/sessions/sessions.schema.ts)）。v0.5.3-beta 起新增 `onSessionStart`、`onBeforeSessionEnd`、`onAfterSessionEnd` 三个插件钩子，允许在生命周期的精确节点插入自定义逻辑（[Release v0.5.3-beta](https://github.com/steel-dev/steel-browser/releases/tag/v0.5.3-beta)）。

```mermaid
flowchart LR
    A[Client] -->|POST /v1/sessions| B(Sessions Controller)
    B --> C[CDP Service]
    C --> D[Browser Launcher]
    D --> E[Chrome Process]
    C --> F[Plugin Manager]
    F --> G[Fingerprint Plugin]
    F --> H[User Plugin]
    E -->|CDP WS :9223| I[Puppeteer/Playwright]
```

会话上下文（包括 Cookies、`localStorage`、`sessionStorage`、IndexedDB）通过 `api/src/utils/context.ts` 中的 `extractStorageForPage` 提取。该函数利用 CDP 的 `Page.getFrameTree` 与 `DOMStorage` 域，按 origin 与 hostname 聚合存储数据，形成 [context/types.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/services/context/types.ts) 中定义的 `SessionData` 结构，从而支持跨请求的状态保持（README 中所强调的「Session Management」特性）。

## 2. 操作（Actions）：高层页面交互 API

Actions 模块位于 `api/src/modules/actions/`，是对底层 CDP/Puppeteer 调用的高层封装，目标是让 Agent 用最少的请求完成抓取、截图、PDF 生成、搜索等任务。`actions.controller.ts` 与 `actions.routes.ts` 共同定义了以下常用端点（端点路径以 README 示例为准）：

| 端点 | 用途 | 关键参数 |
|------|------|----------|
| `POST /v1/scrape` | 提取页面内容（HTML/Markdown/Readability） | `url`, `delay` |
| `POST /v1/screenshot` | 生成 PNG 截图 | `url`, `fullPage` |
| `POST /v1/pdf` | 导出 PDF | `url` |
| 搜索动作 | 通过搜索引擎查询 | `query` (v0.5.2-beta 新增) |

后端使用 `puppeteer-core@23.6.0`（[api/package.json](https://github.com/steel-dev/steel-browser/blob/main/api/package.json)），并通过 `api/src/utils/scrape/readability.ts` 调用 `defuddle` 库提取主要内容，使用 `pdfToHtml.ts` 解析 PDF 文本流（v0.5.1-beta 引入），使用 `jsonToMarkdown.ts` 处理 JSON 响应。导航逻辑则在 `api/src/utils/casting.ts` 的 `navigatePage` 中实现，支持 `back`、`forward`、`refresh` 与 URL 跳转四种语义。

## 3. 反检测（Anti-Detection）：指纹与隐身插件

反检测能力由 [api/src/services/cdp/plugins/builtin/fingerprint.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/services/cdp/plugins/builtin/fingerprint.ts) 提供，依赖 `fingerprint-generator@2.1.82` 与 `fingerprint-injector@2.1.82` 两个核心包（见 [api/package.json](https://github.com/steel-dev/steel-browser/blob/main/api/package.json)）。插件由 [plugin-manager.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/services/cdp/plugins/core/plugin-manager.ts) 在浏览器启动前统一调度，覆盖 User-Agent、Canvas、AudioContext、WebGL 等数十个指纹维度，并支持用户覆写（v0.4.3-beta 改进插件启动时机与指纹覆写支持）。

⚠️ 已知限制：社区已报告在 Chrome 146 + 固定 1920×1080 分辨率下，`fingerprint-generator@2.1.82` 会抛出 `Failed to generate a consistent fingerprint after 10 attempts`（[#295](https://github.com/steel-dev/steel-browser/issues/295)、[#302](https://github.com/steel-dev/steel-browser/issues/302)），必须临时设置 `SKIP_FINGERPRINT_INJECTION` 才能启动容器。部署到生产前应关注此问题的修复进展。

## 4. 协作与扩展：插件钩子与 CDP

会话、操作、反检测三层并非孤立，而是通过 **插件系统** 与 **CDP 服务** 串联。`onBrowserReady` 自 v0.5.0-beta 起支持 Promise 返回（[#226](https://github.com/steel-dev/steel-browser/releases/tag/v0.5.0-beta)），v0.5.2-beta 引入 disconnect handler override（[#233](https://github.com/steel-dev/steel-browser/releases/tag/v0.5.2-beta)），使自定义反检测逻辑可在浏览器就绪但尚未连接时介入。对于需要连接 Selenium 的场景，`api/src/modules/selenium/selenium.routes.ts` 通过代理转发复用同一份 Session，从而避免重复实现反检测栈。

社区中关于集群与 session affinity 的讨论（[#144](https://github.com/steel-dev/steel-browser/issues/144)）提示：在水平扩展时需保证路由层能将同一 Session 的请求始终转发至持有该 Chrome 进程的工作节点，否则 CDP 端点会失效。

## See Also

- [API 模块总览：会话、Actions、Selenium](https://github.com/steel-dev/steel-browser/wiki)
- [CDP 服务与插件机制](https://github.com/steel-dev/steel-browser/wiki)
- [上下文持久化与反指纹策略](https://github.com/steel-dev/steel-browser/wiki)

---

<a id='page-4'></a>

## 部署、插件开发与故障排除

### 相关页面

相关主题：[项目概述与快速入门](#page-1), [核心功能：会话、操作、反检测](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/steel-dev/steel-browser/blob/main/README.md)
- [api/package.json](https://github.com/steel-dev/steel-browser/blob/main/api/package.json)
- [ui/package.json](https://github.com/steel-dev/steel-browser/blob/main/ui/package.json)
- [repl/package.json](https://github.com/steel-dev/steel-browser/blob/main/repl/package.json)
- [repl/README.md](https://github.com/steel-dev/steel-browser/blob/main/repl/README.md)
- [api/src/utils/schema.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/schema.ts)
- [api/src/utils/requests.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/requests.ts)
- [api/src/utils/scrape/index.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/scrape/index.ts)
- [api/src/utils/scrape/readability.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/scrape/readability.ts)
- [api/src/utils/scrape/jsonToMarkdown.ts](https://github.com/steel-dev/steel-browser/blob/main/api/src/utils/scrape/jsonToMarkdown.ts)
- [api/extensions/recorder/package.json](https://github.com/steel-dev/steel-browser/blob/main/api/extensions/recorder/package.json)
</details>

# 部署、插件开发与故障排除

本页面向希望将 **Steel Browser** 自托管部署、扩展其插件行为或排查常见运行问题的工程师。内容覆盖三条主线：基于官方预构建产物的快速部署路径、`@steel-browser/repl` 与内置扩展的二次开发入口，以及社区中反复出现的指纹注入、版本兼容、CDP 连接等故障的应对方式。所有论断均依据仓库源码与公开 issue。

## 部署路径与产物形态

Steel 将运行时拆分为两个并列的 npm 工作区：**API 服务**（`@steel-browser/api`）与 **调试 UI**（`@steel-browser/ui`）。`api/package.json` 列出了运行 API 所需的全部依赖，包括 `puppeteer-core@23.6.0`、`fingerprint-generator@2.1.82`、`fingerprint-injector@2.1.82`、`proxy-chain`、`mupdf` 与 `duckdb-async` 等，外部必须显式提供 Fastify 5.x 作为 peer 依赖；`ui/package.json` 则声明 Vite + SWC 的前端构建链以及 `@scalar/fastify-api-reference`、`rrweb-player` 等客户端资源。

官方 README 推荐三种部署方式：

| 方式 | 入口 | 备注 |
| --- | --- | --- |
| GHCR 预构建镜像 | `ghcr.io/steel-dev/steel-browser` | 同时包含 API + UI，暴露 `3000` 与 `9223` 端口 |
| Railway 一键部署 | `railway.app/deploy/steelbrowser` | 适合快速公网演示 |
| Render 一键部署 | `render.com/deploy` | 与 Railway 类似，使用 Render Blueprint |

本地 Docker 启动命令示例（资料来源：[README.md](https://github.com/steel-dev/steel-browser/blob/main/README.md)）：

```bash
docker run -p 3000:3000 -p 9223:9223 ghcr.io/steel-dev/steel-browser
```

启动后可通过 `http://0.0.0.0:3000/documentation` 查看由 `@scalar/fastify-api-reference` 渲染的 OpenAPI 文档。

## 插件与扩展开发

Steel 的可扩展面主要由三类入口组成：会话生命周期钩子、REPL 工作区以及内置 `recorder` 扩展。

**会话生命周期钩子**：根据 v0.5.3-beta 的发布说明（[Release v0.5.3-beta](https://github.com/steel-dev/steel-browser/releases/tag/v0.5.3-beta)），新增了 `onSessionStart`、`onBeforeSessionEnd`、`onAfterSessionEnd` 三个插件钩子，用于在会话建立前后插入自定义逻辑。`api/src/utils/schema.ts` 暴露了基于 Zod 的 JSON Schema 构建工具，开发者可以借此为自定义配置项生成 OpenAPI 描述，从而让外部 API 客户端获得类型提示。

**REPL 工作区**：`repl/package.json` 声明仅依赖 `puppeteer-core@^24.2.0` 与 `tsx`，并要求 Node ≥ 22，便于直接连接远端 CDP 调试现有会话。`repl/README.md` 给出的标准流程是：先确保 Steel Browser 已在本地或远端运行，再执行 `npm start` 让 `src/script.ts` 通过 WebSocket 连接到 CDP 端点（默认 `ws://localhost:9223`），随后即可像普通 Puppeteer 脚本一样驱动浏览器。

**内置扩展目录**：`api/extensions/recorder/package.json` 是一个独立的 webpack 构建单元，依赖 `rrweb@^2.0.0-alpha.4` 与 `@rrweb/packer@^2.0.0-alpha.4`，用于将会话录制为 rrweb 事件流。开发者可以仿照该目录结构创建新扩展，并在主 API 中按需装载。

```mermaid
flowchart LR
  Client[客户端脚本] -->|REST| API[Steel API]
  API -->|CDP| Chrome[Chromium 实例]
  API -->|加载| Recorder[recorder 扩展]
  API -->|触发| Hooks[onSessionStart 等钩子]
  Hooks --> Plugin[自定义插件]
  Plugin --> API
```

## 抓取与请求工具集

API 在 `api/src/utils/scrape/index.ts` 中统一对外暴露四类工具：`cleanHtml`、`getDefuddleContent`、`isJsonContentType`/`jsonToMarkdown` 与 `stripBase64Images`。其中 `getDefuddleContent`（`api/src/utils/scrape/readability.ts`）使用 Defuddle 提取正文，并在字数低于阈值（`MIN_EXTRACTED_WORDS = 50`）时切换到宽松选择器回退；`jsonToMarkdown`（`api/src/utils/scrape/jsonToMarkdown.ts`）则把 `application/json` 响应包入三反引号代码块，方便 LLM 直接消费。

请求侧，`api/src/utils/requests.ts` 提供 `isHostBlocked`、`compileUrlPatterns` 与 `isUrlMatchingPatterns` 三个纯函数，用于在会话配置中实现 host 白/黑名单与 URL 通配符过滤——这通常与代理链结合使用，避免对外暴露的内网地址被访问。

## 常见故障与排查

社区中反馈最频繁的三类问题及其应对方式如下：

1. **指纹生成失败**。issue #295 与 #302 都报告了 `fingerprint-generator@2.1.82` 在 Chrome 146、固定分辨率 `1920x1080` 组合下抛出 `Failed to generate a consistent fingerprint after 10 attempts`，导致浏览器启动失败、容器变为 unhealthy。临时缓解是设置环境变量 `SKIP_FINGERPRINT_INJECTION=true`，等待上游 `fingerprint-generator` 修复后再恢复（资料来源：[Issue #295](https://github.com/steel-dev/steel-browser/issues/295)、[Issue #302](https://github.com/steel-dev/steel-browser/issues/302)）。

2. **`npm run dev` 报 `File is not defined`**。issue #230 显示 `undici` 在某些 Node 版本下会因缺少全局 `File` 而报错。仓库对 `cross-spawn` 与 `tar-fs` 已写入 `overrides`（见 `api/package.json`），遇到类似兼容性错误时，建议显式安装 Node ≥ 22 并清理 `node_modules` 后重新安装。

3. **集群与请求路由**。issue #144 询问如何实现会话亲和（session affinity），即把同一会话的请求始终路由到持有该 Chrome 实例的节点。仓库目前未提供开箱即用的集群实现，需要在外部负载均衡层基于 `sessionId` 做一致性哈希，或将单实例横向扩展为独立租户。

4. **文档缺口**。issue #123 指出部分高级特性（自定义插件钩子、代理链配置、`optimizeBandwidth` 标志等）缺乏细节说明；建议结合本仓库 `docs/` 目录（若存在）、官方 `docs.steel.dev` 以及源码注释交叉验证。

5. **安全披露**。issue #311 记录了与 VulnCheck 协同披露的 CVE 流程。若在自托管实例中发现异常行为，建议通过 GitHub Security Advisories 渠道提交，而非公开讨论。

排错时的最小检查清单：确认镜像版本与 `fingerprint-generator` 版本组合、确认 CDP 端口 `9223` 在防火墙中开放、确认 `optimizeBandwidth` 与 `SKIP_FINGERPRINT_INJECTION` 等开关符合预期，并通过 `/documentation` 页面验证 API 协议是否一致。

## See Also

- 官方 API 文档：https://docs.steel.dev/api-reference
- 协调披露流程：https://github.com/steel-dev/steel-browser/issues/311
- 集群与会话亲和讨论：https://github.com/steel-dev/steel-browser/issues/144
- v0.5.3-beta 发布说明：https://github.com/steel-dev/steel-browser/releases/tag/v0.5.3-beta

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：steel-dev/steel-browser

摘要：发现 11 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：[BUG] Fingerprint generation fails for Chrome 146 at fixed 1920x1080, forcing SKIP_FINGERPRINT_INJECTION。

## 1. 安装坑 · 来源证据：[BUG] Fingerprint generation fails for Chrome 146 at fixed 1920x1080, forcing SKIP_FINGERPRINT_INJECTION

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Fingerprint generation fails for Chrome 146 at fixed 1920x1080, forcing SKIP_FINGERPRINT_INJECTION
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/steel-dev/steel-browser/issues/302 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：[BUG] Self-hosted steel-browser-api fails with "Failed to generate a consistent fingerprint after 10 attempts"

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Self-hosted steel-browser-api fails with "Failed to generate a consistent fingerprint after 10 attempts"
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/steel-dev/steel-browser/issues/295 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：[QUESTION] how to fix this bug ,npm run dev

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[QUESTION] how to fix this bug ,npm run dev
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/steel-dev/steel-browser/issues/230 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 依赖 Docker 环境

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

## 5. 能力坑 · 能力判断依赖假设

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

## 6. 维护坑 · 维护活跃度未知

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

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

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

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

## 9. 安全/权限坑 · 来源证据：Coordinated Vulnerability Disclosure - steel-browser

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Coordinated Vulnerability Disclosure - steel-browser
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/steel-dev/steel-browser/issues/311 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

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

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

<!-- canonical_name: steel-dev/steel-browser; human_manual_source: deepwiki_human_wiki -->