docs: 更新文档

2026-06-16 21:03:59 +08:00 · 2026-01-12 01:54:43 +08:00
parent 3b49cb4f55
commit 5d5cc2bb19
8 changed files with 330 additions and 3 deletions
@@ -59,6 +59,7 @@ export default defineConfig({
            items: [
              { text: 'Web 管理界面', link: '/admin/webui' },
              { text: 'Linux 部署', link: '/admin/linux' },
+              { text: 'Linux 低内存优化', link: '/admin/optimization' },
              { text: '故障排查', link: '/admin/troubleshooting' }
            ]
          }
@@ -109,6 +110,7 @@ export default defineConfig({
            items: [
              { text: 'Web UI', link: '/en/admin/webui' },
              { text: 'Linux Deployment', link: '/en/admin/linux' },
+              { text: 'Linux Optimization', link: '/en/admin/optimization' },
              { text: 'Troubleshooting', link: '/en/admin/troubleshooting' }
            ]
          }
@@ -0,0 +1,131 @@
+# Linux 低内存优化建议
+
+## 开启 SWAP
+
+1. 检查当前的 SWAP 情况
+   ```bash
+   sudo swapon --show
+   ```
+
+2. 创建 SWAP 文件
+   ```bash
+   fallocate -l 4G /swapfile
+   ```
+
+3. 设置权限
+   ```bash
+   chmod 600 /swapfile
+   ```
+
+4. 格式化并启用 SWAP
+   ```bash
+   mkswap /swapfile
+   swapon /swapfile
+   ```
+
+5. 设置开机自动挂载
+   ```bash
+   echo '/swapfile none swap sw 0 0' | tee -a /etc/fstab
+   ```
+
+## 开启 ZRAM
+
+### Debian / Ubuntu
+
+1. 安装
+   ```bash
+   apt update
+   apt install zram-tools -y
+   ```
+
+2. 修改配置文件
+   ```bash
+   nano /etc/default/zramswap
+   ```
+   
+   添加或修改以下内容：
+
+   ```bash
+   # 使用 zstd 压缩算法，速度和压缩率最平衡
+   ALGO=zstd
+
+   # 使用内存总量的 60% 作为 ZRAM 大小
+   PERCENT=60
+
+   # 【关键】设置优先级为 100。
+   # 只要这个数字比磁盘 Swap（通常是 -2）大，系统就会优先用 ZRAM。
+   PRIORITY=100
+   ```
+
+   按 `Ctrl+O` 回车保存，按 `Ctrl+X` 退出。
+
+3. 重启服务
+   ```bash
+   systemctl daemon-reload
+   systemctl restart zramswap
+   ```
+
+### CentOS / Arch Linux
+
+这些系统推荐使用 `zram-generator`。
+
+1. 安装
+   ```bash
+   # CentOS 8/9, Fedora, AlmaLinux, Rocky Linux
+   dnf install zram-generator -y
+
+   # Arch Linux
+   pacman -S zram-generator
+   ```
+
+2. 修改配置文件
+   创建或编辑 `/etc/systemd/zram-generator.conf`：
+
+   ```ini
+   [zram0]
+   # 使用内存总量的 60%
+   zram-size = ram * 0.6
+   # 使用 zstd 压缩算法
+   compression-algorithm = zstd
+   # 优先级高于磁盘 Swap
+   swap-priority = 100
+   ```
+
+3. 启动服务
+   ```bash
+   systemctl daemon-reload
+   systemctl start systemd-zram-setup@zram0
+   ```
+
+### 通用优化
+
+无论使用哪种系统，都建议调整 `swappiness` 以更积极地使用 ZRAM。
+
+```bash
+grep -q "vm.swappiness" /etc/sysctl.conf || echo "vm.swappiness=80" | tee -a /etc/sysctl.conf
+sysctl -p
+```
+
+## 关闭站点隔离 (fission.autostart)
+
+对于内存极度紧张（如 1GB 内存）的服务器，如果开启 SWAP 和 ZRAM 后仍然经常崩溃，可以作为**兜底方案**尝试关闭 Firefox 的站点隔离功能。
+
+::: warning 风险提示
+关闭站点隔离会降低浏览器的指纹独特性，可能导致更容易被高等级的反爬系统识别（如检测单进程模型或跨进程通信延迟）。请仅在必要时使用。
+:::
+
+1. 修改 `config.yaml` 配置文件：
+
+   ```yaml
+   browser:
+     # ...
+     # 关闭站点隔离以显著降低内存占用
+     fission: false
+   ```
+
+2. 重启 WebAI2API 服务。
+
+::: tip 提示
+配置完成后，建议重启服务器以确保所有设置生效。
+:::
+
@@ -42,10 +42,35 @@ queue:

 # 浏览器配置
 browser:
+  # 浏览器可执行文件路径 (留空则使用默认的)
+  # 非必要不建议修改，否则你要处理很多额外依赖
+  # Windows系统示例 "C:\\camoufox\\camoufox.exe"
+  # Linux系统示例 "/opt/camoufox/camoufox"
  path: ""
+  
+  # 是否启用无头模式
  headless: false
+
+  # 站点隔离 (fission.autostart)
+  # 开启保持 Firefox 默认开启状态
+  # 关闭此项可显著降低内存占用，防止低配服务器崩溃
+  # ⚠️ 风险提示: 正常 Firefox 用户默认开启 Fission，虽然关闭它不会泄露常规指纹，
+  # 但极高阶的反爬系统可能会通过检测“单进程模型”或“跨进程通信延迟”来识别自动化特征！
+  fission: true
+  
+  # [全局代理] 如果 Instance 没有独立配置代理，将使用此配置
  proxy:
+    # 是否启用代理
    enable: false
+    # 代理类型: http 或 socks5
+    type: http
+    # 代理主机
+    host: 127.0.0.1
+    # 代理端口
+    port: 7890
+    # 代理认证 (可选)
+    # user: username
+    # passwd: password
 ```

 ## 配置项说明
@@ -82,6 +107,7 @@ browser:
 | --- | --- | --- | --- |
 | `path` | string | `""` | Camoufox 可执行文件路径，留空使用默认 |
 | `headless` | boolean | `false` | 是否启用无头模式 |
+| `fission` | boolean | `true` | 是否启用站点隔离 (fission.autostart) |
 | `proxy` | object | - | 全局代理配置 |

 ### 适配器配置 (backend.adapter)
@@ -0,0 +1,134 @@
+::: info
+This English version is translated by **Gemini 3 Flash**.
+:::
+
+# Linux Low Memory Optimization
+
+## Enable SWAP
+
+1. Check current SWAP status
+   ```bash
+   sudo swapon --show
+   ```
+
+2. Create SWAP file
+   ```bash
+   fallocate -l 4G /swapfile
+   ```
+
+3. Set permissions
+   ```bash
+   chmod 600 /swapfile
+   ```
+
+4. Format and enable SWAP
+   ```bash
+   mkswap /swapfile
+   swapon /swapfile
+   ```
+
+5. Set auto-mount on boot
+   ```bash
+   echo '/swapfile none swap sw 0 0' | tee -a /etc/fstab
+   ```
+
+## Enable ZRAM
+
+### Debian / Ubuntu
+
+1. Install
+   ```bash
+   apt update
+   apt install zram-tools -y
+   ```
+
+2. Modify configuration file
+   ```bash
+   nano /etc/default/zramswap
+   ```
+   
+   Add or modify the following:
+
+   ```bash
+   # Use zstd compression algorithm for the best balance of speed and ratio
+   ALGO=zstd
+
+   # Use 60% of total memory as ZRAM size
+   PERCENT=60
+
+   # [Crucial] Set priority to 100.
+   # As long as this is higher than disk Swap (usually -2), the system will prioritize ZRAM.
+   PRIORITY=100
+   ```
+
+   Press `Ctrl+O` Enter to save, `Ctrl+X` to exit.
+
+3. Restart service
+   ```bash
+   systemctl daemon-reload
+   systemctl restart zramswap
+   ```
+
+### CentOS / Arch Linux
+
+Recommended to use `zram-generator` for these systems.
+
+1. Install
+   ```bash
+   # CentOS 8/9, Fedora, AlmaLinux, Rocky Linux
+   dnf install zram-generator -y
+
+   # Arch Linux
+   pacman -S zram-generator
+   ```
+
+2. Modify configuration file
+   Create or edit `/etc/systemd/zram-generator.conf`:
+
+   ```ini
+   [zram0]
+   # Use 60% of total memory
+   zram-size = ram * 0.6
+   # Use zstd compression algorithm
+   compression-algorithm = zstd
+   # Higher priority than disk Swap
+   swap-priority = 100
+   ```
+
+3. Start service
+   ```bash
+   systemctl daemon-reload
+   systemctl start systemd-zram-setup@zram0
+   ```
+
+### General Optimization
+
+Regardless of the system, it is recommended to adjust `swappiness` to use ZRAM more aggressively.
+
+```bash
+grep -q "vm.swappiness" /etc/sysctl.conf || echo "vm.swappiness=80" | tee -a /etc/sysctl.conf
+sysctl -p
+```
+
+## Disable Site Isolation (fission.autostart)
+
+For servers with extremely tight memory (e.g., 1GB RAM), if the system still crashes frequently after enabling SWAP and ZRAM, you can try disabling Firefox's Site Isolation as a **last resort**.
+
+::: warning Risk Disclosure
+Disabling Site Isolation reduces the uniqueness of the browser fingerprint, potentially making it easier for high-level anti-bot systems to identify (e.g., by detecting single-process model or inter-process communication delays). Use only when necessary.
+:::
+
+1. Modify `config.yaml`:
+
+   ```yaml
+   browser:
+     # ...
+     # Disable site isolation to significantly reduce memory footprint
+     fission: false
+   ```
+
+2. Restart WebAI2API service.
+
+::: tip Tip
+After completing the configuration, it is recommended to restart the server to ensure all settings take effect.
+:::
@@ -46,10 +46,35 @@ queue:

 # Browser Configuration
 browser:
+  # Path to browser executable (leave empty for default)
+  # Modification is not recommended unless necessary, as you may need to handle extra dependencies
+  # Windows example: "C:\\camoufox\\camoufox.exe"
+  # Linux example: "/opt/camoufox/camoufox"
  path: ""
+  
+  # Whether to enable headless mode
  headless: false
+
+  # Site Isolation (fission.autostart)
+  # Keep enabled for standard Firefox behavior
+  # Disabling this can significantly reduce memory usage and prevent crashes on low-end servers
+  # ⚠️ Risk: Normal Firefox users have Fission enabled by default. While disabling it does not leak common fingerprints, 
+  # extremely advanced anti-bot systems might identify automated features via "single-process model" or "IPC delays".
+  fission: true
+  
+  # [Global Proxy] Used if an Instance does not have its own proxy configuration
  proxy:
+    # Whether to enable proxy
    enable: false
+    # Proxy type: http or socks5
+    type: http
+    # Proxy host
+    host: 127.0.0.1
+    # Proxy port
+    port: 7890
+    # Proxy authentication (optional)
+    # user: username
+    # passwd: password
 ```

 ## Configuration Items
@@ -86,6 +111,7 @@ browser:
 | --- | --- | --- | --- |
 | `path` | string | `""` | Path to Camoufox executable. Leave empty to use default. |
 | `headless` | boolean | `false` | Whether to enable headless mode. |
+| `fission` | boolean | `true` | Whether to enable Site Isolation (fission.autostart). |
 | `proxy` | object | - | Global proxy configuration. |

 ### Adapter Configuration (backend.adapter)
@@ -21,6 +21,10 @@ Before you start deploying WebAI2API, please ensure that your environment meets
 | **CPU** | 1 Core | 2 Cores or above | 2 Cores or above |
 | **Memory** | 1 GB | 2 GB or above | 4 GB or above |
 | **Disk** | 2 GB available | 5 GB or above | 7 GB or above |
+ 
+::: tip Optimization Suggestions
+For low-end servers with 1-2 GB of RAM, it is strongly recommended to enable **SWAP** or **ZRAM** to improve system stability and performance. Refer to [Linux Low Memory Optimization](/en/admin/optimization) for details.
+:::

 ::: tip Real-world Performance
 - **Oracle Free Tier** (1C1G, Debian 12): Limited resources, can be laggy, suitable for testing or light use only.
@@ -12,11 +12,11 @@
 | [**Gemini Enterprise Business**](https://business.gemini.google/) | ✅ | ✅ | ✅ |
 | [**Nano Banana Free**](https://nanobananafree.ai/) | 🚫 | ✅ | 🚫 |
 | [**zAI**](https://zai.is/) | ✅ | ✅ | 🚫 |
-| [**Google Gemini**](https://gemini.google.com/) | ✅ | ✅ | ✅ | 
+| [**Google Gemini**](https://gemini.google.com/) | ✅ | ✅💧 | ✅💧 | 
 | [**ZenMux**](https://zenmux.ai/) | ✅ | ❌ | 🚫 | 
 | [**ChatGPT**](https://chatgpt.com/) | ✅ | ✅ | 🚫 | 
 | [**DeepSeek**](https://chat.deepseek.com/) | ✅ | 🚫 | 🚫 | 
-| [**Sora**](https://sora.chatgpt.com/) | 🚫 | 🚫 | ✅ | 
+| [**Sora**](https://sora.chatgpt.com/) | 🚫 | 🚫 | ✅💧 | 
 | [**Google Flow**](https://labs.google/fx/zh/tools/flow) | 🚫 | ✅ | ❌ | 
 | [**豆包**](https://www.doubao.com/) | ✅ | ✅ | ❌ | 
 | 待续... | - | - | - | 
@@ -24,7 +24,7 @@
 ::: tip 实测环境表现
 **获取完整模型列表**: 通过 `GET /v1/models` 接口查看当前配置下所有可用模型及其详细信息。

-✅目前支持；❌目前不支持，但未来可能会支持；🚫网站不支持, 未来是否在支持看网站具体情况；
+✅目前支持；❌目前不支持，但未来可能会支持；🚫网站不支持, 未来是否在支持看网站具体情况；💧结果带水印且无法去除；
 :::

 ## 项目截图
@@ -18,6 +18,10 @@
 | **内存** | 1 GB | 2 GB 及以上 | 4 GB 及以上 |
 | **磁盘** | 2 GB 可用空间 | 5 GB 及以上 | 7 GB 及以上 |

+::: tip 优化建议
+对于内存为 1-2 GB 的低配服务器，强烈建议开启 **SWAP** 或 **ZRAM** 以提升系统稳定性并优化运行体验，操作方法请参考 [Linux 低内存优化](/admin/optimization)。
+:::
+
 ::: tip 实测环境表现
 - **Oracle 免费机** (1C1G, Debian 12)：资源紧张，比较卡顿，仅供尝鲜或轻度使用
 - **阿里云轻量云** (2C2G, Debian 11)：运行流畅，项目开发测试所用机型