From 55377de092afb0290a6aaafbd1b37dd80435b49c Mon Sep 17 00:00:00 2001 From: foxhui Date: Mon, 24 Nov 2025 02:08:54 +0800 Subject: [PATCH] docs: update project documentation in README.md --- README.md | 273 ++++++++++-------------------------------------------- 1 file changed, 48 insertions(+), 225 deletions(-) diff --git a/README.md b/README.md index 0272089..1df73d6 100644 --- a/README.md +++ b/README.md @@ -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 系统。 ## 📄 许可证