docs: 移除代码文件，初始化文档专用分支

2026-06-16 21:03:59 +08:00 · 2025-12-20 20:02:24 +08:00
parent e8123cca5d
commit 28cac21641
123 changed files with 28258 additions and 18637 deletions
@@ -0,0 +1,111 @@
+# Linux 部署
+
+在 Linux 服务器上运行 WebAI2API 的特殊配置说明。
+
+## 显示方式选择
+
+在 Linux 服务器上运行非无头模式时，需要配置显示环境。
+
+### 方式一：Xvfb + VNC (推荐)
+
+使用虚拟显示器运行程序，通过 VNC 远程查看。
+
+#### 使用内置命令
+
+```bash
+npm start -- -xvfb -vnc
+```
+
+这会自动：
+- 启动 Xvfb 虚拟显示器
+- 启动 x11vnc 服务器
+- 可通过 WebUI 直接查看 VNC 画面
+
+#### 手动配置
+
+如果内置命令无法满足需求：
+
+1. **启动虚拟显示器**
+
+```bash
+xvfb-run --server-num=99 --server-args="-ac -screen 0 1920x1080x24" npm start
+```
+
+2. **映射到 VNC**
+
+```bash
+x11vnc -display :99 -localhost -nopw -forever -noxdamage
+```
+
+## VNC 连接
+
+### 通过 SSH 隧道 (推荐)
+
+```bash
+# 本地终端
+ssh -L 5900:127.0.0.1:5900 root@服务器IP
+```
+
+然后使用 VNC 客户端连接 `127.0.0.1:5900`。
+
+### 通过 WebUI
+
+服务启动后，访问 WebUI 的「VNC 显示」页面即可直接查看。
+
+### 安装依赖
+
+### Ubuntu/Debian
+
+```bash
+sudo apt-get update
+sudo apt-get install xvfb x11vnc
+```
+
+### CentOS/RHEL
+
+```bash
+sudo yum install xorg-x11-server-Xvfb x11vnc
+```
+
+### Arch Linux
+
+```bash
+sudo pacman -S xorg-server-xvfb x11vnc
+```
+
+### 方式二：X11 转发
+
+适用于通过 SSH 连接服务器的场景。
+
+1. 在本地安装 X Server（如 VcXsrv、Xming）
+2. 使用支持 X11 转发的终端（如 WindTerm）
+3. 在 SSH 会话中启用 X11 转发
+
+```bash
+ssh -X user@server
+```
+
+## Docker 部署
+
+Docker 镜像已内置 Xvfb 和 VNC 支持：
+
+```bash
+docker run -d --name webai2api \
+  -p 3000:3000 -p 5900:5900 \
+  -v "$(pwd)/data:/app/data" \
+  -e LOGIN_MODE=true \
+  --shm-size=2gb \
+  foxhui/lmarena-imagen-automator:latest
+```
+
+通过 VNC 客户端连接 `localhost:5900` 完成登录。
+
+## 常见问题
+
+### 端口被占用
+
+如果 5900 端口已被占用，VNC 服务器会自动查找 5901-5999 范围内可用的端口。
+
+### 显示号冲突
+
+Xvfb 会自动从 50 开始查找可用的显示号，避免与现有 X 服务器冲突。
@@ -0,0 +1,134 @@
+# 故障排查
+
+常见问题的诊断和解决方法。
+
+## 请求相关
+
+### 请求被拒绝 (429 Too Many Requests)
+
+**问题**：并发请求过多，队列已满。
+
+**解决方案**：
+- 启用流式模式 (`stream: true`)，可无限排队
+- 减少并发请求数量
+- 增加 `queue.queueBuffer` 配置值
+
+### 请求超时
+
+**问题**：任务超过 120 秒未完成。
+
+**解决方案**：
+- 启用流式模式，利用心跳保活
+- 检查网络连接是否稳定
+- 某些复杂提示词可能需要更长时间
+
+## 验证相关
+
+### reCAPTCHA 验证失败
+
+**问题**：返回 `recaptcha validation failed`。
+
+**解决方案**：
+- 降低请求频率
+- 进入登录模式手动完成验证
+- 使用稳定纯净的 IP 地址
+- 检查 IP 纯净度：[ping0.cc](https://ping0.cc)
+
+### CloudFlare 挑战
+
+**问题**：浏览器卡在 CloudFlare 验证页面。
+
+**解决方案**：
+- 进入 VNC 手动完成验证
+- 更换 IP 地址
+- 避免使用数据中心 IP
+
+## 登录相关
+
+### 登录状态丢失
+
+**问题**：服务重启后需要重新登录。
+
+**解决方案**：
+- 确保 `data` 目录持久化
+- 检查 `userDataMark` 配置是否正确
+- 避免删除浏览器数据目录
+
+### OAuth 登录失败
+
+**问题**：Google 等 OAuth 登录跳转失败。
+
+**解决方案**：
+- 确保可以访问 accounts.google.com
+- 检查代理配置是否正确
+- 尝试更换 IP 地址
+
+## 浏览器相关
+
+### 浏览器启动失败
+
+**问题**：Camoufox 无法启动。
+
+**解决方案**：
+```bash
+# 重新初始化 Camoufox
+npm run init
+```
+
+### 内存不足
+
+**问题**：浏览器因内存不足崩溃。
+
+**解决方案**：
+- 增加服务器内存（建议 2GB+）
+- 减少同时运行的浏览器实例数量
+- Docker 环境确保设置 `--shm-size=2gb`
+
+## 网络相关
+
+### 代理连接失败
+
+**问题**：无法连接到代理服务器。
+
+**解决方案**：
+- 检查代理服务器地址和端口
+- 验证代理认证信息
+- 测试代理服务器是否正常
+
+### 目标网站不可访问
+
+**问题**：无法访问 LMArena/Gemini 等网站。
+
+**解决方案**：
+- 检查网络连接
+- 尝试使用代理
+- 确认目标网站未被封禁
+
+## 日志诊断
+
+### 查看详细日志
+
+在 `config.yaml` 中设置日志等级：
+
+```yaml
+logLevel: debug
+```
+
+### 常见日志信息
+
+| 日志内容 | 说明 |
+| --- | --- |
+| `工作池初始化失败` | 检查配置文件和网络 |
+| `Worker 不支持模型` | 检查模型名称是否正确 |
+| `验证超时` | 需要手动完成验证 |
+| `页面已关闭` | 浏览器可能崩溃 |
+
+## 获取帮助
+
+如果以上方法无法解决问题：
+
+1. 查看 [GitHub Issues](https://github.com/foxhui/WebAI2API/issues)
+2. 提交 Issue 并附上：
+   - 日志输出（设置 `logLevel: debug`）
+   - 配置文件（隐藏敏感信息）
+   - 操作系统和 Node.js 版本
@@ -0,0 +1,82 @@
+# Web 管理界面
+
+WebAI2API 提供了内置的 Web 管理界面，用于监控和管理服务。
+
+::: warning 注意
+WebUI 以及管理接口仅在握手阶段使用 API Token 验证，传输阶段无任何加密，如果您在公网环境使用，请使用 Caddy 或 Nginx 等专业的网站服务器对连接进行 HTTPS 加密！
+:::
+
+## 访问地址
+
+```
+http://localhost:3000
+```
+
+首次访问需要输入配置文件中设置的 API Token 进行认证。
+
+## 功能模块
+
+### 仪表盘
+
+仪表盘页面显示系统运行状态：
+
+- **系统状态**：版本、运行时间、运行模式
+- **业务统计**：窗口数量、实例数量
+- **队列状态**：处理中/等待中的任务列表
+
+### 系统管理
+
+系统管理页面提供：
+
+- **服务控制**
+  - 普通重启
+  - 登录模式重启
+  - 指定 Worker 登录
+  - 停止服务
+
+- **缓存管理**
+  - 查看临时文件
+  - 清理缓存
+
+- **数据管理**
+  - 查看浏览器数据目录
+  - 删除未使用的数据目录
+
+### VNC 显示
+
+在 Linux 环境下使用 `-xvfb -vnc` 启动时，可以通过 WebUI 直接查看和操作虚拟显示器：
+
+- 连接/断开 VNC
+- 全屏显示
+- 查看 VNC 状态信息
+
+::: tip 说明
+VNC 显示功能需要服务以 Xvfb + VNC 模式运行。
+:::
+
+### 配置管理
+
+- **服务器配置**：端口、认证、心跳设置
+- **适配器配置**：各后端的专属配置
+- **浏览器设置**：路径、无头模式、代理
+
+### 实例管理
+
+管理浏览器实例和 Worker 配置（需要重启生效）。
+
+## 快捷操作
+
+### 登录模式重启
+
+1. 进入「缓存与重启」页面
+2. 点击「重启」按钮旁的下拉箭头
+3. 选择重启模式：
+   - **普通重启**：正常模式重启
+   - **登录模式重启**：以 `-login` 参数重启
+   - **指定 Worker 登录**：选择特定 Worker 进入登录模式
+
+### 清理缓存
+
+1. 进入「缓存与重启」页面
+2. 找到「缓存管理」区域
+3. 点击「清理缓存」按钮