简介

Camofox Browser 是一个专为 AI 代理设计的反检测浏览器自动化服务器，基于 Firefox 内核（Camoufox 引擎）构建。该项目提供了一套完整的浏览器控制 API，支持无头浏览器操作、页面交互、内容提取等自动化任务，同时集成了多项反检测技术，能够有效绕过 Google Captcha 等常见的反爬虫机制。

Camofox Browser 的核心价值在于为 AI 代理提供稳定、可靠的浏览器控制能力，使用户能够在不触发网站反爬虫机制的情况下完成网页浏览、数据抓取、表单填写等操作。资料来源：AGENTS.md

系统架构

Camofox Browser 采用模块化架构设计，主要包含以下几个核心模块：

graph TD
    A[客户端请求] --> B[server.js 路由层]
    B --> C{请求类型}
    C -->|Tab 操作| D[Tab 管理模块]
    C -->|Session 操作| E[Session 管理模块]
    C -->|Browser 操作| F[Browser 管理模块]
    C -->|内容提取| G[Extract 模块]
    D --> H[Camoufox 引擎]
    E --> H
    F --> H
    G --> H
    H --> I[浏览器实例]
    I --> J[网页内容]
    
    K[插件系统] --> H
    L[事件系统] --> B
    M[OpenAPI 文档] --> B

核心模块职责

资料来源：server.js, lib/openapi.js, lib/extract.js

技术栈与依赖

Camofox Browser 使用以下核心技术栈：

graph LR
    A[运行时] --> B[Node.js]
    A --> C[Camoufox 内核]
    B --> D[Express.js]
    B --> E[Playwright API]
    C --> F[Firefox]
    
    G[API 文档] --> H[swagger-jsdoc]
    G --> I[swagger-stripey]

主要技术依赖

API 系统

OpenAPI 规范

Camofox Browser 采用 OpenAPI 3.0.3 规范管理 API。所有路由通过 @openapi JSDoc 注释自动生成规范文件，文档可通过 GET /docs 访问 API 的 Swagger UI 界面。资料来源：lib/openapi.js:1-30

API 标签分类

API 按功能划分为以下标签组：

资料来源：AGENTS.md

主要 API 端点

资料来源：server.js

会话管理

用户隔离机制

Camofox Browser 通过 userId 参数实现用户间的 cookies 和存储隔离，确保不同用户的数据完全独立。资料来源：AGENTS.md

graph TD
    A[用户请求] --> B{userId 验证}
    B -->|有效| C[获取/创建 Session]
    B -->|无效| D[返回 400 错误]
    C --> E{Session 存在?}
    E -->|是| F[复用现有 Session]
    E -->|否| G[创建新 Session]
    F --> H[执行操作]
    G --> H
    H --> I[Session 超时检查]
    I -->|30分钟无活动| J[销毁 Session]

会话配置

事件系统

Camofox Browser 内置完整的事件系统，支持同步和异步两种事件模式。资料来源：lib/plugins.js

事件类型分类

#### Tab 生命周期事件

#### 内容事件

#### 输入事件

事件钩子模式

事件系统支持两种模式：

1. 异步钩子（events.emitAsync()）：用于 browser:launching、session:creating、session:created、session:destroyed，服务器会等待所有监听器完成后再继续执行
2. 同步事件（events.emit()）：用于其他所有事件，采用即发即忘模式

资料来源：AGENTS.md

插件系统

Camofox Browser 支持插件扩展，通过事件钩子机制允许插件在关键生命周期节点执行自定义逻辑。资料来源：scripts/plugin.js

插件管理命令

插件安装来源

• Git URL：git:github.com/user/repo 或 https://github.com/user/repo
• 本地路径：./path/to/local/plugin

资料来源：scripts/plugin.js

崩溃报告系统

Camofox Browser 内置 lib/reporter.js 模块，负责收集和上报崩溃及事件循环停滞信息。资料来源：lib/reporter.js

报告的环境信息

已知问题：事件循环停滞

社区反馈显示，部分用户在运行过程中会遇到事件循环停滞（Event loop stalled）问题：

受影响版本包括 v1.6.0、v1.7.2、v1.7.3，主要发生在 macOS 和 Linux 平台。该问题会导致浏览器操作无响应，但不会造成数据丢失。资料来源：社区反馈 Issue #4860

配置与运行

环境变量

运行方式

Camofox Browser 支持多种运行方式：

# 从源码运行
npm start
# 或使用运行脚本
./run.sh

# 从 npm 安装运行
npx @askjo/camofox-browser

# 全局安装
npm install -g @askjo/camofox-browser
camofox-browser

资料来源：AGENTS.md, 社区公告

Docker 部署

Docker 容器支持通过环境变量配置，v1.10 版本可通过环境变量正确启用 VNC，但 v1.11 版本存在回归问题。资料来源：Issue #4314

测试框架

资料来源：AGENTS.md

Schema 验证

内容提取模块提供了 Schema 验证功能，确保提取的数据符合预定义结构。资料来源：lib/extract.js

支持的数据类型

验证规则

• 顶层 schema 必须为 type: object
• 每个属性必须定义为对象格式
• 属性可指定 type，未指定时默认为字符串

快速开始

``bash npm install ``

1. 安装依赖

``bash npm start ``

1. 启动服务

``bash curl http://localhost:9377/health ``

1. 验证健康状态

``bash curl -X POST http://localhost:9377/tabs \ -H "Content-Type: application/json" \ -d '{"userId": "agent1"}' ``

1. 创建标签页并导航

``` http://localhost:9377/docs

1. 访问 API 文档

核心组件概览

graph TD
    Client["AI 代理客户端"]
    Server["Express HTTP Server<br/>(port 9377)"]
    Browser["Camoufox Browser<br/>(Firefox 核心)"]
    Sessions["Session Manager"]
    Plugins["Plugin System"]
    Events["Event Emitter"]
    Reporter["Crash/Hang Reporter"]
    
    Client -->|"REST API"| Server
    Server --> Browser
    Server --> Sessions
    Server --> Events
    Sessions --> Browser
    Plugins --> Server
    Events --> Plugins
    Reporter --> Events
    
    subgraph "server.js"
        Server
        Sessions
        Events
    end
    
    subgraph "lib/"
        Plugins
        Reporter
    end

组件职责

服务器架构

技术栈

• 运行环境: Node.js (v22+)
• Web 框架: Express.js
• 浏览器引擎: Camoufox (基于 Firefox 的反检测浏览器)
• API 规范: OpenAPI 3.0.3 (通过 swagger-jsdoc 自动生成)
• 文档 UI: swagger-stripey (三栏式界面)

架构层次

graph LR
    subgraph "表现层"
        OpenAPI["OpenAPI Docs UI<br/>/docs"]
        JSON["/openapi.json"]
    end
    
    subgraph "路由层"
        Tabs["Tabs Routes<br/>/tabs/:tabId/*"]
        Sessions["Sessions Routes<br/>/sessions/:userId/*"]
        Browser["Browser Routes<br/>/browser/*"]
        System["System Routes<br/>/health, /metrics"]
    end
    
    subgraph "业务逻辑层"
        Auth["authMiddleware()"]
        Limits["withUserLimit()"]
        TabLock["withTabLock()"]
        Timeout["withTimeout()"]
    end
    
    subgraph "浏览器控制层"
        Launcher["Browser Launcher"]
        Context["Browser Contexts"]
        Page["Pages/Tabs"]
    end
    
    OpenAPI -->|"spec"| JSON
    JSON --> Tabs
    JSON --> Sessions
    JSON --> Browser
    JSON --> System
    
    Tabs --> Auth
    Sessions --> Auth
    Tabs --> Limits
    Tabs --> TabLock
    Tabs --> Timeout
    TabLock --> Page
    Limits --> Context
    Context --> Launcher

API 路由分类

浏览器引擎架构

Camoufox 启动流程

sequenceDiagram
    participant Server as server.js
    participant Launcher as lib/launcher.js
    participant Browser as Camoufox Browser
    participant Context as Browser Context
    
    Server->>Launcher: ensureBrowser()
    Launcher->>Launcher: 检查浏览器实例
    alt 浏览器未启动或断开
        Launcher->>Launcher: 检测环境 (Docker/WSL2/Fly.io)
        Launcher->>Browser: launchBrowser(options)
        Browser-->>Launcher: browser instance
        Launcher-->>Server: 返回浏览器引用
    end
    
    Server->>Context: createBrowserContext(userId)
    Context-->>Server: context with独立存储

浏览器上下文隔离

每个用户会话 (userId) 拥有独立的浏览器上下文，实现以下隔离：

资料来源：AGENTS.md:60-75

会话管理架构

会话生命周期

stateDiagram-v2
    [*] --> Created: 创建新用户会话
    Created --> Active: 首次访问
    Active --> Active: 持续操作
    Active --> Idle: 30分钟无活动
    Idle --> Active: 恢复使用
    Idle --> Expired: 超时
    Expired --> [*]
    Active --> [*]: 主动销毁

会话数据结构

sessions = Map<userId, {
  id: string,
  lastAccess: number,      // 时间戳
  tabGroups: Map<sessionKey, Set<tabId>>,
  context: BrowserContext,
  ...
}>

标签页管理

graph TD
    TabGroup["TabGroup<br/>(sessionKey)"]
    Tab1["Tab e1"]
    Tab2["Tab e2"]
    Tab3["Tab e3"]
    
    TabGroup --> Tab1
    TabGroup --> Tab2
    TabGroup --> Tab3
    
    TabState["TabState"]
    TabState --> Page["page (Playwright)"]
    TabState --> NavigateAbort["navigateAbort"]
    TabState --> ToolCalls["toolCalls"]
    TabState --> ConsecutiveTimeouts["consecutiveTimeouts"]
    TabState --> ConsecutiveFailures["consecutiveFailures"]
    
    Tab1 --> TabState
    Tab2 --> TabState
    Tab3 --> TabState

事件系统架构

事件分类

Mutating Hooks

Mutating hooks 允许插件在操作前修改配置对象：

// 修改 Xvfb 分辨率 (用于 VNC 插件)
events.on('browser:launching', ({ options }) => {
  options.virtual_display_resolution = '1920x1080';
});

资料来源：lib/plugins.js:32-50

插件系统架构

插件管理器

graph LR
    subgraph "scripts/plugin.js"
        Install["install 命令"]
        Remove["remove 命令"]
        List["list 命令"]
    end
    
    subgraph "lib/plugins.js"
        Load["插件加载"]
        Hooks["事件钩子注册"]
        Deps["依赖安装"]
    end
    
    Install --> Load
    Remove --> Load
    Load --> Hooks
    Load --> Deps

插件安装流程

node scripts/plugin.js install <source>
# source 支持:
#   - git:github.com/user/repo
#   - https://github.com/user/repo
#   - ./path/to/local/plugin

插件生命周期钩子

错误处理与监控

健康检查端点

GET /health 返回系统状态：

{
  "ok": true,
  "engine": "camoufox",
  "browserConnected": true,
  "browserRunning": true,
  "activeTabs": 5,
  "activeSessions": 3,
  "consecutiveFailures": 0,
  "memory": {
    "rssMb": 42,
    "heapUsedMb": 66,
    "nativeMemMb": 36
  }
}

资料来源：server.js:150-175

崩溃/挂起报告

lib/reporter.js 实现自动上报机制：

社区问题关联: 社区中存在多个 stuck:event-loop 问题报告（#4863, #4862, #4860 等），显示 Event Loop 阻塞是已知问题，用户应注意长时运行任务对事件循环的影响。

速率限制

数据提取验证

lib/extract.js 提供 schema 验证功能：

validateSchema(schema) → { ok: boolean, error?: string }

API 文档自动生成

OpenAPI 规范生成流程

graph TD
    JSDoc["@openapi JSDoc 注释"]
    swagger["swagger-jsdoc"]
    spec["openapi.json"]
    UI["swagger-stripey UI"]
    Docs["/docs"]
    JSON["/openapi.json"]
    
    JSDoc --> swagger
    swagger --> spec
    spec --> UI
    spec --> JSON
    UI --> Docs
    JSON --> JSON

JSDoc 注释规范

/**
 * @openapi
 * /tabs/{tabId}/click:
 *   post:
 *     tags: [Interaction]
 *     summary: Click an element
 *     parameters:
 *       - name: tabId
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [userId]
 *     responses:
 *       200:
 *         description: Click result.
 */
app.post('/tabs/:tabId/click', async (req, res) => { ... });

资料来源：AGENTS.md:15-45

环境适配

平台检测

服务器自动检测运行环境并调整配置：

环境变量配置

社区问题关联: Docker VNC 回归问题（#4314）表明环境变量检测在 1.11 版本中存在变化，用户遇到 VNC 无法从环境变量激活的情况。

安全性

中间件链

graph LR
    Request["HTTP Request"]
    Auth["authMiddleware()"]
    RateLimit["速率限制"]
    ErrorHandler["错误处理"]
    Route["Route Handler"]
    
    Request --> Auth
    Auth --> RateLimit
    RateLimit --> ErrorHandler
    ErrorHandler --> Route

认证机制

性能优化

内存管理

健康检查返回内存指标：

memory: {
  rssMb: 42,        // 进程总内存
  heapUsedMb: 66,   // V8 堆使用
  nativeMemMb: 36   // 原生内存 (RSS - Heap)
}

并发控制

扩展阅读

• API 参考文档 - 完整 API 端点说明
• 插件开发指南 - 如何开发自定义插件
• 部署指南 - Docker、Fly.io 部署配置
• 故障排除 - 常见问题与解决方案

项目概述

camofox-browser 是一个面向 AI Agent 的反检测浏览器自动化服务器，提供无头浏览器控制、辅助功能快照、元素引用、会话隔离、Cookie 导入、代理轮换和结构化日志等功能。服务默认监听端口 9377。

系统要求

注意：社区反馈在 WSL2 环境下运行可能出现屏幕闪烁问题（每 3 分钟一次），这是已知问题，暂无解决方案。

安装方式

方式一：NPM 全局安装（推荐）

从 v1.11.2 起，npm 包直接安装可执行文件：

# 临时运行
npx @askjo/camofox-browser

# 全局安装
npm install -g @askjo/camofox-browser
camofox-browser

全局安装后，默认端口为 9377，可通过相同环境变量配置。

方式二：Docker 安装

Docker 镜像提供开箱即用的环境，预装默认插件依赖：

# 运行最新版本
docker run --rm -it -p 9377:9377 \
  ghcr.io/jo-inc/camofox-browser:latest

# 带 VNC 支持（需 v1.10.x，v1.11 存在回归问题）
docker run --rm -it -p 9377:9377 -p 6080:6080 \
  -e ENABLE_VNC=1 -e VNC_BIND=0.0.0.0 \
  ghcr.io/jo-inc/camofox-browser:1.10.0

# 验证 VNC 激活
curl -4I localhost:6080
# HTTP/1.1 200 OK

已知问题：v1.11 版本中 VNC 无法通过环境变量激活，请关注 Issue #4314。

方式三：源码安装

# 克隆仓库
git clone https://github.com/jo-inc/camofox-browser.git
cd camofox-browser

# 安装依赖
npm install

# 构建 camoufox 引擎
npm run build:camoufox

构建完成后，使用以下命令启动：

npm start
# 或
./run.sh

快速开始

基本工作流程

graph TD
    A[启动服务] --> B{安装方式}
    B -->|NPM| C[camofox-browser]
    B -->|Docker| D[docker run]
    B -->|源码| E[npm start]
    C --> F[服务就绪<br/>localhost:9377]
    D --> F
    E --> F
    F --> G[创建会话]
    G --> H[开启 Tab]
    H --> I[导航到网页]
    I --> J[获取快照]
    J --> K[交互操作]

首次使用示例

1. 启动服务

npm start
# 输出: Server started on port 9377

2. 创建新 Tab 并导航

# 创建 Tab
curl -X POST http://localhost:9377/tabs \
  -H "Content-Type: application/json" \
  -d '{"userId": "agent1", "sessionKey": "task1"}'

# 导航到 Google
curl -X POST http://localhost:9377/tabs/{tabId}/navigate \
  -H "Content-Type: application/json" \
  -d '{"userId": "agent1", "macro": "@google_search", "query": "test"}'

3. 获取页面快照

curl "http://localhost:9377/tabs/{tabId}/snapshot?userId=agent1"

返回元素引用（如 e1, e2），用于后续交互。

4. 执行交互操作

# 点击元素
curl -X POST http://localhost:9377/tabs/{tabId}/click \
  -H "Content-Type: application/json" \
  -d '{"userId": "agent1", "ref": "e1"}'

# 输入文本
curl -X POST http://localhost:9377/tabs/{tabId}/type \
  -H "Content-Type: application/json" \
  -d '{"userId": "agent1", "ref": "e2", "text": "hello world"}'

环境变量配置

配置方式：

• Docker: -e VAR=value
• 源码: 在 .env 文件中设置

插件管理

camofox-browser 支持插件扩展：

# 安装插件（从 Git 或本地路径）
node scripts/plugin.js install git:github.com/user/repo
node scripts/plugin.js install ./path/to/local/plugin

# 列出已安装插件
node scripts/plugin.js list

# 移除插件
node scripts/plugin.js remove <plugin-name>

安装插件后需重启服务。

验证安装

运行测试套件

# 所有测试（单元 + E2E + 插件）
npm test

# 仅插件测试
npm run test:plugins

# E2E 测试
npm run test:e2e

# 实时 Google 测试
npm run test:live

健康检查

curl http://localhost:9377/health
# 或访问 API 文档
curl http://localhost:9377/docs

常见问题

下一步

• API 参考 - 完整的 REST API 文档
• 插件开发 - 开发自定义插件
• 事件系统 - 订阅和处理浏览器事件

核心引擎：Camoufox

camofox-browser 默认使用 Camoufox 作为底层浏览器引擎。Camoufox 是基于 Firefox 的反检测浏览器，专门针对网站反爬虫和机器人检测机制进行了优化。

技术特点

资料来源：AGENTS.md:运行引擎

事件循环健康监测

反检测机制不仅包括浏览器层面的防护，还包含服务器端的性能监控。当事件循环阻塞超过阈值时，系统会自动报告问题。

阻塞检测机制

graph TD
    A[事件循环监控] --> B{阻塞时间 > 阈值?}
    B -->|是| C[触发 stuck:event-loop 报告]
    B -->|否| D[继续正常监控]
    C --> E[匿名化错误数据]
    E --> F[上报至 crash-reporter]
    F --> G[创建 GitHub Issue]

阈值配置

社区反馈表明，在高负载场景下（如长时间运行、大量并发标签页），事件循环可能出现 17s 至 74s 的阻塞情况。资料来源：社区 Issue #4863

会话隔离机制

camofox-browser 通过 userId 实现用户间的 cookies 和存储隔离，这是防止检测的重要手段。

隔离策略

会话生命周期

资料来源：lib/plugins.js:事件定义

浏览器上下文管理

上下文选项动态修改

通过 session:creating 钩子，插件可以在浏览器上下文创建前修改配置：

events.on('session:creating', ({ userId, contextOptions }) => {
  // 修改 contextOptions
});

上下文创建流程

graph TD
    A[browser:launching 钩子] --> B[session:creating 钩子]
    B --> C[async 插件处理完成]
    C --> D[创建浏览器上下文]
    D --> E[session:created 事件]
    E --> F[上下文就绪]

标签页级隔离

每个标签页在独立的页面实例中运行，通过 tabId 进行标识和管理。

标签页事件流

资料来源：lib/plugins.js:标签页事件

用户代理伪装

camofox-browser 通过以下方式伪装用户行为：

交互操作伪装

所有交互操作都会记录到 tabState.toolCalls，用于统计和监控。

点击操作的延迟预算机制

camofox-browser 实现了点击延迟预算机制，防止操作过快被检测：

const remainingBudget = () => Math.max(0, budget - elapsed);

资料来源：server.js:点击处理

插件扩展机制

camofox-browser 提供插件系统，允许用户扩展反检测能力。

插件命令

# 安装插件
node scripts/plugin.js install <git-url|local-path>

# 移除插件
node scripts/plugin.js remove <name>

# 列出插件
node scripts/plugin.js list

插件安装来源格式

资料来源：scripts/plugin.js:插件命令

插件钩子类型

变异钩子示例

// 修改 Xvfb 分辨率（用于 VNC 插件）
events.on('browser:launching', ({ options }) => {
  options.virtual_display_resolution = '1920x1080';
});

VNC 插件与反检测

VNC 插件允许用户实时查看浏览器画面，这在调试反检测行为时非常有用。

环境变量配置

Docker 部署

docker run --rm -it -p 9377:9377 -p 6080:6080 \
  -e ENABLE_VNC=1 -e VNC_BIND=0.0.0.0 \
  ghcr.io/jo-inc/camofox-browser:1.10.0

注意：社区反馈 v1.11 版本存在 VNC 环境变量激活回归问题。资料来源：社区 Issue #4314

健康状态监控

camofox-browser 提供健康检查端点，用于监控反检测机制的运行状态。

健康检查端点

GET /health

响应示例

{
  "ok": true,
  "engine": "camoufox",
  "browserConnected": true,
  "browserRunning": true,
  "activeTabs": 5,
  "activeSessions": 2,
  "consecutiveFailures": 0,
  "memory": {
    "rssMb": 183,
    "heapUsedMb": 66,
    "nativeMemMb": 117
  }
}

状态说明

反检测限制与已知问题

Cloudflare Turnstile 挑战

当前版本的反检测机制在处理 Cloudflare Turnstile 挑战时存在限制：

Cloudflare Turnstile challenges (used by sites like GunBroker, bet365, and others) cannot be bypassed with the current camofox-browser toolset even when using a residential proxy IP.

资料来源：社区 Issue #40

事件循环阻塞

在高负载长时间运行的场景中，事件循环可能出现显著阻塞：

资料来源：社区 Issue #4860、社区 Issue #4483

最佳实践

1. 合理的操作延迟

在模拟人类行为时，应使用合理的操作间隔：

• 页面加载后等待 1-3 秒再进行交互
• 点击之间添加随机延迟
• 避免连续快速操作

2. 会话管理

• 为不同任务使用不同的 userId
• 定期清理过期会话
• 监控活跃会话数量

3. 插件扩展

• 使用 VNC 插件调试反检测行为
• 通过 session:creating 钩子自定义上下文选项
• 避免安装来源不明的插件

4. 监控告警

• 定期检查 /health 端点
• 关注 consecutiveFailures 指标
• 配置事件循环阻塞阈值告警

相关资源

• OpenAPI 文档 - 完整的 API 参考
• Camoufox 官方文档 - 底层浏览器引擎
• 插件开发指南 - 如何开发自定义插件

概述

camofox-browser 的会话管理是整个自动化浏览器的核心子系统，负责管理浏览器上下文（Browser Context）、标签页生命周期、用户资源限制以及会话级别的持久化状态。每一个会话（Session）对应一个独立的浏览器上下文，提供了完整的隔离环境，支持并发多用户访问和独立的代理配置。

会话管理器通过内存中的 Map 结构维护活跃会话，并结合事件驱动架构实现插件扩展和状态同步。

核心架构

会话存储结构

camofox 使用 JavaScript Map 数据结构存储会话实例：

const sessions = new Map();

每个会话对象包含以下关键属性：

资料来源：server.js

会话通过 normalizeUserId() 函数规范化用户 ID，确保大小写不敏感的查询一致性：

const session = sessions.get(normalizeUserId(userId));

会话与标签页关系

┌─────────────────────────────────────────┐
│           Session (userId)               │
│  ┌─────────────────────────────────┐   │
│  │     TabGroup (listItemId)        │   │
│  │  ┌───────┐ ┌───────┐ ┌───────┐ │   │
│  │  │ Tab 1 │ │ Tab 2 │ │ Tab N │ │   │
│  │  └───────┘ └───────┘ └───────┘ │   │
│  └─────────────────────────────────┘   │
│  lastAccess: timestamp                 │
│  contextOptions: {...}                 │
└─────────────────────────────────────────┘

会话与标签页的层级关系：

• 会话层：管理用户级别的配置、代理、Cookie 和资源限制
• 分组层：通过 listItemId 组织相关标签页
• 标签页层：独立的页面实例，包含 page、tabState 等

资料来源：server.js（标签页删除逻辑）

会话生命周期

创建流程

会话创建通过 POST /sessions 路由触发，流程如下：

graph TD
    A[接收创建会话请求] --> B[验证 userId]
    B --> C{会话已存在?}
    C -->|是| D[返回现有会话]
    C -->|否| E[分配新会话 ID]
    E --> F[初始化 contextOptions]
    F --> G[触发 session:creating 事件]
    G --> H[调用 browser.newContext]
    H --> I[触发 session:created 事件]
    I --> J[注册到 sessions Map]
    J --> K[设置活跃会话指标]

关键事件钩子：

资料来源：lib/plugins.js 资料来源：AGENTS.md

销毁流程

会话销毁支持显式和隐式两种方式：

显式销毁：通过 DELETE /sessions/:userId 显式关闭会话 隐式销毁：会话空闲超时后自动清理

// 关闭标签页时清理分组
if (found.group.size === 0) {
  session.tabGroups.delete(found.listItemId);
}

资料来源：server.js

过期与清理机制

系统通过 session:expired 事件通知会话过期：

// 事件载荷
{ userId, idleMs }

过期条件：

• 会话在配置的空闲时间（IDLE_TIMEOUT_MS）内无访问
• lastAccess 时间戳距离当前时间超过阈值

标签页管理

标签页数据结构

每个标签页在会话中以 tabId 为键存储，包含：

{
  tabId: string,
  tabState: {
    page: Page,           // Playwright Page 对象
    toolCalls: number,    // 工具调用计数
    consecutiveTimeouts: number,    // 连续超时次数
    consecutiveFailures: number,    // 连续失败次数
    navigateAbort: AbortController, // 导航取消控制器
  },
  group: Set,      // 同组标签页集合
  listItemId: string, // 分组标识
}

资料来源：server.js

标签页锁定机制

为防止并发操作冲突，系统实现了标签页级别的锁机制：

await withTabLock(tabId, async () => {
  await tabState.page.keyboard.press(key);
});

锁队列深度通过 refreshTabLockQueueDepth() 更新，用于监控。

标签页删除

删除标签页时执行完整清理：

if (found.tabState.navigateAbort) found.tabState.navigateAbort.abort();
await clearTabDownloads(found.tabState);
await safePageClose(found.tabState.page);
found.group.delete(req.params.tabId);
tabLocks.get(req.params.tabId)?.drain();
tabLocks.delete(req.params.tabId);

事件系统

会话事件

资料来源：AGENTS.md

标签页事件

资料来源：lib/plugins.js

异步钩子

以下事件通过 events.emitAsync() 触发，系统会等待所有监听器完成：

• browser:launching
• session:creating
• session:created
• session:destroyed

// 示例：修改浏览器启动参数
events.on('browser:launching', ({ options }) => {
  options.virtual_display_resolution = '1920x1080';
});

资料来源：AGENTS.md

用户限制与配额

用户级限流

系统通过 withUserLimit() 函数实现用户级别的并发限制：

const result = await withUserLimit(userId, () => withTimeout(...));

标签页操作计数器

每个标签页维护操作计数器，用于检测异常行为：

tabState.toolCalls++;
tabState.consecutiveTimeouts = 0;
tabState.consecutiveFailures = 0;

连续失败/超时计数达到阈值后会触发告警。

Cookie 与存储管理

Cookie 导入

通过 session:cookies:import 事件导入 Cookie：

events.on('session:cookies:import', ({ userId, count }) => {
  console.log(`Imported ${count} cookies for user ${userId}`);
});

存储状态导出

会话级别的存储状态可通过 session:storage:export 事件导出：

events.on('session:storage:export', ({ userId }) => {
  // 导出 localStorage, sessionStorage 等
});

健康检查与会话状态

健康检查端点

GET /health 返回会话相关的健康指标：

{
  "ok": true,
  "engine": "camoufox",
  "browserConnected": true,
  "browserRunning": true,
  "activeTabs": 5,
  "activeSessions": 2,
  "consecutiveFailures": 0,
  "memory": {
    "rssMb": 120,
    "heapUsedMb": 66,
    "nativeMemMb": 54
  }
}

资料来源：server.js

恢复状态

系统支持恢复模式，当检测到问题时返回 503 状态：

if (healthState.isRecovering) {
  return res.status(503).json({ ok: false, recovering: true });
}

插件集成

插件与会话交互

插件可以通过事件系统与会话管理深度集成：

// 监听所有会话标签页事件
events.on('tab:navigated', ({ userId, tabId, url, prevUrl }) => {
  // 记录导航历史
});

插件命令

通过 scripts/plugin.js 管理会话相关的插件：

# 安装插件
node scripts/plugin.js install git:github.com/user/repo

# 列出已安装插件
node scripts/plugin.js list

# 移除插件
node scripts/plugin.js remove <name>

常见问题与排查

Event Loop 阻塞

社区反馈中频繁出现的 stuck:event-loop 问题：

会话泄露

如果 activeSessions 持续增长但不下降：

1. 检查 session:expired 事件是否正常触发
2. 验证空闲超时配置
3. 检查客户端是否正确调用会话销毁接口

标签页无法关闭

关闭标签页时需要完整清理：

• 中止导航控制器
• 清除下载记录
• 安全关闭页面对象
• 清理标签页锁

配置参考

源码索引

概述

camofox-browser 提供了一套完整的 RESTful API，用于控制反检测浏览器自动化引擎。API 基于 OpenAPI 3.0.3 规范构建，支持通过标准 HTTP 请求与浏览器实例进行交互，实现页面导航、元素操作、内容提取、数据抓取等功能。

API 的核心设计理念是为 AI 代理提供可靠、可观测的浏览器控制接口。每个 API 端点都集成了以下特性：

• 会话隔离：通过 userId 参数实现多用户资源隔离
• 并发控制：使用 Tab 锁机制防止竞态条件
• 错误处理：统一的错误响应格式和超时保护
• 事件驱动：完整的插件事件系统用于扩展和监控

资料来源：lib/openapi.js:1-30

API 端点分类

API 端点按功能分为以下标签组：

资料来源：AGENTS.md:80-90

系统端点

健康检查

GET /health

返回服务器健康状态和浏览器运行信息。

响应示例：

{
  "ok": true,
  "engine": "camoufox",
  "browserConnected": true,
  "browserRunning": true,
  "activeTabs": 5,
  "activeSessions": 3,
  "consecutiveFailures": 0,
  "memory": {
    "rssMb": 42,
    "heapUsedMb": 66,
    "nativeMemMb": 12
  }
}

当服务器处于恢复状态时，返回 503 状态码：

{
  "ok": false,
  "recovering": true
}

资料来源：server.js:health-endpoint

标签页操作

创建标签页

POST /tabs

创建新的浏览器标签页。

请求体：

获取标签页快照

GET /tabs/:tabId/snapshot

获取页面的可访问性快照，包含元素引用（ref）系统。

查询参数：

响应结构：

{
  "tabId": "tab_abc123",
  "url": "https://example.com",
  "title": "Example Page",
  "refs": {
    "e1": {
      "tag": "BUTTON",
      "text": "Submit",
      "rect": { "x": 100, "y": 200, "width": 80, "height": 40 }
    }
  }
}

标签页统计

GET /tabs/:tabId/stats

返回标签页元数据，包括 URL、工具调用计数、访问过的 URL、下载/失败计数。

资料来源：server.js:tabs-stats-endpoint

关闭标签页

DELETE /tabs/:tabId

关闭指定标签页并释放相关资源。

查询/请求体参数：

关闭操作会执行以下清理步骤：

1. 中止导航请求（如果存在）
2. 清除下载记录
3. 安全关闭页面
4. 移除 Tab 锁
5. 更新标签页组

资料来源：server.js:tabs-delete-endpoint

导航操作

页面导航

POST /tabs/:tabId/navigate

导航到指定 URL 或执行搜索宏。

请求体：

前进/后退

POST /tabs/:tabId/forward
POST /tabs/:tabId/back

在浏览历史中前进或后退。

资料来源：server.js:navigate-forward-endpoint

交互操作

点击元素

POST /tabs/:tabId/click

点击页面上的元素。

请求体：

*ref 和 selector 至少需要提供一个。

执行流程：

graph TD
    A[接收 click 请求] --> B[验证 userId 和 tabId]
    B --> C[检查 ref 或 selector]
    C --> D[定位元素]
    D --> E[执行点击]
    E --> F[获取点击后快照]
    F --> G[返回结果]

点击操作会重置 consecutiveTimeouts 和 consecutiveFailures 计数器。

资料来源：server.js:tabs-click-endpoint

输入文本

POST /tabs/:tabId/type

向元素输入文本。

请求体：

按键

POST /tabs/:tabId/press

模拟键盘按键。

请求体：

滚动

滚动页面内容，支持方向和滚动量控制。

内容提取

结构化数据提取

POST /tabs/:tabId/extract

使用 JSON Schema 从页面提取结构化数据。

请求体：

Schema 格式示例：

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "x-ref": "e5"
    },
    "price": {
      "type": "number",
      "x-ref": "e12"
    },
    "inStock": {
      "type": "boolean",
      "x-ref": "e8"
    }
  }
}

x-ref 字段指向快照中的元素引用。

类型支持：

Schema 验证规则：

1. 顶层 schema 必须 type: object
2. 必须包含 properties 对象
3. 每个属性必须是对象
4. 属性类型必须在支持列表中

资料来源：lib/extract.js:1-60

页面评估

POST /tabs/:tabId/evaluate

在页面上下文中执行 JavaScript 表达式。

截图

GET /tabs/:tabId/screenshot

获取页面截图。

会话管理

获取会话追踪

GET /sessions/:userId/traces/:filename

下载会话追踪文件（ZIP 格式）。

响应头：

Content-Type: application/zip
Content-Length: <file_size>

错误响应：

会话追踪文件结构

追踪文件包含会话期间的详细操作日志，用于调试和性能分析。

资料来源：server.js:sessions-traces-endpoint

认证机制

API 使用中间件进行认证控制：

authMiddleware()

认证方式优先级：

1. API Key 在请求头中
2. 环回地址免认证（127.0.0.1 / localhost）

资料来源：AGENTS.md:100-110

OpenAPI 文档

文档访问

规范生成

OpenAPI 规范通过 swagger-jsdoc 从 server.js 中的 JSDoc @openapi 注释自动生成。

JSDoc 注释规范：

/**
 * @openapi
 * /tabs/{tabId}/click:
 *   post:
 *     tags: [Interaction]
 *     summary: Click an element
 *     parameters:
 *       - name: tabId
 *         in: path
 *         required: true
 *         schema:
 *           type: string
 *     requestBody:
 *       required: true
 *       content:
 *         application/json:
 *           schema:
 *             type: object
 *             required: [userId]
 *             properties:
 *               userId:
 *                 type: string
 *     responses:
 *       200:
 *         description: Click result.
 */
app.post('/tabs/:tabId/click', async (req, res) => {
  // ...
});

生成命令：

npm run generate-openapi

资料来源：lib/openapi.js:1-45

插件事件系统

API 与插件系统深度集成，通过事件发射器提供钩子机制。

事件分类

#### 浏览器事件

#### 标签页事件

#### 内容事件

#### 下载事件

#### 服务器事件

异步钩子

以下事件通过 events.emitAsync() 发射，服务器会等待所有监听器完成：

• browser:launching
• session:creating
• session:created
• session:destroyed

其他事件使用 events.emit()（即发即忘模式）。

事件使用示例

// 监听标签页点击
events.on('tab:click', ({ userId, tabId, ref }) => {
  console.log(`User ${userId} clicked element ${ref} in tab ${tabId}`);
});

// 修改浏览器启动配置
events.on('browser:launching', ({ options }) => {
  options.virtual_display_resolution = '1920x1080';
});

资料来源：lib/plugins.js:event-system

错误处理

统一错误响应

所有端点使用统一的错误响应格式：

{
  "error": "错误描述信息"
}

常见错误

安全错误处理

错误信息通过 safeError() 函数处理，防止敏感信息泄露：

safeError(err) // 清理堆栈跟踪和内部路径

资料来源：lib/reporter.js:error-sanitization

速率限制

用户并发限制

每个 userId 有独立的并发限制，防止资源滥用：

withUserLimit(userId, async () => {
  // 执行操作
});

Tab 锁

每个标签页使用独立的锁机制，确保操作顺序执行：

withTabLock(tabId, async () => {
  // 执行操作
});

监控与可观测性

Prometheus 指标

API 集成 Prometheus 指标收集：

健康状态追踪

服务器追踪以下健康指标：

• consecutiveNavFailures：连续导航失败次数
• isRecovering：是否处于恢复状态
• activeTabs：活跃标签页数量
• activeSessions：活跃会话数量

事件循环监控

社区反馈显示存在事件循环阻塞问题（阈值 5 秒），这可能导致 API 请求超时。

相关问题：#4863、#4483

客户端库

CLI 二进制文件

从 v1.11.2 起，npm 包提供 camofox-browser 可执行文件：

# 直接运行
npx @askjo/camofox-browser

# 全局安装
npm install -g @askjo/camofox-browser
camofox-browser

默认端口：9377

环境变量配置

最佳实践

请求组织

1. 先创建标签页：使用 POST /tabs 创建新会话
2. 获取快照：使用 GET /tabs/:tabId/snapshot 获取元素引用
3. 使用引用操作：优先使用 ref 而非 CSS 选择器
4. 提取结构化数据：使用 POST /tabs/:tabId/extract 进行数据抓取

错误恢复

1. 检查 GET /health 端点的 recovering 状态
2. 监控 consecutiveFailures 指标
3. 实现指数退避重试机制

性能优化

1. 复用标签页而非频繁创建销毁
2. 使用批量操作减少网络往返
3. 避免在单次请求中执行过多操作

相关文档

• AGENTS.md - 完整的事件系统文档
• docs/api.html - Swagger UI 源码
• openapi.json - 完整的 OpenAPI 规范

概述

camofox-browser 的插件系统是一个可扩展的模块化架构，允许开发者通过事件钩子（hooks）和生命周期回调来增强浏览器自动化服务器的功能。插件可以监听浏览器启动、会话创建、标签页操作等事件，并能够修改浏览器配置和会话选项。

插件系统基于 Node.js 的 EventEmitter 实现，支持同步和异步两种事件处理模式。核心插件包括 VNC（虚拟网络计算）远程可视化、持久化存储、以及 YouTube 特定功能扩展。

资料来源：lib/plugins.js:1-50

架构设计

系统组件

graph TD
    A[camofox-browser 服务器] --> B[插件系统核心<br/>lib/plugins.js]
    B --> C[事件总线<br/>EventEmitter]
    B --> D[插件加载器]
    B --> E[钩子处理器]
    
    D --> F[VNC 插件]
    D --> G[Persistence 插件]
    D --> H[YouTube 插件]
    D --> I[自定义插件]
    
    C -->|tab:created| J1[Tab 生命周期]
    C -->|browser:launching| J2[Browser 生命周期]
    C -->|session:creating| J3[Session 生命周期]
    
    E -->|修改 options| K[传递给核心引擎]

事件分类

插件系统中的事件分为两类：变异钩子（Mutating Hooks） 和 观察者钩子（Observer Hooks）。

资料来源：lib/plugins.js:25-45

事件系统详解

Tab 生命周期事件

内容相关事件

输入交互事件

资料来源：lib/plugins.js:35-55

下载与认证事件

服务器事件

插件管理 CLI

插件管理通过 node scripts/plugin.js 命令行工具执行。

命令列表

安装插件

# 从 GitHub 安装
node scripts/plugin.js install git:github.com/user/repo
node scripts/plugin.js install https://github.com/user/repo

# 从本地路径安装
node scripts/plugin.js install ./path/to/local/plugin

安装过程会自动执行以下步骤：

1. 解析插件来源（Git URL 或本地路径）
2. 克隆/复制插件文件到 plugins/ 目录
3. 安装插件依赖（npm install）
4. 更新配置文件记录新插件
5. 输出安装结果和重启提示

资料来源：scripts/plugin.js:1-60

内置插件

VNC 插件

VNC（Virtual Network Computing）插件提供基于 noVNC 的浏览器可视化访问能力。

#### 启动配置

#### 已知问题

社区反馈 #4314 指出在 v1.11 版本中，VNC 无法通过环境变量正确激活：

# v1.10 工作正常
docker run --rm -it -p 9377:9377 -p 6080:6080 \
  -e ENABLE_VNC=1 -e VNC_BIND=0.0.0.0 \
  ghcr.io/jo-inc/camofox-browser:1.10.0

# v1.11 环境变量不生效

此问题影响在 Docker 容器环境中使用 VNC 功能的需求。

资料来源：plugins/vnc/index.js, plugins/vnc/vnc-launcher.js

Persistence 插件

持久化插件用于在会话之间保存和恢复浏览器状态，包括 Cookie、LocalStorage 和会话存储。

资料来源：plugins/persistence/index.js

YouTube 插件

YouTube 插件提供针对 YouTube 网站的特定功能扩展，包括播放控制、评论操作和播放列表管理。

资料来源：plugins/youtube/index.js, plugins/youtube/youtube.js

插件开发指南

基本结构

一个典型的插件目录结构：

plugins/my-plugin/
├── index.js          # 插件入口，导出事件处理器
├── package.json      # 插件依赖定义
└── *.js              # 其他模块文件

插件入口格式

// plugins/my-plugin/index.js
export default {
  name: 'my-plugin',
  version: '1.0.0',
  
  // 事件处理器
  onBrowserLaunching: async ({ options }) => {
    // 修改浏览器启动选项
    options.virtual_display_resolution = '1920x1080';
  },
  
  onTabCreated: async ({ userId, tabId, page, url }) => {
    // 监听新标签页创建
    console.log(`Tab ${tabId} created for ${userId}`);
  },
  
  onTabNavigated: async ({ userId, tabId, url, prevUrl }) => {
    // 监听页面导航
    if (url.includes('特定域名')) {
      // 执行特定逻辑
    }
  }
};

变异钩子示例

变异钩子允许插件修改传递给核心引擎的选项对象：

// 修改 Xvfb 分辨率（用于 VNC 插件）
events.on('browser:launching', ({ options }) => {
  options.virtual_display_resolution = '1920x1080';
});

// 修改会话创建参数
events.on('session:creating', ({ options }) => {
  options.extraHTTPHeaders = {
    'X-Custom-Header': 'value'
  };
});

资料来源：AGENTS.md:1-50

异步钩子处理

部分钩子使用 emitAsync() 触发，服务器会等待所有监听器完成后再继续：

// 这是一个异步钩子，服务器会等待完成
events.on('session:created', async ({ userId, context }) => {
  // 从磁盘加载存储状态
  const storageState = await loadStorageState(userId);
  await context.addInitScript({
    storage: storageState
  });
});

插件依赖安装

插件安装后会自动执行依赖安装：

// 安装插件依赖
function installPluginDeps(name) {
  const pluginDir = join(pluginsDir, name);
  const pkgFile = join(pluginDir, 'package.json');
  
  if (existsSync(pkgFile)) {
    // 执行 npm install
    spawnSync('npm', ['install', '--silent'], {
      cwd: pluginDir,
      stdio: 'inherit'
    });
  }
}

配置管理

插件配置存储

已安装的插件信息存储在配置文件中：

// 添加插件到配置
function addToConfig(name) {
  if (!CONFIG.plugins.includes(name)) {
    CONFIG.plugins.push(name);
    saveConfig();
  }
}

插件目录结构

常见问题

模块未找到错误

社区 Issue #54 报告了插件更新失败的问题：

Failed to update camofox-browser: Error [ERR_MODULE_NOT_FOUND]: Cannot find module...

解决方案：

1. 确认插件的 package.json 配置正确
2. 检查模块路径是否使用相对路径
3. 运行 npm install 重新安装依赖

VNC 在 Docker 中不工作

问题：v1.11 版本中环境变量 ENABLE_VNC=1 不生效

临时解决方案：

# 使用 v1.10 版本
docker run --rm -it -p 9377:9377 -p 6080:6080 \
  ghcr.io/jo-inc/camofox-browser:1.10.0

插件加载失败

插件加载时会执行依赖安装，如果 npm install 失败，插件可能无法正常工作。建议检查：

1. Node.js 版本兼容性
2. 网络连接（需要访问 npm registry）
3. 文件系统权限

最佳实践

事件处理优化

内存管理

长时间运行的服务器需要注意插件的内存使用：

// 定期清理不再使用的数据
events.on('session:destroyed', async ({ userId }) => {
  await clearUserCache(userId);
});

安全考虑

API 参考

事件载荷类型

钩子执行顺序

sequenceDiagram
    participant Server as 服务器
    participant Plugin as 插件系统
    participant Browser as 浏览器引擎
    
    Server->>Plugin: browser:launching (mutating)
    Plugin->>Browser: 修改后的 options
    Browser->>Server: 浏览器启动
    
    Server->>Plugin: session:creating (mutating)
    Plugin->>Server: 修改后的配置
    
    Server->>Plugin: session:created (async, await)
    Note over Plugin: 执行初始化逻辑
    Server->>Server: 会话就绪
    
    Loop 会话生命周期
        Server->>Plugin: tab:created
        Server->>Plugin: tab:navigated
        Server->>Plugin: tab:snapshot
        Server->>Plugin: tab:click / tab:type / tab:scroll
    end
    
    Server->>Plugin: session:destroyed (async, await)
    Note over Plugin: 执行清理逻辑

总结

camofox-browser 的插件系统提供了强大的扩展能力，通过事件驱动的架构，开发者可以在浏览器生命周期、会话管理和标签页操作的各个环节注入自定义逻辑。系统支持两种事件处理模式（同步和异步），并提供了变异钩子来修改核心引擎的配置选项。

内置插件涵盖了 VNC 可视化、持久化存储和 YouTube 功能等常见场景。插件管理 CLI 提供了便捷的安装、移除和列表查看功能。开发自定义插件时，需要注意遵循入口格式规范，正确处理异步操作，并做好错误处理和资源清理。

概述

搜索宏作为 navigate 接口的参数之一，配合 query 参数使用，可以自动解析并导航到对应搜索引擎的搜索结果页面。这种设计简化了 AI 代理与搜索引擎交互的流程，避免了直接处理 URL 编码和搜索参数拼接的复杂性。

资料来源：server.js:navigate endpoint

支持的搜索宏

camofox-browser 当前支持以下搜索宏：

资料来源：AGENTS.md:Search Macros section

使用方式

API 调用

搜索宏通过 POST /tabs/:tabId/navigate 接口使用：

POST /tabs/:tabId/navigate
Content-Type: application/json

{
  "userId": "agent1",
  "macro": "@google_search",
  "query": "camofox browser automation"
}

请求参数说明：

资料来源：server.js:navigate endpoint schema

工作流程

graph TD
    A[客户端请求 navigate] --> B[解析 macro 参数]
    B --> C{检查 macro 格式}
    C -->|有效宏| D[根据宏名选择搜索引擎]
    C -->|无效或空| E[使用 url 参数直接导航]
    D --> F[拼接 query 参数]
    F --> G[编码生成搜索 URL]
    G --> H[浏览器导航到搜索结果]

最佳实践

元素引用稳定性

搜索宏导航后会生成新的页面快照，此时元素引用（如 e1, e2）会被重置。每次导航操作后需要重新调用 /snapshot 获取当前页面的元素引用。

搜索流程示例

# 1. 创建标签页
POST /tabs
# 返回: { tabId: "tab_abc123" }

# 2. 使用搜索宏导航
POST /tabs/tab_abc123/navigate
{
  "userId": "agent1",
  "macro": "@google_search",
  "query": "browser automation"
}

# 3. 获取快照（引用已更新）
GET /tabs/tab_abc123/snapshot?userId=agent1

# 4. 点击搜索结果
POST /tabs/tab_abc123/click
{
  "userId": "agent1",
  "ref": "e3"
}

会话隔离

搜索宏导航时会继承当前 userId 的会话上下文，包括 cookies、存储状态和代理设置。这确保了搜索行为的连续性和隐私隔离。

与直接 URL 的对比

相关事件

搜索宏导航过程中会触发以下事件：

资料来源：lib/plugins.js:Tab Lifecycle events

限制与注意事项

1. 宏名称格式：必须包含 @ 前缀（如 @google_search），使用时会进行格式校验
2. 查询词编码：特殊字符会自动进行 URL 编码，无需手动处理
3. 导航超时：宏解析和导航操作受全局超时机制约束
4. 反爬虫检测：即使使用搜索宏，目标网站仍可能触发反爬虫机制

扩展搜索宏

搜索宏的实现位于 lib/macros.js（如存在），可通过插件系统进行扩展。开发自定义宏需遵循以下约定：

• 宏名称必须以 @ 开头
• 必须实现 URL 转换逻辑
• 需要处理查询词的编码转义

具体扩展方式可参考 AGENTS.md 中的搜索宏使用文档。

部署方式概览

camofox-browser 支持多种部署方式，开发者可根据实际需求选择最适合的方案：

Docker 部署

Docker 是生产环境推荐使用的部署方式，提供完整的功能支持和隔离环境。

使用预构建镜像

从 GitHub Container Registry 获取最新稳定版本：

docker run --rm -it -p 9377:9377 \
  ghcr.io/jo-inc/camofox-browser:latest

启用 VNC 支持

在 Docker 环境中启用 VNC 需要设置以下环境变量：

docker run --rm -it -p 9377:9377 -p 6080:6080 \
  -e ENABLE_VNC=1 \
  -e VNC_BIND=0.0.0.0 \
  ghcr.io/jo-inc/camofox-browser:latest

验证 VNC 服务是否正常运行：

curl -4I localhost:6080
HTTP/1.1 200 OK

已知问题： 在 v1.11 版本中，VNC 无法通过环境变量正确激活，社区已报告此回归问题。资料来源：#4314

持久化配置

将配置目录和数据卷挂载到宿主机：

docker run --rm -it -p 9377:9377 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/plugins:/app/plugins \
  -v $(pwd)/data:/app/data \
  ghcr.io/jo-inc/camofox-browser:latest

自定义构建

如需包含特定插件或自定义配置，可基于官方 Dockerfile 构建：

FROM ghcr.io/jo-inc/camofox-browser:latest

# 安装额外插件
COPY plugins/* /app/plugins/

# 配置环境变量
ENV BROWSER_HEADLESS=false
ENV LOG_LEVEL=debug

npm 部署

快速启动

使用 npx 直接运行，无需全局安装：

npx @askjo/camofox-browser

全局安装

将 CLI 工具全局安装到系统：

npm install -g @askjo/camofox-browser
camofox-browser

默认端口为 9377，可通过环境变量配置。

平台部署

Railway 部署

camofox-browser 原生支持 Railway 平台部署，配置通过 railway.toml 管理：

[build]
builder = "NIXPACKS"
buildCommand = "npm install && npm run build"

[deploy]
healthcheckPath = "/health"
restartPolicyType = "ON_FAILURE"
restartPolicyLimit = 10

Railway 会自动检测项目类型并配置构建环境。资料来源：railway.toml:1-10

Fly.io 部署

对于 Fly.io 平台，配置由 fly.toml 定义：

app = "camofox-browser"
primary_region = "iad"

[build]
  builder = "heroku/buildpacks:20"

[env]
  PORT = "8080"
  METAL = "true"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0
  processes = ["app"]

资料来源：fly.toml:1-15

部署到 Fly.io：

fly launch
fly deploy

环境变量配置

camofox-browser 通过环境变量控制运行时行为，以下是主要配置项：

VNC 相关配置

源码部署

依赖要求

• Node.js v22+
• npm v10+
• Linux/macOS（部分功能在 Windows WSL2 中有限制）

构建步骤

# 克隆仓库
git clone https://github.com/jo-inc/camofox-browser.git
cd camofox-browser

# 安装依赖
npm install

# 构建
npm run build

# 启动
npm start
# 或使用运行脚本
./run.sh

Makefile 自动化

项目提供 Makefile 简化常见操作：资料来源：Makefile

make install    # 安装依赖
make build     # 构建项目
make start     # 启动服务
make test      # 运行测试
make clean     # 清理构建产物

故障排除

事件循环停滞

频繁报告的问题是事件循环停滞（Event loop stalled），表现为操作超时：

stuck:event-loop: Event loop stalled for 17s (threshold: 5s)

原因分析：

• 长时间运行的浏览器实例内存占用过高
• 并发会话过多导致资源耗尽
• 网络请求阻塞事件循环

解决方案：

1. 监控内存使用：关注 node heap 和 node RSS 指标
2. 限制并发会话数量，设置合理的 MAX_CONCURRENT_SESSIONS
3. 定期重启服务以释放资源
4. 社区报告显示此问题在 v1.7.2-v1.7.3 版本中较为常见

资料来源：#4863、#4483

WSL2 屏幕闪烁

在 Windows 11 的 WSL2 环境中运行可能遇到屏幕每3分钟闪烁一次的问题，伴随 Tux 图标任务短暂出现。资料来源：#64

Docker 构建失败

如需自动化 Docker 构建作为发布流程的一部分，社区已有相关功能请求。资料来源：#525

生产环境建议

资源规划

监控指标

建议监控以下指标：

• HTTP 请求延迟
• 事件循环阻塞时间
• 浏览器堆内存使用率
• 活跃会话数
• 错误率

安全建议

• 通过环境变量设置强密码保护 VNC 访问
• 配置防火墙限制端口访问
• 使用反向代理（如 nginx）处理 HTTPS
• 定期更新到最新稳定版本

相关链接

• GitHub 仓库：https://github.com/jo-inc/camofox-browser
• 问题反馈：https://github.com/jo-inc/camofox-browser/issues
• 最新版本：v1.11.2

配置方式概览

Camofox-browser 支持三种配置方式，按优先级从高到低排列：

graph TD
    A[配置优先级] --> B[API请求参数]
    A --> C[环境变量]
    A --> D[camofox.config.json]
    
    B -->|最高优先级| E[运行时覆盖]
    C -->|次优先级| E
    D -->|最低优先级| E

环境变量配置

环境变量是部署和 Docker 场景中最常用的配置方式。

核心配置变量

VNC 配置

社区反馈表明 VNC 配置在 1.11 版本中存在回归问题，详见 Issue #4314。

# Docker 部署示例
docker run --rm -it -p 9377:9377 -p 6080:6080 \
  -e ENABLE_VNC=1 \
  -e VNC_BIND=0.0.0.0 \
  ghcr.io/jo-inc/camofox-browser:1.11.2

代理配置

代理格式：protocol://username:password@host:port

会话配置

浏览器配置

插件配置

配置文件

项目根目录下的 camofox.config.json 用于持久化配置。

配置文件结构

{
  "server": {
    "port": 9377,
    "host": "0.0.0.0",
    "logLevel": "info",
    "logFormat": "json"
  },
  "browser": {
    "headless": true,
    "viewport": {
      "width": 1280,
      "height": 800
    },
    "args": []
  },
  "session": {
    "timeoutMs": 1800000,
    "maxTabs": 10
  },
  "proxy": {
    "http": null,
    "https": null,
    "noProxy": null
  },
  "vnc": {
    "enabled": false,
    "bind": "127.0.0.1",
    "port": 6080
  },
  "plugins": {
    "dir": "./plugins",
    "npmRegistry": "https://registry.npmjs.org/"
  },
  "traces": {
    "dir": "./traces",
    "retentionDays": 7
  }
}

配置验证

配置系统在 lib/extract.js 中提供了 schema 验证功能：

const SUPPORTED_TYPES = new Set(['string', 'number', 'integer', 'boolean', 'object', 'null']);

代理配置详解

代理格式

graph LR
    A[代理格式] --> B[protocol]
    A --> C[username]
    A --> D[password]
    A --> E[host]
    A --> F[port]
    
    B -->|"socks5|http|https"| G[协议]

代理 URL 格式：protocol://username:password@host:port

代理配置示例

// 通过 API 创建带代理的会话
POST /sessions
{
  "userId": "agent1",
  "contextOptions": {
    "proxy": {
      "server": "http://username:[email protected]:8080"
    }
  }
}

代理生命周期管理

插件配置

插件管理命令

# 安装插件
node scripts/plugin.js install <source>

# 卸载插件
node scripts/plugin.js remove <name>

# 列出已安装插件
node scripts/plugin.js list
node scripts/plugin.js ls

插件安装来源

插件依赖管理

安装插件后，系统会自动执行以下操作：

1. 解析插件源码类型
2. 克隆/复制到 PLUGIN_DIR
3. 安装插件 npm 依赖
4. 更新 camofox.config.json 中的插件列表

// scripts/plugin.js 中的核心逻辑
const installed = parsed.type === 'git'
  ? installFromGit(parsed.url, parsed.name)
  : installFromLocal(parsed.path, parsed.name);

for (const name of installed) {
  addToConfig(name);
  installPluginDeps(name);
}

插件事件钩子

// 修改 Xvfb 分辨率示例
events.on('browser:launching', ({ options }) => {
  options.virtual_display_resolution = '1920x1080';
});

API 配置参数

会话相关参数

标签页操作参数

内容获取参数

健康检查配置

/health 端点返回服务器和浏览器的健康状态：

{
  "ok": true,
  "engine": "camoufox",
  "browserConnected": true,
  "browserRunning": true,
  "activeTabs": 5,
  "activeSessions": 2,
  "consecutiveFailures": 0,
  "memory": {
    "rssMb": 150,
    "heapUsedMb": 66,
    "nativeMemMb": 84
  }
}

当系统处于恢复状态时，返回 503 状态码：

{
  "ok": false,
  "recovering": true
}

日志配置

日志格式

支持 json 和 text 两种格式：

// JSON 格式示例
{
  "level": "info",
  "msg": "tab closed",
  "reqId": "abc123",
  "tabId": "tab1",
  "userId": "agent1",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

日志级别

请求日志字段

路径配置

追踪文件路径规则

// 路径格式
${tracesDir}/${userId}/${filename}

// 示例
./traces/agent1/trace-20240101.zip

路径安全验证

系统对文件路径进行安全验证，防止路径遍历攻击：

const full = resolveTracePath(CONFIG.tracesDir, userId, req.params.filename);
if (!full) return res.status(400).json({ error: 'invalid filename' });

Docker 环境配置

镜像拉取

# 拉取指定版本
docker pull ghcr.io/jo-inc/camofox-browser:1.11.2

# 拉取最新版本
docker pull ghcr.io/jo-inc/camofox-browser:latest

Docker 常用配置

docker run --rm -it \
  -p 9377:9377 \
  -p 6080:6080 \
  -e PORT=9377 \
  -e ENABLE_VNC=1 \
  -e VNC_BIND=0.0.0.0 \
  -e LOG_LEVEL=info \
  ghcr.io/jo-inc/camofox-browser:1.11.2

Docker Compose 示例

version: '3.8'
services:
  camofox:
    image: ghcr.io/jo-inc/camofox-browser:1.11.2
    ports:
      - "9377:9377"
      - "6080:6080"
    environment:
      - ENABLE_VNC=1
      - VNC_BIND=0.0.0.0
      - LOG_LEVEL=info
    restart: unless-stopped

配置优先级与合并

graph TD
    A[配置合并顺序] --> B[1. 加载 camofox.config.json]
    B --> C[2. 应用环境变量覆盖]
    C --> D[3. 应用运行时 API 参数]
    D --> E[最终配置]
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#9f9,stroke:#333,stroke-width:2px

合并规则

1. 深层合并：嵌套对象执行深层合并，非替换
2. 数组替换：数组类型直接替换，非合并
3. null 处理：null 值覆盖为空，而非删除键

常见配置问题

VNC 在 Docker 中不生效

问题描述：Issue #4314 反馈 VNC 在 1.11 版本中无法通过环境变量激活。

解决方案：确保在 Docker 运行时正确设置 ENABLE_VNC=1 和 VNC_BIND=0.0.0.0：

docker run --rm -it \
  -p 6080:6080 \
  -e ENABLE_VNC=1 \
  -e VNC_BIND=0.0.0.0 \
  ghcr.io/jo-inc/camofox-browser:1.11.2

# 验证 VNC 服务
curl -4I localhost:6080
# 应返回 HTTP/1.1 200 OK

插件安装失败

问题描述：Issue #54 报告从 OC 4.5 更新到 4.9 时插件更新失败。

错误信息：

Failed to update camofox-browser: Error [ERR_MODULE_NOT_FOUND]: Cannot find module...

解决方案：检查插件目录权限，确保 node_modules 已正确安装：

# 重新安装插件依赖
cd plugins/camofox-browser
npm install

WSL2 环境屏幕闪烁

问题描述：Issue #64 报告在 WSL2 环境下每 3 分钟出现屏幕闪烁。

说明：这是由 Xvfb 虚拟显示驱动的已知行为，不影响功能但可能影响使用体验。

配置参考表

完整环境变量列表

Pitfall Log / 踩坑日志

项目：jo-inc/camofox-browser

摘要：发现 37 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：配置坑 - 来源证据：[0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s)。

1. 配置坑 · 来源证据：[0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_509e4f60bc5b4f59b2f30d8e940b435f | https://github.com/jo-inc/camofox-browser/issues/4493 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 配置坑 · 来源证据：[50ffc888] stuck:event-loop: Event loop stalled for 12s (threshold: 5s)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[50ffc888] stuck:event-loop: Event loop stalled for 12s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9b0d643d129c40bba9029a91908b6df8 | https://github.com/jo-inc/camofox-browser/issues/4495 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

3. 维护坑 · 来源证据：[5cf7d100] stuck:event-loop: Event loop stalled for 22s (threshold: 5s)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[5cf7d100] stuck:event-loop: Event loop stalled for 22s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b64265a647de4b7b87d3c451230683a7 | https://github.com/jo-inc/camofox-browser/issues/4483 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 配置坑 · 来源证据：[1f7f8070] stuck:event-loop: Event loop stalled for 6s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[1f7f8070] stuck:event-loop: Event loop stalled for 6s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_bc5774adce304ebcb8ccd6511fcf24df | https://github.com/jo-inc/camofox-browser/issues/4859 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：[1f8af390] stuck:event-loop: Event loop stalled for 80s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[1f8af390] stuck:event-loop: Event loop stalled for 80s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_66b048f511104e1f9c71f1ab5bb753ad | https://github.com/jo-inc/camofox-browser/issues/4854 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

6. 配置坑 · 来源证据：[43752418] stuck:event-loop: Event loop stalled for 46s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[43752418] stuck:event-loop: Event loop stalled for 46s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_34506ec241e243b79da0f0ffc55849da | https://github.com/jo-inc/camofox-browser/issues/4858 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

7. 配置坑 · 来源证据：[51f1f89c] stuck:event-loop: Event loop stalled for 38s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[51f1f89c] stuck:event-loop: Event loop stalled for 38s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ec01f035f6474fde8b54a78998fcf0e8 | https://github.com/jo-inc/camofox-browser/issues/4851 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

8. 配置坑 · 来源证据：[674b19b0] stuck:event-loop: Event loop stalled for 23s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[674b19b0] stuck:event-loop: Event loop stalled for 23s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ea7990b603954ff98742c9307eaa3873 | https://github.com/jo-inc/camofox-browser/issues/4856 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

9. 配置坑 · 来源证据：[7506c020] stuck:event-loop: Event loop stalled for 70s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[7506c020] stuck:event-loop: Event loop stalled for 70s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_79456dd0004342acba398cdc03c58748 | https://github.com/jo-inc/camofox-browser/issues/4852 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

10. 配置坑 · 来源证据：[8c732f44] stuck:event-loop: Event loop stalled for 93s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[8c732f44] stuck:event-loop: Event loop stalled for 93s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d5beb836c1824c75b5eedfce488baaeb | https://github.com/jo-inc/camofox-browser/issues/4853 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

11. 配置坑 · 来源证据：[8ffefba3] stuck:event-loop: Event loop stalled for 55s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[8ffefba3] stuck:event-loop: Event loop stalled for 55s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_59fb2f68349c474fb6875fd66c694591 | https://github.com/jo-inc/camofox-browser/issues/4855 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

12. 配置坑 · 来源证据：[90cfc6c8] stuck:event-loop: Event loop stalled for 17s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[90cfc6c8] stuck:event-loop: Event loop stalled for 17s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c4c3a2b1654f4286b1c91f91aad1713e | https://github.com/jo-inc/camofox-browser/issues/4863 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

13. 配置坑 · 来源证据：[988be9c4] stuck:event-loop: Event loop stalled for 18s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[988be9c4] stuck:event-loop: Event loop stalled for 18s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_734e663855e842ce92efed98a8cbd0b3 | https://github.com/jo-inc/camofox-browser/issues/4862 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

14. 配置坑 · 来源证据：[c665094c] stuck:event-loop: Event loop stalled for 74s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[c665094c] stuck:event-loop: Event loop stalled for 74s (threshold: 5s)
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_defd39095ef14988a51da35554363f33 | https://github.com/jo-inc/camofox-browser/issues/4860 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1142274728 | https://github.com/jo-inc/camofox-browser | README/documentation is current enough for a first validation pass.

16. 运行坑 · 失败模式：runtime: [5cf7d100] stuck:event-loop: Event loop stalled for 22s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: [5cf7d100] stuck:event-loop: Event loop stalled for 22s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [5cf7d100] stuck:event-loop: Event loop stalled for 22s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [5cf7d100] stuck:event-loop: Event loop stalled for 22s (threshold: 5s). Context: Observed when using macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_adfbf6e2a8851ffb888977db14835ee7 | https://github.com/jo-inc/camofox-browser/issues/4483 | [5cf7d100] stuck:event-loop: Event loop stalled for 22s (threshold: 5s)

17. 运行坑 · 失败模式：runtime: [ef2f639f] stuck:event-loop: Event loop stalled for 103s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: [ef2f639f] stuck:event-loop: Event loop stalled for 103s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [ef2f639f] stuck:event-loop: Event loop stalled for 103s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [ef2f639f] stuck:event-loop: Event loop stalled for 103s (threshold: 5s). Context: Observed when using macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_e1e537c82dc9bc903c25afaff458ef37 | https://github.com/jo-inc/camofox-browser/issues/4484 | [ef2f639f] stuck:event-loop: Event loop stalled for 103s (threshold: 5s)

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 建议检查：确认是否有离线 demo、mock 数据或可替代服务。
• 防护动作：外部服务依赖未明确时，不把本地安装成功等同于能力可用。
• 证据：packet_text.keyword_scan | github_repo:1142274728 | https://github.com/jo-inc/camofox-browser | matched external service / cloud / webhook / database keyword

19. 维护坑 · 失败模式：migration: [1f7f8070] stuck:event-loop: Event loop stalled for 6s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [1f7f8070] stuck:event-loop: Event loop stalled for 6s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [1f7f8070] stuck:event-loop: Event loop stalled for 6s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [1f7f8070] stuck:event-loop: Event loop stalled for 6s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_4f4c6975103e49767f988cddded1c5a3 | https://github.com/jo-inc/camofox-browser/issues/4857 | [1f7f8070] stuck:event-loop: Event loop stalled for 6s (threshold: 5s)

20. 维护坑 · 失败模式：migration: [1f8af390] stuck:event-loop: Event loop stalled for 80s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [1f8af390] stuck:event-loop: Event loop stalled for 80s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [1f8af390] stuck:event-loop: Event loop stalled for 80s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [1f8af390] stuck:event-loop: Event loop stalled for 80s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_7f437cba05011955428eb8555b0dd70c | https://github.com/jo-inc/camofox-browser/issues/4854 | [1f8af390] stuck:event-loop: Event loop stalled for 80s (threshold: 5s)

21. 维护坑 · 失败模式：migration: [43752418] stuck:event-loop: Event loop stalled for 46s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [43752418] stuck:event-loop: Event loop stalled for 46s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [43752418] stuck:event-loop: Event loop stalled for 46s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [43752418] stuck:event-loop: Event loop stalled for 46s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_f75614730f93a7ca81e759ec5b88bf03 | https://github.com/jo-inc/camofox-browser/issues/4858 | [43752418] stuck:event-loop: Event loop stalled for 46s (threshold: 5s)

22. 维护坑 · 失败模式：migration: [51f1f89c] stuck:event-loop: Event loop stalled for 38s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [51f1f89c] stuck:event-loop: Event loop stalled for 38s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [51f1f89c] stuck:event-loop: Event loop stalled for 38s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [51f1f89c] stuck:event-loop: Event loop stalled for 38s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_a3790117e4c346db5a241874d5355c6d | https://github.com/jo-inc/camofox-browser/issues/4851 | [51f1f89c] stuck:event-loop: Event loop stalled for 38s (threshold: 5s)

23. 维护坑 · 失败模式：migration: [674b19b0] stuck:event-loop: Event loop stalled for 23s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [674b19b0] stuck:event-loop: Event loop stalled for 23s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [674b19b0] stuck:event-loop: Event loop stalled for 23s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [674b19b0] stuck:event-loop: Event loop stalled for 23s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_5f800f182f246903f0b004ebdf189ce5 | https://github.com/jo-inc/camofox-browser/issues/4856 | [674b19b0] stuck:event-loop: Event loop stalled for 23s (threshold: 5s)

24. 维护坑 · 失败模式：migration: [7506c020] stuck:event-loop: Event loop stalled for 70s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [7506c020] stuck:event-loop: Event loop stalled for 70s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [7506c020] stuck:event-loop: Event loop stalled for 70s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [7506c020] stuck:event-loop: Event loop stalled for 70s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_5cbd66fe3eb622d1f5e34730b742dbac | https://github.com/jo-inc/camofox-browser/issues/4852 | [7506c020] stuck:event-loop: Event loop stalled for 70s (threshold: 5s)

25. 维护坑 · 失败模式：migration: [8c732f44] stuck:event-loop: Event loop stalled for 93s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [8c732f44] stuck:event-loop: Event loop stalled for 93s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [8c732f44] stuck:event-loop: Event loop stalled for 93s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [8c732f44] stuck:event-loop: Event loop stalled for 93s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_1c9813603e614996e1e705a49f5d9459 | https://github.com/jo-inc/camofox-browser/issues/4853 | [8c732f44] stuck:event-loop: Event loop stalled for 93s (threshold: 5s)

26. 维护坑 · 失败模式：migration: [8ffefba3] stuck:event-loop: Event loop stalled for 55s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [8ffefba3] stuck:event-loop: Event loop stalled for 55s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [8ffefba3] stuck:event-loop: Event loop stalled for 55s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [8ffefba3] stuck:event-loop: Event loop stalled for 55s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_dcf762017f14fd0f1ff0f2fd7938023e | https://github.com/jo-inc/camofox-browser/issues/4855 | [8ffefba3] stuck:event-loop: Event loop stalled for 55s (threshold: 5s)

27. 维护坑 · 失败模式：migration: [90cfc6c8] stuck:event-loop: Event loop stalled for 17s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [90cfc6c8] stuck:event-loop: Event loop stalled for 17s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [90cfc6c8] stuck:event-loop: Event loop stalled for 17s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [90cfc6c8] stuck:event-loop: Event loop stalled for 17s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_0ae6d0d255bee7d4c76ecadae2a2b89b | https://github.com/jo-inc/camofox-browser/issues/4863 | [90cfc6c8] stuck:event-loop: Event loop stalled for 17s (threshold: 5s), failure_mode_cluster:github_issue | fmev_9b0f7685b8e7a6dc76d4052c3ed229f3 | https://github.com/jo-inc/camofox-browser/issues/4861 | [90cfc6c8] stuck:event-loop: Event loop stalled for 17s (threshold: 5s), failure_mode_cluster:github_issue | fmev_4a9cb6fcef9fa031d0e8ee287b4c4997 | https://github.com/jo-inc/camofox-browser/issues/4849 | [90cfc6c8] stuck:event-loop: Event loop stalled for 17s (threshold: 5s)

28. 维护坑 · 失败模式：migration: [988be9c4] stuck:event-loop: Event loop stalled for 18s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [988be9c4] stuck:event-loop: Event loop stalled for 18s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [988be9c4] stuck:event-loop: Event loop stalled for 18s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [988be9c4] stuck:event-loop: Event loop stalled for 18s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_58b8387d3aaf6df3674469afed9e6e2b | https://github.com/jo-inc/camofox-browser/issues/4862 | [988be9c4] stuck:event-loop: Event loop stalled for 18s (threshold: 5s)

29. 维护坑 · 失败模式：migration: [c665094c] stuck:event-loop: Event loop stalled for 74s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [c665094c] stuck:event-loop: Event loop stalled for 74s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [c665094c] stuck:event-loop: Event loop stalled for 74s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [c665094c] stuck:event-loop: Event loop stalled for 74s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_aebc2e6751b5e29fe6a44e3dc055a8cd | https://github.com/jo-inc/camofox-browser/issues/4860 | [c665094c] stuck:event-loop: Event loop stalled for 74s (threshold: 5s)

30. 维护坑 · 失败模式：migration: [fed74e38] stuck:event-loop: Event loop stalled for 96s (threshold: 5s)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [fed74e38] stuck:event-loop: Event loop stalled for 96s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [fed74e38] stuck:event-loop: Event loop stalled for 96s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [fed74e38] stuck:event-loop: Event loop stalled for 96s (threshold: 5s). Context: Observed when using node, macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_f1881e686e51f7989cbba960e849e678 | https://github.com/jo-inc/camofox-browser/issues/4850 | [fed74e38] stuck:event-loop: Event loop stalled for 96s (threshold: 5s)

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1142274728 | https://github.com/jo-inc/camofox-browser | last_activity_observed missing

32. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1142274728 | https://github.com/jo-inc/camofox-browser | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1142274728 | https://github.com/jo-inc/camofox-browser | no_demo; severity=medium

34. 运行坑 · 失败模式：performance: [0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s)

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: [0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s). Context: Observed when using node, linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_96d2eca451f642a641a8a7b2525b1746 | https://github.com/jo-inc/camofox-browser/issues/4493 | [0d148b4c] stuck:event-loop: Event loop stalled for 7s (threshold: 5s)

35. 运行坑 · 失败模式：performance: [50ffc888] stuck:event-loop: Event loop stalled for 12s (threshold: 5s)

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: [50ffc888] stuck:event-loop: Event loop stalled for 12s (threshold: 5s)
• 对用户的影响：Developers may hit a documented source-backed failure mode: [50ffc888] stuck:event-loop: Event loop stalled for 12s (threshold: 5s)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [50ffc888] stuck:event-loop: Event loop stalled for 12s (threshold: 5s). Context: Observed when using node, linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_4c3438066164124d4582118383fcfdca | https://github.com/jo-inc/camofox-browser/issues/4495 | [50ffc888] stuck:event-loop: Event loop stalled for 12s (threshold: 5s)

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1142274728 | https://github.com/jo-inc/camofox-browser | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1142274728 | https://github.com/jo-inc/camofox-browser | release_recency=unknown