WebAI2API/docs/admin/troubleshooting.md

# 故障排查

常见问题的诊断和解决方法。

## 挂机相关

### 窗口主动置顶

**问题**：任务进行时浏览器窗口会主动置顶

**解决方案**：
- Windows 和 macOS 可单开一个虚拟桌面（Win + Tab）给程序单独使用
- Linux 使用 Xvfb 模式即可

## 请求相关

### 请求被拒绝 (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 版本