docs: update project documentation in README.md

2026-06-16 21:03:59 +08:00 · 2025-11-24 02:08:54 +08:00
parent 4324b9c14b
commit 55377de092
1 changed files with 48 additions and 225 deletions
@@ -2,7 +2,9 @@

 ## 📝 项目简介

-LMArenaImagenAutomator 是一个基于 Puppeteer 的自动化图像生成工具，通过模拟人类操作与 LMArena 网站交互，提供图像生成服务。项目支持两种运行模式：
+LMArenaImagenAutomator 是一个基于 Puppeteer 的自动化图像生成工具，通过模拟人类操作与 LMArena 网站交互，提供图像生成服务。
+
+项目支持两种运行模式：
 - **OpenAI 兼容模式**：提供标准的 OpenAI API 接口，便于集成到现有应用
 - **Queue 队列模式**：使用 Server-Sent Events (SSE) 实时推送生成状态

@@ -104,12 +106,19 @@ chrome:

 ## 📖 使用方法

-### 【重要】务必进行的步骤
- 第一次启动程序时必须关闭无头模式启动（**Linux无界面请看文档结尾**）
- 等待网页加载完毕后登录账号（否则会在使用几次后弹出登录界面阻止操作）
- 点击输入框输入任意内容点发送，等待弹出服务条款和CloudFlare Turnstile验证码
- 点击验证码并同意条款后再次点击发送，此时可能会弹出reCAPTCHA验证码，若出现也将其通过
- 后续可改为无头模式运行，但建议使用非无头模式避免频繁触发人机验证码
+### 首次使用重要指引
+
+#### 1. 首次启动与登录
+- **关闭无头模式**：第一次启动程序时，请务必关闭无头模式。（**Linux无界面用户请参阅文档结尾**）
+- **完成账号登录**：等待网页加载完毕后，请手动登录您的账号，以避免后续使用中弹出登录界面。
+
+#### 2. 验证流程
+- **触发验证**：在输入框中输入任意内容并发送，等待服务条款和CloudFlare Turnstile验证码弹出。
+- **通过验证**：点击验证码并同意服务条款，然后再次点击发送。此过程可能会弹出reCAPTCHA验证码，请一并完成。
+
+#### 3. 后续运行建议
+- **模式选择**：完成上述步骤后，您可以选择切换为无头模式运行。
+- **推荐模式**：为减少触发人机验证的频率，建议仍保持非无头模式运行。


 ### 方式一：使用 HTTP API
@@ -121,7 +130,7 @@ npm start

 #### OpenAI 兼容模式
 > [!WARNING]
-> 由于模拟真实用户的浏览器操作，一次只能进行一个任务，剩下的将会放入队列中等待，为防止客户端超时影响体验，该模式如果已经有3个任务时后来的任务将会直接返回错误代码，推荐使用Queue队列模式，服务器会向客户端发送心跳包以确保连接存活。
+> 由于模拟真实浏览器操作，每次只能处理一个任务，其余任务将进入队列等待。为避免客户端超时影响体验，若当前任务数已达3个，后续请求将直接返回错误。因此，强烈推荐使用队列模式（`queue`），该模式下服务器会向客户端发送心跳包以确保连接持续活跃。

 **配置文件设置**
 ```yaml
@@ -288,6 +297,8 @@ lmarena/

 **解决方案**:
 - 确保已安装 Chrome 或 Chromium
+  - 大陆地区设备可能因网络原因 Puppeteer 自动安装失败
+  - 可尝试手动安装后填写 `chrome.path` (Linux 可使用 `which` 指令检索路径)
 - 检查 `config.yaml` 中的 `chrome.path` 是否正确
 - 尝试删除 `data/chromeUserData` 目录后重新运行

@@ -321,7 +332,7 @@ chrome:
 - 建议：
  - 降低请求频率
  - 首次使用时手动完成一次验证 (关闭 headless 模式)
-  - 使用稳定和纯净的 IP 地址 (可使用 ping0.cc 查询IP地址纯净度)
+  - 使用稳定和纯净的 IP 地址 (可使用 [ping0.cc](https://ping0.cc) 查询IP地址纯净度)

 ### 图像生成超时

@@ -331,235 +342,47 @@ chrome:
 - 检查网络连接是否稳定
 - 某些复杂提示词可能需要更长时间

-### Linux下关闭无头模式运行
+### Linux 环境下非无头模式运行

-**问题**: 在Linux多用户模式下无界面运行浏览器
+**问题**: 需要在 Linux 服务器上显示浏览器界面（如手动过验证码）

 **解决方案**:

-方法一：X11转发（适用于后续无头模式运行）
- 推荐使用WindTerm开启右上角X-Server
- 在会话设置中的X11栏目中改为 “内部X11显示”
+**方法一：X11 转发 (轻量级)**
+- 推荐使用 WindTerm 等终端工具，开启 X-Server 功能
+- 在 SSH 会话设置中启用 X11 转发 (Forward X11)

-方法二：Xvfb+X11VNC（推荐）
- 使用xvfb创建虚拟显示器运行该程序，并且将虚拟显示器映射到VNC中便于后续管理（因为在后续使用中可能还会弹出reCAPTCHA验证码需要手动通过）
- 创建虚拟显示器并运行程序 (99为屏幕号，冲突可行更改)
-```
-xvfb-run --server-num=99 --server-args="-ac -screen 0 1280x720x16" npm start
-```
- 将虚拟显示器映射至VNC
-```
-x11vnc -display :99 -localhost -nopw -once -noxdamage -ncache 10
-```
- 后续可用RealVNC等程序通过5900端口连接（推荐使用SSH隧道转发不将VNC直接暴露在公网，然后VNC连接127.0.0.1）
-```
-ssh -L 5900:127.0.0.1:5900 root@服务器IP
-```
+**方法二：Xvfb + X11VNC (推荐)**
+使用虚拟显示器运行程序，并通过 VNC 远程查看。
+
+1. **启动虚拟显示器并运行程序** (屏幕号 99 可按需修改):
+   ```bash
+   xvfb-run --server-num=99 --server-args="-ac -screen 0 1280x720x16" npm start
+   ```
+
+2. **将虚拟显示器映射至 VNC**:
+   ```bash
+   x11vnc -display :99 -localhost -nopw -once -noxdamage -ncache 10
+   ```
+
+3. **建立 SSH 隧道连接 VNC** (安全推荐):
+   ```bash
+   # 在本地终端运行，将服务器 5900 端口映射到本地
+   ssh -L 5900:127.0.0.1:5900 root@服务器IP
+   ```
+   随后使用 VNC 客户端连接 `127.0.0.1:5900` 即可。

 ---

-## 📊 配置建议
-| 资源 | 最低配置 | 推荐配置 |
-|------|---------|---------|
-| CPU | 1核 | 2核及以上 |
-| 内存 | 1GB | 2GB 及以上 |
-server:
-  type: queue
-```
-
-**请求端点**
-```
-POST http://127.0.0.1:3000/v1/queue/join
-```
-
-**SSE 事件类型**
-
-| 事件类型 | 数据格式 | 说明 |
-|---------|---------|------|
-| `status` | `{status: "queued", position: 1}` | 任务已入队 |
-| `status` | `{status: "processing"}` | 开始处理 |
-| `result` | `{status: "completed", image: "base64..."}` | 生成成功 |
-| `result` | `{status: "error", msg: "错误信息"}` | 生成失败 |
-| `heartbeat` | 时间戳 | 保持连接 |
-| `done` | `"[DONE]"` | 流结束 |
-
-**Node.js 示例代码**
-```javascript
-import http from 'http';
-
-const options = {
-  hostname: '127.0.0.1',
-  port: 3000,
-  path: '/v1/queue/join',
-  method: 'POST',
-  headers: {
-    'Content-Type': 'application/json',
-    'Authorization': 'Bearer your-secret-key'
-  }
-};
-
-const req = http.request(options, (res) => {
-  res.on('data', (chunk) => {
-    const lines = chunk.toString().split('\n');
-    for (const line of lines) {
-      if (line.startsWith('event: ')) {
-        const event = line.substring(7).trim();
-        console.log('事件类型:', event);
-      } else if (line.startsWith('data: ')) {
-        const data = JSON.parse(line.substring(6));
-        console.log('数据:', data);
-      }
-    }
-  });
-});
-
-req.write(JSON.stringify({
-  messages: [{ role: "user", content: "a cute cat" }]
-}));
-req.end();
-```
-
-#### 带图片的请求
-
-**支持格式**：PNG、JPEG、GIF、WebP  
-**最大数量**：5 张图片  
-**数据格式**：Base64 编码
-
-**请求示例**
-```json
-{
-  "messages": [{
-    "role": "user",
-    "content": [
-      {
-        "type": "text",
-        "text": "make it more colorful"
-      },
-      {
-        "type": "image_url",
-        "image_url": {
-          "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
-        }
-      }
-    ]
-  }]
-}
-```
-
-### 方式二：使用CLI客户端脚本
-
-**启动CLI工具**
-```bash
-npm test
-```
-根据指引填写图片路径和提示词即可
-
---
-
-## 📁 项目结构
-
-```
-lmarena/
-├── server.js          # HTTP 服务器 (主入口)
-├── config.yaml        # 配置文件
-├── package.json       # 项目依赖
-├── lib/
-│   ├── lmarena.js     # 核心生图逻辑 (Puppeteer 操作)
-│   ├── config.js      # 配置加载器
-│   ├── genApiKey.js   # API 密钥生成工具
-│   └── test.js        # 功能测试脚本
-└── data/
-    ├── chromeUserData/  # Chrome 用户数据 (自动创建)
-    └── temp/            # 临时图片存储
-```
-
---
-
-## 🔧 常见问题
-
-### 浏览器启动失败
-
-**问题**: `Error: Failed to launch the browser process`
-
-**解决方案**:
- 确保已安装 Chrome 或 Chromium
- 检查 `config.yaml` 中的 `chrome.path` 是否正确
- 尝试删除 `data/chromeUserData` 目录后重新运行
-
-### GPU 相关错误
-
-**问题**: 无显卡服务器运行时出现 GPU 错误
-
-**解决方案**:
- 该报错并不会影响程序运行，但是强烈建议在无显卡的设备上关闭GPU加速
-```yaml
-chrome:
-  gpu: false  # 禁用 GPU 加速
-```
-
-### 请求被拒绝 (429 Too Many Requests)
-
-**问题**: 并发请求过多
-
-**解决方案**:
- 该问题仅存在于OpenAI兼容模式
- 当前限制：1 个并发 + 2 个排队 (总计 3 个)
- 修改 `server.js` 中的 `MAX_CONCURRENT` 和 `MAX_QUEUE_SIZE` (不建议，应为大多数客户端HTTP请求是有超时时间的)
- 等待当前任务完成后再提交新任务
-
-### reCAPTCHA 验证失败
-
-**问题**: 返回 `recaptcha validation failed`
-
-**解决方案**:
- 这是 LMArena 的人机验证机制
- 建议：
-  - 降低请求频率
-  - 首次使用时手动完成一次验证 (关闭 headless 模式)
-  - 使用稳定和纯净的 IP 地址 (可使用 ping0.cc 查询IP地址纯净度)
-
-### 图像生成超时
-
-**问题**: 任务超过 120 秒未完成
-
-**解决方案**:
- 检查网络连接是否稳定
- 某些复杂提示词可能需要更长时间
-
-### Linux下关闭无头模式运行
-
-**问题**: 在Linux多用户模式下无界面运行浏览器
-
-**解决方案**:
-
-方法一：X11转发（适用于后续无头模式运行）
- 推荐使用WindTerm开启右上角X-Server
- 在会话设置中的X11栏目中改为 “内部X11显示”
-
-方法二：Xvfb+X11VNC（推荐）
- 使用xvfb创建虚拟显示器运行该程序，并且将虚拟显示器映射到VNC中便于后续管理（因为在后续使用中可能还会弹出reCAPTCHA验证码需要手动通过）
- 创建虚拟显示器并运行程序 (99为屏幕号，冲突可行更改)
-```
-xvfb-run --server-num=99 --server-args="-ac -screen 0 1280x720x16" npm start
-```
- 将虚拟显示器映射至VNC
-```
-x11vnc -display :99 -localhost -nopw -once -noxdamage -ncache 10
-```
- 后续可用RealVNC等程序通过5900端口连接（推荐使用SSH隧道转发不将VNC直接暴露在公网，然后VNC连接127.0.0.1）
-```
-ssh -L 5900:127.0.0.1:5900 root@服务器IP
-```
-
---
-
-## 📊 配置建议
+## 📊 设备配置
 | 资源 | 最低配置 | 推荐配置 |
 |------|---------|---------|
 | CPU | 1核 | 2核及以上 |
 | 内存 | 1GB | 2GB 及以上 |

-参考：经测试可以在Oracle的1G1C免费机Debian环境下运行
+经测试，本项目可在以下环境中稳定运行：
+- Oracle 免费机：1C1G 配置，基于 Debian 系统。
+- 阿里云轻量应用服务器：2C2G 配置，基于 Debian 系统。

 ## 📄 许可证