From 5d5cc2bb19dcea2898b3aae37d587e0937e11133 Mon Sep 17 00:00:00 2001 From: foxhui Date: Mon, 12 Jan 2026 01:54:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vitepress/config.js | 2 + docs/admin/optimization.md | 131 +++++++++++++++++++++++++++++++++ docs/config/overview.md | 26 +++++++ docs/en/admin/optimization.md | 134 ++++++++++++++++++++++++++++++++++ docs/en/config/overview.md | 26 +++++++ docs/en/guide/requirements.md | 4 + docs/guide/introduction.md | 6 +- docs/guide/requirements.md | 4 + 8 files changed, 330 insertions(+), 3 deletions(-) create mode 100644 docs/admin/optimization.md create mode 100644 docs/en/admin/optimization.md diff --git a/.vitepress/config.js b/.vitepress/config.js index 0a2674c..d1978a1 100644 --- a/.vitepress/config.js +++ b/.vitepress/config.js @@ -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' } ] } diff --git a/docs/admin/optimization.md b/docs/admin/optimization.md new file mode 100644 index 0000000..a807af1 --- /dev/null +++ b/docs/admin/optimization.md @@ -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 提示 +配置完成后，建议重启服务器以确保所有设置生效。 +::: + diff --git a/docs/config/overview.md b/docs/config/overview.md index b89389c..f50b402 100644 --- a/docs/config/overview.md +++ b/docs/config/overview.md @@ -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) diff --git a/docs/en/admin/optimization.md b/docs/en/admin/optimization.md new file mode 100644 index 0000000..d3364e6 --- /dev/null +++ b/docs/en/admin/optimization.md @@ -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. +::: diff --git a/docs/en/config/overview.md b/docs/en/config/overview.md index 92cff0c..f711451 100644 --- a/docs/en/config/overview.md +++ b/docs/en/config/overview.md @@ -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) diff --git a/docs/en/guide/requirements.md b/docs/en/guide/requirements.md index 76d210b..fb79453 100644 --- a/docs/en/guide/requirements.md +++ b/docs/en/guide/requirements.md @@ -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. diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md index b1be5cd..1651560 100644 --- a/docs/guide/introduction.md +++ b/docs/guide/introduction.md @@ -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` 接口查看当前配置下所有可用模型及其详细信息。 -✅目前支持；❌目前不支持，但未来可能会支持；🚫网站不支持, 未来是否在支持看网站具体情况； +✅目前支持；❌目前不支持，但未来可能会支持；🚫网站不支持, 未来是否在支持看网站具体情况；💧结果带水印且无法去除； ::: ## 项目截图 diff --git a/docs/guide/requirements.md b/docs/guide/requirements.md index 8232309..67eeccc 100644 --- a/docs/guide/requirements.md +++ b/docs/guide/requirements.md @@ -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)：运行流畅，项目开发测试所用机型