mirror of
https://github.com/foxhui/WebAI2API.git
synced 2026-06-16 21:03:59 +08:00
docs: 增加英语文档，完善文档
This commit is contained in:
foxhui
@@ -0,0 +1,88 @@
|
||||
::: info
|
||||
This English version is translated by **Gemini 3 Flash**.
|
||||
:::
|
||||
|
||||
# Linux Deployment
|
||||
|
||||
[Docker users can ignore this] Special configuration instructions for running WebAI2API on Linux servers.
|
||||
|
||||
## 1. Install Necessary Dependencies
|
||||
|
||||
Essential dependencies for Linux command-line mode that allow you to run graphical applications in a Linux environment without a desktop environment.
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 2. Run the Program
|
||||
|
||||
Run the program using a virtual display and view it remotely via VNC. (The program will handle all the setup for you.)
|
||||
|
||||
```bash
|
||||
npm start -- -xvfb -vnc
|
||||
```
|
||||
|
||||
This will automatically:
|
||||
- Start the Xvfb virtual display.
|
||||
- Start the x11vnc server.
|
||||
- Allow you to view the VNC screen directly through the WebUI.
|
||||
|
||||
## 3. Connecting to the Program
|
||||
|
||||
### Via WebUI (Recommended)
|
||||
|
||||
Once the service is started, visit the "VNC Display" page in the WebUI to view it directly.
|
||||
|
||||
### Via SSH Tunnel
|
||||
|
||||
::: tip Tip
|
||||
The port might not always be 5900; the program will automatically search for an available VNC port in the range 5900-5999.
|
||||
:::
|
||||
|
||||
```bash
|
||||
# In your local terminal
|
||||
ssh -L 5900:127.0.0.1:5900 root@Server_IP
|
||||
```
|
||||
|
||||
Then use a VNC client to connect to `127.0.0.1:5900`.
|
||||
|
||||
## Alternative Method: Terminal X11 Forwarding
|
||||
|
||||
This method is not recommended unless you prefer to configure your own environment.
|
||||
|
||||
1. Install an X Server locally (e.g., VcXsrv, Xming).
|
||||
2. Use a terminal that supports X11 forwarding (e.g., WindTerm).
|
||||
3. Enable X11 forwarding in your SSH session.
|
||||
|
||||
```bash
|
||||
ssh -X user@server
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
### Port Already Occupied
|
||||
|
||||
If port 5900 is already in use, the VNC server will automatically look for an available port in the 5901-5999 range.
|
||||
|
||||
### Display Number Conflict
|
||||
|
||||
Xvfb will automatically search for an available display number starting from 50 to avoid conflicts with existing X servers.
|
||||
|
||||
### Unable to Connect to VNC
|
||||
|
||||
Please check if the dependencies were installed successfully.
|
||||
@@ -0,0 +1,148 @@
|
||||
::: info
|
||||
This English version is translated by **Gemini 3 Flash**.
|
||||
:::
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
Diagnosis and solutions for common problems.
|
||||
|
||||
## Operational Issues
|
||||
|
||||
### Window Forcing Itself to Foreground
|
||||
|
||||
**Problem**: The browser window actively brings itself to the foreground during a task.
|
||||
|
||||
**Solution**:
|
||||
- On Windows and macOS, you can use a separate virtual desktop (Win + Tab) specifically for the program.
|
||||
- On Linux, use Xvfb mode.
|
||||
|
||||
## Request Issues
|
||||
|
||||
### Request Rejected (429 Too Many Requests)
|
||||
|
||||
**Problem**: Too many concurrent requests; the queue is full.
|
||||
|
||||
**Solution**:
|
||||
- Enable streaming mode (`stream: true`), which allows for unlimited queuing.
|
||||
- Reduce the number of concurrent requests.
|
||||
- Increase the `queue.queueBuffer` value in your configuration.
|
||||
|
||||
### Request Timeout
|
||||
|
||||
**Problem**: The task did not complete within 120 seconds.
|
||||
|
||||
**Solution**:
|
||||
- Enable streaming mode and use the heartbeat mechanism to keep the connection alive.
|
||||
- Check if your network connection is stable.
|
||||
- Some complex prompts may simply require more time.
|
||||
|
||||
## Verification Issues
|
||||
|
||||
### reCAPTCHA Failure
|
||||
|
||||
**Problem**: Returns `recaptcha validation failed`.
|
||||
|
||||
**Solution**:
|
||||
- Reduce the frequency of requests.
|
||||
- Enter Login Mode to complete the verification manually.
|
||||
- Use a stable and clean IP address.
|
||||
- Check IP cleanliness using tools like [ping0.cc](https://ping0.cc).
|
||||
|
||||
### Cloudflare Challenge
|
||||
|
||||
**Problem**: The browser is stuck on the Cloudflare verification page.
|
||||
|
||||
**Solution**:
|
||||
- Use VNC to complete the verification manually.
|
||||
- Change your IP address.
|
||||
- Avoid using datacenter IPs.
|
||||
|
||||
## Login Issues
|
||||
|
||||
### Login State Lost
|
||||
|
||||
**Problem**: You are asked to log in again after a service restart.
|
||||
|
||||
**Solution**:
|
||||
- Ensure the `data` directory is persistent.
|
||||
- Verify that the `userDataMark` configuration is correct.
|
||||
- Avoid deleting browser data directories.
|
||||
|
||||
### OAuth Login Failure
|
||||
|
||||
**Problem**: Login redirects via Google or other OAuth providers fail.
|
||||
|
||||
**Solution**:
|
||||
- Ensure `accounts.google.com` is accessible.
|
||||
- Check if your proxy configuration is correct.
|
||||
- Try changing your IP address.
|
||||
|
||||
## Browser Issues
|
||||
|
||||
### Browser Fails to Start
|
||||
|
||||
**Problem**: Camoufox cannot start.
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Re-initialize Camoufox
|
||||
npm run init
|
||||
```
|
||||
|
||||
### Out of Memory
|
||||
|
||||
**Problem**: The browser crashes due to insufficient memory.
|
||||
|
||||
**Solution**:
|
||||
- Increase server RAM (2GB+ recommended).
|
||||
- Reduce the number of simultaneously running browser instances.
|
||||
- Ensure `--shm-size=2gb` is set in Docker environments.
|
||||
|
||||
## Network Issues
|
||||
|
||||
### Proxy Connection Failed
|
||||
|
||||
**Problem**: Unable to connect to the proxy server.
|
||||
|
||||
**Solution**:
|
||||
- Check the proxy server address and port.
|
||||
- Verify proxy authentication credentials.
|
||||
- Test if the proxy server is working correctly.
|
||||
|
||||
### Target Website Inaccessible
|
||||
|
||||
**Problem**: Unable to access sites like LMArena or Gemini.
|
||||
|
||||
**Solution**:
|
||||
- Check your network connectivity.
|
||||
- Try using a proxy.
|
||||
- Confirm the target website is not blocked.
|
||||
|
||||
## Log Diagnosis
|
||||
|
||||
### View Detailed Logs
|
||||
|
||||
Set the log level in `config.yaml`:
|
||||
|
||||
```yaml
|
||||
logLevel: debug
|
||||
```
|
||||
|
||||
### Common Log Messages
|
||||
|
||||
| Log Content | Description |
|
||||
| --- | --- |
|
||||
| `Worker pool initialization failed` | Check configuration and network. |
|
||||
| `Worker does not support model` | Verify if the model name is correct. |
|
||||
| `Verification timeout` | Manual verification is required. |
|
||||
| `Page closed` | The browser may have crashed. |
|
||||
|
||||
## Getting Help
|
||||
|
||||
If the above methods do not resolve your issue:
|
||||
|
||||
1. Check [GitHub Issues](https://github.com/foxhui/WebAI2API/issues).
|
||||
2. Submit an Issue including:
|
||||
- Log output (with `logLevel: debug`).
|
||||
- Your configuration file (hide sensitive information).
|
||||
- Your OS and Node.js version.
|
||||
@@ -0,0 +1,87 @@
|
||||
::: info
|
||||
This English version is translated by **Gemini 3 Flash**.
|
||||
:::
|
||||
|
||||
# Web Management Interface
|
||||
|
||||
WebAI2API provides a built-in Web Management Interface (WebUI) for monitoring and managing the service.
|
||||
|
||||
::: warning Note
|
||||
The WebUI and management interfaces only use the API Token for authentication during the handshake phase. Transmissions are not encrypted. If you are using this on a public network, please use a professional web server like Caddy or Nginx to provide HTTPS encryption!
|
||||
:::
|
||||
|
||||
## Access URL
|
||||
|
||||
```
|
||||
http://localhost:3000
|
||||
```
|
||||
|
||||
On your first visit, you will need to enter the API Token set in your configuration file (`auth` field) for authentication.
|
||||
|
||||
## Functional Modules
|
||||
|
||||
### Dashboard
|
||||
|
||||
The dashboard displays the system's operational status:
|
||||
|
||||
- **System Status**: Version, uptime, and running mode.
|
||||
- **Business Statistics**: Number of windows and instances.
|
||||
- **Queue Status**: Lists of tasks currently being processed or waiting in the queue.
|
||||
|
||||
### System Management
|
||||
|
||||
The system management page provides:
|
||||
|
||||
- **Service Control**
|
||||
- Normal Restart
|
||||
- Restart in Login Mode
|
||||
- Specific Worker Login
|
||||
- Stop Service
|
||||
- Adapter Settings (descriptions, model management, feature toggles)
|
||||
|
||||
- **Cache Management**
|
||||
- View temporary files.
|
||||
- Clear cache.
|
||||
|
||||
- **Data Management**
|
||||
- View browser data directories.
|
||||
- Delete unused data directories.
|
||||
|
||||
### VNC Display
|
||||
|
||||
When starting with `-xvfb -vnc` in a Linux environment, you can view and operate the virtual display directly through the WebUI:
|
||||
|
||||
- Connect/Disconnect VNC.
|
||||
- Full-screen mode.
|
||||
- View VNC status information.
|
||||
|
||||
::: tip Note
|
||||
The VNC display feature requires the service to be running in Xvfb + VNC mode.
|
||||
:::
|
||||
|
||||
### Configuration Management
|
||||
|
||||
- **Server Configuration**: Port, authentication, and heartbeat settings.
|
||||
- **Adapter Configuration**: Exclusive settings for each backend.
|
||||
- **Browser Settings**: Path, headless mode, and proxy settings.
|
||||
|
||||
### Instance Management
|
||||
|
||||
Manage browser instance and Worker configurations (requires a restart to take effect).
|
||||
|
||||
## Quick Actions
|
||||
|
||||
### Restarting in Login Mode
|
||||
|
||||
1. Go to the "Cache & Restart" page.
|
||||
2. Click the dropdown arrow next to the "Restart" button.
|
||||
3. Select the restart mode:
|
||||
- **Normal Restart**: Restarts in standard mode.
|
||||
- **Login Mode Restart**: Restarts with the `-login` parameter.
|
||||
- **Specific Worker Login**: Select a specific Worker to enter login mode.
|
||||
|
||||
### Clearing Cache
|
||||
|
||||
1. Go to the "Cache & Restart" page.
|
||||
2. Find the "Cache Management" area.
|
||||
3. Click the "Clear Cache" button.
|
||||
Reference in New Issue
Block a user