# web2api

**Repository Path**: web/web2api

## Basic Information

- **Project Name**: web2api
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WebAI2API

简体中文 | [English](README_EN.md)

<p align="center">
  <img src="https://github.com/user-attachments/assets/296a518e-c42b-4e39-8ff6-9b4381ed4f6e" width="49%" />
  <img src="https://github.com/user-attachments/assets/bfa30ece-6947-4f18-b2c9-ccc8087b7e89" width="49%" />
</p>
<p align="center">
  <img src="https://github.com/user-attachments/assets/5b15ebd2-7593-4f0e-8561-83d6ba5d88ab" width="49%" />
  <img src="https://github.com/user-attachments/assets/53deea29-4071-4a07-8a61-211761c5f2f7" width="49%" />
</p>

## 📑 目录

- [快速部署](#-快速部署)
  - [方式一:手动部署](#方式一手动部署)
  - [方式二:Docker 部署](#方式二docker-部署)
  - [方式三:宝塔面板部署](#方式三宝塔面板部署)
- [快速开始](#-快速开始)
- [使用方法](#-使用方法)
- [API 接口](#-api-接口)
- [设备配置参考](#-设备配置参考)
- [极致性能指南](#-极致性能指南)

---

## 📝 项目简介

**WebAI2API** 是一个基于 **Camoufox (Playwright)** 的网页版 AI 服务转通用 API 的工具。通过模拟人类操作与 LMArena、Gemini 等网站交互, 提供兼容 **OpenAI 格式** 的接口服务, 同时支持 **多窗口并发** 与 **多账号管理**(浏览器实例数据隔离)。

### ✨ 主要特性

- 🤖 **拟人交互**: 模拟人类打字与鼠标轨迹, 通过特征伪装规避自动化检测
- 🔄 **接口兼容**: 提供标准 OpenAI 格式接口, 支持流式响应与心跳保活
- 🚀 **并发隔离**: 支持多窗口并发执行, 可配置独立代理,实现多账号浏览器实例级数据隔离
- 🛡️ **稳定防护**: 内置任务队列、负载均衡、故障转移、错误重试等基础功能
- 🎨 **网页管理**: 提供可视化管理界面, 支持实时日志查看、VNC 连接、适配器管理等

### 📋 支持列表

| 网站名称 | 文本生成 | 图片生成 | 视频生成 |
| :--- | :---: | :---: | :---: | 
| [**LMArena**](https://lmarena.ai/) | ✅ | ✅ | 🚫 |
| [**Gemini Enterprise Business**](https://business.gemini.google/) | ✅ | ✅ | ✅ |
| [**Nano Banana Free**](https://nanobananafree.ai/) | 🚫 | ✅ | 🚫 |
| [**zAI**](https://zai.is/) | ✅ | ✅ | 🚫 |
| [**Google Gemini**](https://gemini.google.com/) | ✅ | ✅💧 | ✅💧 | 
| [**ZenMux**](https://zenmux.ai/) | ✅ | ❌ | 🚫 | 
| [**ChatGPT**](https://chatgpt.com/) | ✅ | ✅ | 🚫 | 
| [**DeepSeek**](https://chat.deepseek.com/) | ✅ | 🚫 | 🚫 | 
| [**Sora**](https://sora.chatgpt.com/) | 🚫 | 🚫 | ✅💧 | 
| [**Google Flow**](https://labs.google/fx/zh/tools/flow) | 🚫 | ✅ | ❌ | 
| [**豆包**](https://www.doubao.com/) | ✅ | ✅ | ❌ | 
| 待续... | - | - | - | 

> [!NOTE]
> **获取完整模型列表**: 通过 `GET /v1/models` 接口查看当前配置下所有可用模型及其详细信息。
> 
> ✅目前支持；❌目前不支持，但未来可能会支持；🚫网站不支持, 未来是否在支持看网站具体情况；💧结果带水印且无法去除；

---

## 🚀 快速部署

本项目支持 **源码直接运行**、**Docker 容器化部署** 和 **宝塔面板部署** 三种方式。

### 📋 环境要求

- **Node.js**: v20.0.0+ (ABI 115+)
- **操作系统**: Windows / Linux / macOS
- **核心依赖**: Camoufox (安装过程中自动获取)

### 🛠️ 方式一:手动部署

1. **安装与配置**
   ```bash
   # 1. 安装 NPM 依赖
   pnpm install

   # 2. 安装浏览器等预编译依赖
   # ⚠️ 该脚本需连接 GitHub 下载资源。若网络受限，请使用代理
   npm run init 
   # 使用代理
   # 直接使用 -proxy 可交互式输入代理配置
   npm run init -- -proxy=http://username:passwd@host:port

   # 3. Linux 依赖安装
   # 其他发行版请前往文档中心查找或者自行搜索
   apt install -y xvfb x11vnc libgtk-3-0 libx11-xcb1 libasound2
   
   ```

2. **启动服务**
   ```bash
   # 标准启动
   npm start

   # Linux 系统 - 虚拟显示启动
   npm start -- -xvfb -vnc

   # 登录模式 (会临时强行禁用无头模式和自动化)
   npm start -- -login (-xvfb -vnc)
   ```

### 🐳 方式二:Docker 部署

> [!WARNING]
> **安全提醒**: 
> - Docker 镜像默认开启虚拟显示器 (Xvfb) 和 VNC 服务
> - 可通过 WebUI 的虚拟显示器板块连接
> - **WebUI 传输过程未加密, 公网环境请使用 SSH 隧道或 HTTPS**

**Docker CLI 启动**
```bash
docker run -d --name webai-2api \
  -p 3000:3000 \
  -v "$(pwd)/data:/app/data" \
  --shm-size=2gb \
  foxhui/webai-2api:latest
```

**Docker Compose 启动**
```bash
docker-compose up -d
```

### 🏠 方式三:宝塔面板部署

> [!NOTE]
> 宝塔面板部署适合不想使用 Docker 的用户, 通过宝塔的 Node.js 项目管理器进行管理。

#### 1. 环境准备

**在宝塔面板中安装以下软件:**

- **Node.js 版本管理器 (PM2管理器)**: 软件商店搜索安装
- **Nginx**: 软件商店安装 (用于反向代理和 HTTPS)
- **MySQL**: 可选, 本项目使用 SQLite, 无需 MySQL
- **Redis**: 可选

**安装系统依赖 (SSH 终端执行):**
```bash
# Debian/Ubuntu 系统
apt update
apt install -y xvfb x11vnc libgtk-3-0 libx11-xcb1 libasound2 libgbm1 libnss3 libxss1 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libpango-1.0-0 libcairo2 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1

# CentOS/AlmaLinux/Rocky 系统
# 1) 启用常用仓库（epel 与 crb/powertools，部分系统包默认不在基础仓库）
dnf install -y epel-release
# AlmaLinux/Rocky 9: sudo dnf config-manager --set-enabled crb
# AlmaLinux/Rocky 8: sudo dnf config-manager --set-enabled powertools

# 2) 安装 Chromium 运行所需系统库（使用 RHEL 系包名）
dnf install -y \
    xorg-x11-server-Xvfb x11vnc \
    gtk3 libX11-xcb alsa-lib nss libXScrnSaver \
    atk at-spi2-atk cups-libs libdrm libxkbcommon \
    pango cairo libXcomposite libXdamage libXfixes libXrandr libgbm

# 3) 验证依赖是否完整（可选，检查是否有 not found）
# ldd $(find /www/wwwroot/webai-2api -name "chrome" -o -name "chromium" 2>/dev/null | head -1) 2>/dev/null | grep "not found"
```

#### 2. 安装 Node.js

1. 登录宝塔面板, 进入 **软件商店** → 搜索 **PM2管理器** → 安装
2. 安装完成后, 进入 **Node版本管理**, 安装 **Node.js v20.x** (必须 >= 20.0.0)
3. 确保 ABI 版本为 115+

#### 3. 上传项目代码

```bash
# 方式一: 使用宝塔文件管理器上传
# 将项目压缩包上传到 /www/wwwroot/webai-2api/ 目录并解压

# 方式二: SSH 终端克隆
cd /www/wwwroot
git clone https://gitee.com/web/web2api.git webai-2api
cd webai-2api
```

#### 4. 安装项目依赖

```bash
cd /www/wwwroot/webai-2api

# 安装 pnpm (如未安装)
npm install -g pnpm

# 安装项目依赖
pnpm install

# 初始化运行环境 (下载 Camoufox 等浏览器资源)
# ⚠️ 若服务器网络受限, 需要使用代理
npm run init

# 如网络受限, 使用代理初始化:
# npm run init -- -proxy=http://用户名:密码@代理地址:端口

#安装必要依赖
sudo yum install xorg-x11-server-Xvfb x11vnc gtk3 libX11-xcb alsa-lib

```

#### 5. 配置项目

```bash
# 初次运行会自动从 config.example.yaml 复制配置文件到 data/config.yaml
# 手动配置:
cd /www/wwwroot/webai-2api
cp config.example.yaml data/config.yaml
```

编辑 `data/config.yaml`:
```yaml
server:
  port: 3000  # 服务端口
  auth: your-secure-key  # API 密钥 (可通过 npm run genkey 生成)

# 其他配置按需调整, 详见 config.example.yaml 注释
```

#### 6. 启动项目

**方式 A: 使用 PM2 守护 (推荐)**

```bash
cd /www/wwwroot/webai-2api

# 使用 PM2 启动 (带虚拟显示)
pm2 start supervisor.js --name webai-2api -- -xvfb

# 如需 VNC 远程查看浏览器
pm2 start supervisor.js --name webai-2api -- -xvfb -vnc

# 保存 PM2 进程列表
pm2 save

# 设置开机自启
pm2 startup
# 按提示执行输出的命令
```

**方式 B: 使用宝塔 Node 项目管理器**

1. 进入宝塔 **网站** → **Node项目**
2. 点击 **添加 Node项目**
3. 项目目录: `/www/wwwroot/webai-2api`
4. 启动命令: `npm start`
5. 端口: `3000`
6. 运行模式: `生产环境`
7. 点击 **提交**

#### 7. 配置 Nginx 反向代理 (可选, 推荐)

**在宝塔面板添加站点:**

1. 进入 **网站** → **添加站点**
2. 域名: 填写你的域名 (如 `api.example.com`)
3. PHP版本: 选择 **纯静态**
4. 创建完成后, 点击站点名 → **反向代理** → **添加反向代理**
5. 代理名称: `webai-2api`
6. 目标URL: `http://127.0.0.1:3000`
7. 点击提交

**配置 SSL 证书 (推荐):**
1. 站点设置 → SSL → 申请 Let's Encrypt 证书
2. 开启强制 HTTPS

**示例 Nginx 配置 (高级设置中参考):**
```nginx
server {
    listen 80;
    server_name api.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate    /www/server/panel/vhost/cert/api.example.com/fullchain.pem;
    ssl_certificate_key    /www/server/panel/vhost/cert/api.example.com/privkey.pem;

    # WebSocket 支持 (SSE 流式响应需要)
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;  # 长响应超时
        proxy_send_timeout 300s;
    }
}
```

#### 8. 开放防火墙端口

```bash
# 宝塔面板 → 安全 → 开放端口: 3000 (或你配置的端口)

# SSH 终端防火墙命令 (如使用 firewalld)
firewall-cmd --permanent --add-port=3000/tcp
firewall-cmd --reload

# 如使用 ufw
ufw allow 3000/tcp
```

#### 9. 验证部署

```bash
# 本地测试 API
curl http://服务器IP:3000/v1/models \
  -H "Authorization: Bearer your-secure-key"

# 测试文本生成
curl http://服务器IP:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secure-key" \
  -d '{"model":"doubao","messages":[{"role":"user","content":"你好"}],"stream":true}'
```

#### 10. 初始化账号

1. 访问 WebUI: `http://服务器IP:3000`
2. 登录后进入 **虚拟显示器** 板块, 连接 VNC
3. 在虚拟显示器中手动登录各 AI 网站账号
4. 完成人机验证和新手指引

#### 常见问题

**Q: 启动后浏览器打不开?**
```bash
# 检查 Xvfb 是否运行
ps aux | grep xvfb
# 如需手动启动
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
```

**Q: 依赖安装失败?**
```bash
# 清理缓存重新安装
cd /www/wwwroot/webai-2api
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

**Q: 服务器内存不足?**
```bash
# 添加 swap 虚拟内存
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
# 设置开机自启
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
```

**Q: PM2 进程查看日志?**
```bash
pm2 logs webai-2api    # 查看实时日志
pm2 monit              # 监控进程状态
pm2 restart webai-2api # 重启服务
```

---

## ⚡ 快速开始

### 1. 调整配置文件

程序初次运行会从`config.example.yaml`复制配置文件到`data/config.yaml`

**配置文件的生效需要重启程序！**

```yaml
server:
  # 监听端口
  port: 3000
  # 鉴权 API Token (可使用 npm run genkey 生成)
  # 该配置会对 API 接口和 WebUI 生效
  auth: sk-change-me-to-your-secure-key
```

> [!TIP]
> **完整配置说明**: 请参考 [config.example.yaml](config.example.yaml) 文件中的详细注释,或访问 [WebAI2API 文档中心](https://foxhui.github.io/WebAI2API/) 查看完整配置指南。

### 2. 访问 Web 管理界面

服务启动后, 打开浏览器访问:
```
http://localhost:3000
```

> [!TIP]
> **远程访问**: 将 `localhost` 替换为服务器 IP 地址即可远程访问。
> **API Token**: 配置文件中的`auth`所配置的鉴权密钥。
> **安全建议**: 公网环境建议使用 Nginx/Caddy 配置 HTTPS 或通过 SSH 隧道访问。

### 3. 初始化账号登录

> [!IMPORTANT]
> **首次使用必须完成以下初始化步骤**:

1. **连接虚拟显示器**:
   - Linux/Docker: 在 WebUI 的"虚拟显示器"板块连接
   - Windows: 直接在弹出的浏览器窗口中操作

2. **完成账号登录**:
   - 手动登录所需的 AI 网站账号 (账号要求可进入 WebUI 的适配器管理中查看)
   - 在输入框发送任意消息, 触发并完成人机验证 (如需要)
   - 同意服务条款或者新手指引 (如需要)
   - 确保不再有初次使用相关内容的阻拦

3. **配置用户数据持久化**:
   - **固定用户数据标记**: 在 `config.yaml` 中设置固定的 `userDataMark` 以确保登录状态持久化
   - **配置示例**:
   ```yaml
   backend:
     pool:
       instances:
         - name: "browser_default"
           # 固定的用户数据标记，确保登录状态持久化
           userDataMark: "persistent_login"
           workers:
             - name: "default"
               type: lmarena
   ```
   - **重要提示**: 配置固定用户数据标记后，重启服务时将保持之前的登录状态，无需重复登录

4. **SSH 隧道连接示例**(公网服务器推荐):
   ```bash
   # 在本地终端运行,将服务器的 WebUI 映射到本地
   ssh -L 3000:127.0.0.1:3000 root@服务器IP
   
   # 然后在本地访问
   # WebUI: http://localhost:3000
   ```

---

## 📖 使用方法

### 运行模式说明

> [!NOTE]
> **关于有头/无头模式**:
> - **有头模式**(默认): 显示浏览器窗口, 便于调试和人工干预
> - **无头模式**: 后台运行, 节省资源但无法查看浏览器界面, 且可能会被网站检测
> 
> **建议**: 为降低风控, **强烈建议长期保持非无头模式运行**(或使用虚拟显示器 Xvfb)。

---

## 🔌 API 接口

> [!TIP]
> **详细文档**: 请访问 [WebAI2API 文档中心](https://foxhui.github.io/WebAI2API/) 获取更全面的配置指南与接口说明。

### 1. OpenAI 兼容接口

> [!WARNING]
> **并发限制与流式保活建议**
> 
> 本项目通过模拟真实浏览器操作实现, 处理过程根据实际情况时间可能有所变化, 当积压的任务超过设置的数量时会直接拒绝非流式模式的请求。
> 
> **💡 强烈建议开启流式模式**: 服务器将发送保活心跳包, 可无限排队避免超时。

#### 文本对话

**端点**: `POST /v1/chat/completions`

**请求示例**:
```bash
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gemini-3-pro",
    "messages": [
      {"role": "user", "content": "你好,请介绍一下你自己"}
    ],
    "stream": true
  }'
```

#### 多模态请求(文生图/图生图)

**支持的图片格式**:
- **格式**: PNG, JPEG, GIF, WebP
- **数量**: 最大 10 张(具体限制因网站而异)
- **数据格式**: 必须使用 Base64 Data URL 格式
- **自动转换**: 服务器会自动将所有图片转换为 JPG 格式以保证兼容性

#### 参数说明

| 参数 | 类型 | 必填 | 说明 |
| :--- | :--- | :---: | :--- |
| `model` | string | ✅ | 模型名称, 可通过 `/v1/models` 获取可用列表 |
| `stream` | boolean | 推荐 | 是否开启流式响应, 包含心跳保活机制 |

> [!NOTE]
> **关于流式保活 (Heartbeat)**
>
> 为防止长连接超时, 系统提供两种保活模式 (可在配置中切换):
> 1. **Comment 模式 (默认/推荐)**: 发送 `:keepalive` 注释, 符合 SSE 标准,兼容性最好
> 2. **Content 模式**: 发送空内容的 data 包, 仅用于必须收到 JSON 数据才重置超时的特殊客户端

### 2. 获取模型列表

**端点**: `GET /v1/models`

**请求示例**:
```bash
curl http://localhost:3000/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 3. 获取 Cookies

**功能说明**: 利用本项目的自动续登功能获取最新 Cookie 供其他工具使用。

**端点**: `GET /v1/cookies`

**参数**:
- `name` (可选): 浏览器实例名称,默认为 `default`
- `domain` (可选): 过滤指定域名的 Cookie

**请求示例**:
```bash
# 获取指定实例和域名的 Cookie
curl "http://localhost:3000/v1/cookies?name=browser_default&domain=lmarena.ai" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

## 📊 设备配置参考

| 资源 | 最低配置 | 推荐配置 (单实例) | 推荐配置 (多实例) |
| :--- | :--- | :--- | :--- |
| **CPU** | 1 核 | 2 核及以上 | 4 核及以上 |
| **内存** | 1 GB | 2 GB 及以上 | 8 GB 及以上 |
| **磁盘** | 2 GB 可用空间 | 10 GB 及以上 | 30 GB+ SSD |

**实测环境表现** (均为单浏览器实例):
- **Oracle 免费机** (1C1G, Debian 12): 资源紧张, 比较卡顿, 仅供尝鲜或轻度使用
- **阿里云轻量云** (2C2G, Debian 11): 运行流畅但实例也会卡顿, 项目开发测试所用机型
- **腾讯云标准型** (4C8G, Debian 12): 运行流畅, 支持 3-5 个 Worker 并发

---

## ⚡ 极致性能指南

本项目通过 Worker 池架构、浏览器隔离、CSS 性能注入、心跳保活等多层次优化, 实现稳定高效的 AI 网页服务代理。以下从架构设计、Worker 模型、参数调优、服务器配置四个维度详细说明。

### 架构性能设计

#### 1. Worker 池架构

```
HTTP 请求
  → 任务队列 (QueueManager)
    → 并发控制 (maxConcurrent)
      → PoolManager (策略选择: least_busy / round_robin / random)
        → Worker (浏览器实例封装)
          → Camoufox (Firefox 内核)
            → 目标 AI 网站
```

**核心设计:**
- **多 Worker 隔离**: 每个 Worker 封装独立浏览器实例, 互不干扰
- **浏览器共享**: 同一 `userDataDir` 的 Worker 可共享浏览器进程, 节省资源
- **智能调度**: `least_busy` 策略优先选择空闲 Worker, 实现负载均衡
- **故障转移**: Worker 失败时自动切换到下一个, 最多重试 `maxRetries` 次
- **Merge 模式**: 单个 Worker 支持多适配器类型, 灵活组合

#### 2. 浏览器性能优化

| 优化项 | 实现方式 | 性能提升 |
|--------|----------|----------|
| **CSS 性能注入** | 禁用动画/过渡/滤镜 (`animation/transition/filter` 全设为 none) | 页面渲染速度提升 30-50% |
| **字体优化** | `text-rendering: optimizeSpeed` 跳过字体排版计算 | 文本渲染加速 |
| **GPU 可配置** | VPS 环境设 `disableGPU: true`, 强制软件渲染 (llvmpipe) | 避免 GPU 挂起, 稳定性大幅提升 |
| **指纹持久化** | Canvas/WebGL 指纹写入文件, 避免每次启动重新生成 | 启动耗时减少 60% |
| **遥测禁用** | 关闭 Firefox 遥测、自动更新、安全报告等后台请求 | 减少网络开销和 CPU 占用 |
| **WebRTC 屏蔽** | `block_webrtc: true` 防止 IP 泄露和意外带宽消耗 | 隐私+性能双重提升 |
| **CSS 视口强制** | `layout.css.device-width.enabled: true` 确保移动端视口生效 | 移动端适配更稳定 |

#### 3. 队列与心跳优化

| 优化项 | 实现方式 | 效果 |
|--------|----------|------|
| **队列缓冲** | `queueBuffer` 支持排队, 流式请求无限排队 | 避免高峰时段 503 拒绝 |
| **心跳保活** | 3 秒间隔心跳包 (`:keepalive` 注释模式) | 防止 SSE 连接超时 |
| **流式优先** | 非流式请求受 `maxConcurrent + queueBuffer` 限制, 流式无限制 | 保障流式体验 |
| **空闲监控** | 队列空闲时 Worker 自动跳转到监控页保持活跃状态 | 避免页面超时失效 |

#### 4. 反检测与稳定性

| 优化项 | 实现方式 | 效果 |
|--------|----------|------|
| **Camoufox 指纹** | 基于 BrowserForge 的 Canvas/WebGL/UA 全套指纹伪装 | 通过 AI 平台反爬检测 |
| **Ghost Cursor** | 拟人化鼠标轨迹, 模拟人类操作 | 降低风控触发率 |
| **设备模式切换** | PC/Mobile 动态切换视口、UA、触摸事件 | 适配不同设备检测 |
| **浏览器崩溃恢复** | 浏览器断开后自动重新初始化, 恢复共享 Worker 连接 | 零人工干预 |
| **标签页自动重建** | 标签页关闭事件监听, 自动创建新标签页 | 长期运行稳定性 |

### Worker 并发模型

#### 配置结构

```yaml
backend:
  pool:
    # 调度策略
    strategy: least_busy    # least_busy | round_robin | random
    # 故障转移
    failover:
      enabled: true
      maxRetries: 2
    # 实例配置
    instances:
      - name: main
        userDataMark: profile1
        workers:
          - name: worker-lmarena
            type: lmarena
          - name: worker-gemini
            type: gemini
          - name: worker-merge
            type: merge
            mergeTypes: [gemini, deepseek, doubao]
            mergeMonitor: doubao
```

#### 性能参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `queue.maxConcurrent` | Worker 数量 | 自动计算, 等于 Worker 总数 |
| `queue.queueBuffer` | 2 | 非流式请求缓冲队列大小 |
| `queue.imageLimit` | 5 | 单次请求图片数量上限 |
| `pool.strategy` | least_busy | Worker 选择策略 |
| `pool.failover.maxRetries` | 2 | 故障转移最大重试次数 |
| `browser.disableGPU` | false | 禁用 GPU 加速 (VPS 环境建议 true) |
| `browser.humanizeCursor` | true | 拟人化鼠标轨迹 |
| `server.keepalive.mode` | comment | 心跳模式 (comment/content) |

#### Merge 聚合模式 (单 Worker 多平台)

Merge 模式允许**一个 Worker 同时挂载多个平台适配器**, 根据请求的模型 ID 自动路由到对应平台, 共享同一个浏览器实例, 节省资源。

**配置示例** — 一个 Worker 同时支持 Gemini、DeepSeek、Doubao:

```yaml
backend:
  pool:
    instances:
      - name: main
        userDataMark: profile1
        workers:
          - name: worker-merge          # Worker 名称 (唯一)
            type: merge                   # 类型: merge 表示聚合模式
            mergeTypes:                   # 支持的平台适配器列表
              - gemini
              - deepseek
              - doubao
            mergeMonitor: doubao         # 空闲时挂机的监控平台 (可选)
            device: pc                   # 设备模式 (pc/mobile)
```

**路由逻辑**:

| 请求的 modelId | 自动路由到 | 说明 |
|---------------|-----------|------|
| `gemini-1.5-pro` | **gemini** 适配器 | 自动匹配, 无需前缀 |
| `deepseek-chat` | **deepseek** 适配器 | 自动匹配 |
| `doubao-pro-32k` | **doubao** 适配器 | 自动匹配 |
| `gemini/gpt-4o` | **gemini** 适配器 | 用 `平台/模型` 前缀强制指定 |
| `doubao/deepseek-chat` | **doubao** 适配器 | 强制指定平台 |

**故障转移机制**: Merge 模式内置适配器级故障转移, 当第一个适配器失败时自动切换到下一个:

```
请求 modelId: deepseek-chat
  → 尝试 deepseek 适配器 → 失败
  → 尝试 doubao 适配器 (如有相同模型) → 成功 ✓
```

**模型发现**: 通过 `/v1/models` 接口可看到 Merge Worker 聚合的所有模型, 每个模型会生成两个条目:
- 无前缀: 如 `deepseek-chat` (由系统选择适配器)
- 带前缀: 如 `deepseek/deepseek-chat` (强制使用指定适配器)

**适用场景**:
- 低资源 VPS: 1 个 Worker 跑 3-5 个平台
- 平台互补: 一个平台挂了自动切到另一个
- 统一入口: 客户端不需要关心后端平台差异

**注意事项**:
- 所有 `mergeTypes` 中的平台共享同一个浏览器 Cookie/Session
- 各平台账号需在同一浏览器 Profile 中分别登录
- 故障转移最多重试 `maxRetries + 1` 次 (默认 3 次)
- 标记为 `retryable: false` 的错误 (如内容安全) 不会自动重试

### 性能优化参数

在 `data/config.yaml` 中调整以下参数可进一步优化性能:

```yaml
browser:
  # VPS/无 GPU 环境务必设为 true, 否则浏览器会挂起
  disableGPU: true
  # 启用 CSS 性能注入 (默认全部启用)
  cssInject:
    animation: true   # 禁用动画/过渡
    filter: true      # 禁用滤镜/阴影
    font: true        # 字体渲染优化
  # 拟人化游标模式
  humanizeCursor: true

queue:
  # 非流式请求缓冲: 0 = 不限制, 推荐 5-10
  queueBuffer: 5
  # 单次请求图片上限
  imageLimit: 5

backend:
  pool:
    # 推荐 least_busy, 实现真正的负载均衡
    strategy: least_busy
    failover:
      enabled: true
      maxRetries: 2      # 高可用环境可设为 3
      imgDlRetry: false   # 图片下载是否重试

server:
  # 心跳模式: comment (SSE 标准, 推荐) | content (兼容特殊客户端)
  keepalive:
    mode: comment
```

### 服务器配置要求

#### 最低配置 (测试/开发)

| 资源 | 规格 | 说明 |
|------|------|------|
| **CPU** | 1 核 | 仅适合单 Worker 测试 |
| **内存** | 2 GB | 单浏览器实例约 500MB-1GB |
| **磁盘** | 10 GB HDD | Camoufox + Profile + 日志 |
| **操作系统** | Windows 10+ / Linux (Ubuntu 20.04+) | 推荐 Linux |
| **Node.js** | v20.0.0+ (ABI 115+) | 必须 |
| **Docker** | 可选 | 20.10+ |

#### 推荐配置 (生产环境)

| 资源 | 规格 | 说明 |
|------|------|------|
| **CPU** | 4 核 | 支持 3-5 个 Worker 并发 |
| **内存** | 8 GB | 每个浏览器 ~1.5GB, 预留系统 2GB |
| **磁盘** | 30 GB+ SSD | Profile 持久化 + 日志 + 临时文件 |
| **网络** | 500 Mbps+ 稳定带宽 | AI 平台响应下载 |
| **系统** | Ubuntu 22.04/24.04 LTS | 长期支持 |
| **Xvfb** | 必须 | 无显示器环境必备 |

#### 高并发配置 (5+ Worker)

| 资源 | 规格 | 说明 |
|------|------|------|
| **CPU** | 8-16 核 | 推荐高频多核 |
| **内存** | 16-32 GB | 按 1.5GB/Worker × Worker 数 + 系统预留 |
| **磁盘** | 100 GB+ NVMe SSD | 大量 Profile + 日志 |
| **网络** | 1 Gbps+ | 大带宽低延迟 |
| **Worker 数** | 5-10 个 | 每个 Worker 独立浏览器实例 |

#### Docker 资源限制配置

```bash
# Docker CLI 推荐配置
docker run -d --name webai-2api \
  -p 3000:3000 \
  -v "$(pwd)/data:/app/data" \
  --shm-size=2gb \
  --memory=8g \
  --cpus=4 \
  foxhui/webai-2api:latest
```

```yaml
# docker-compose.yml 推荐配置
services:
  webai-2api:
    image: foxhui/webai-2api:latest
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
    # 关键! 默认 64MB, Firefox 需要足够的共享内存
    shm_size: '2gb'
    # 资源限制 (按需调整)
    # deploy:
    #   resources:
    #     limits:
    #       cpus: '4'
    #       memory: 8g
    environment:
      - NODE_ENV=production
      # 如需禁用 GPU (VPS 环境)
      # - BROWSER__DISABLE_GPU=true
```

### 性能监控与 Checklist

#### 监控命令

```bash
# 查看实时日志
pm2 logs webai-2api

# 监控进程状态和资源占用
pm2 monit

# 查看系统资源
top -bn1 | head -20
free -h
df -h

# 查看 Worker 队列状态 (API)
curl http://localhost:3000/admin/status \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### 极限性能 Checklist

- [ ] 使用 SSD/NVMe 磁盘 (禁止 HDD)
- [ ] Docker 环境设置 `shm_size` >= 2GB
- [ ] VPS 环境设置 `browser.disableGPU: true` (防止浏览器挂起)
- [ ] 启用 CSS 性能注入 (`cssInject.animation/filter/font`)
- [ ] 使用 `least_busy` 调度策略实现负载均衡
- [ ] 流式请求使用 `comment` 心跳模式 (SSE 标准兼容)
- [ ] 合理设置 `queueBuffer` (推荐 5-10) 应对突发流量
- [ ] 开启故障转移 (`failover.enabled: true`) 保障高可用
- [ ] 定期清理过期 Profile 和历史记录
- [ ] 使用稳定的代理 IP (避免频繁切换)

---

## 📄 许可证和免责声明

本项目采用 [MIT License](LICENSE) 开源。

> [!CAUTION]
> **免责声明**
> 
> 本项目仅供学习交流使用。如果因使用该项目造成的任何后果 (包括但不限于账号被禁用),作者和项目均不承担任何责任。请遵守相关网站和服务的使用条款 (ToS),并做好相关数据的备份工作。

---

## 📋 更新日志

查看完整的版本历史和更新内容, 请访问 [CHANGELOG.md](CHANGELOG.md)。

### 🕰️ 历史版本说明

本项目已从 Puppeteer 迁移至 Camoufox, 以应对日益复杂的反机器人检测机制。基于 Puppeteer 的旧版本代码已归档至 `puppeteer-edition` 分支, 仅作留存, **不再提供更新与维护**。

---

**感谢 LMArena、Gemini 等网站提供 AI 服务!** 🎉