Skip to content

Commit 5d5cc2b

Browse files
foxhuifoxhui
committed
docs: 更新文档
1 parent 3b49cb4 commit 5d5cc2b

File tree

8 files changed

+330
-3
lines changed

8 files changed

+330
-3
lines changed

‎.vitepress/config.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ export default defineConfig({
5959
items: [
6060
{ text: 'Web 管理界面', link: '/admin/webui' },
6161
{ text: 'Linux 部署', link: '/admin/linux' },
62+
{ text: 'Linux 低内存优化', link: '/admin/optimization' },
6263
{ text: '故障排查', link: '/admin/troubleshooting' }
6364
]
6465
}
@@ -109,6 +110,7 @@ export default defineConfig({
109110
items: [
110111
{ text: 'Web UI', link: '/en/admin/webui' },
111112
{ text: 'Linux Deployment', link: '/en/admin/linux' },
113+
{ text: 'Linux Optimization', link: '/en/admin/optimization' },
112114
{ text: 'Troubleshooting', link: '/en/admin/troubleshooting' }
113115
]
114116
}

‎docs/admin/optimization.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Linux 低内存优化建议
2+
3+
## 开启 SWAP
4+
5+
1. 检查当前的 SWAP 情况
6+
```bash
7+
sudo swapon --show
8+
```
9+
10+
2. 创建 SWAP 文件
11+
```bash
12+
fallocate -l 4G /swapfile
13+
```
14+
15+
3. 设置权限
16+
```bash
17+
chmod 600 /swapfile
18+
```
19+
20+
4. 格式化并启用 SWAP
21+
```bash
22+
mkswap /swapfile
23+
swapon /swapfile
24+
```
25+
26+
5. 设置开机自动挂载
27+
```bash
28+
echo '/swapfile none swap sw 0 0' | tee -a /etc/fstab
29+
```
30+
31+
## 开启 ZRAM
32+
33+
### Debian / Ubuntu
34+
35+
1. 安装
36+
```bash
37+
apt update
38+
apt install zram-tools -y
39+
```
40+
41+
2. 修改配置文件
42+
```bash
43+
nano /etc/default/zramswap
44+
```
45+
46+
添加或修改以下内容：
47+
48+
```bash
49+
# 使用 zstd 压缩算法，速度和压缩率最平衡
50+
ALGO=zstd
51+
52+
# 使用内存总量的 60% 作为 ZRAM 大小
53+
PERCENT=60
54+
55+
# 【关键】设置优先级为 100。
56+
# 只要这个数字比磁盘 Swap（通常是 -2）大，系统就会优先用 ZRAM。
57+
PRIORITY=100
58+
```
59+
60+
按 `Ctrl+O` 回车保存，按 `Ctrl+X` 退出。
61+
62+
3. 重启服务
63+
```bash
64+
systemctl daemon-reload
65+
systemctl restart zramswap
66+
```
67+
68+
### CentOS / Arch Linux
69+
70+
这些系统推荐使用 `zram-generator`。
71+
72+
1. 安装
73+
```bash
74+
# CentOS 8/9, Fedora, AlmaLinux, Rocky Linux
75+
dnf install zram-generator -y
76+
77+
# Arch Linux
78+
pacman -S zram-generator
79+
```
80+
81+
2. 修改配置文件
82+
创建或编辑 `/etc/systemd/zram-generator.conf`：
83+
84+
```ini
85+
[zram0]
86+
# 使用内存总量的 60%
87+
zram-size = ram * 0.6
88+
# 使用 zstd 压缩算法
89+
compression-algorithm = zstd
90+
# 优先级高于磁盘 Swap
91+
swap-priority = 100
92+
```
93+
94+
3. 启动服务
95+
```bash
96+
systemctl daemon-reload
97+
systemctl start systemd-zram-setup@zram0
98+
```
99+
100+
### 通用优化
101+
102+
无论使用哪种系统，都建议调整 `swappiness` 以更积极地使用 ZRAM。
103+
104+
```bash
105+
grep -q "vm.swappiness" /etc/sysctl.conf || echo "vm.swappiness=80" | tee -a /etc/sysctl.conf
106+
sysctl -p
107+
```
108+
109+
## 关闭站点隔离 (fission.autostart)
110+
111+
对于内存极度紧张（如 1GB 内存）的服务器，如果开启 SWAP 和 ZRAM 后仍然经常崩溃，可以作为**兜底方案**尝试关闭 Firefox 的站点隔离功能。
112+
113+
::: warning 风险提示
114+
关闭站点隔离会降低浏览器的指纹独特性，可能导致更容易被高等级的反爬系统识别（如检测单进程模型或跨进程通信延迟）。请仅在必要时使用。
115+
:::
116+
117+
1. 修改 `config.yaml` 配置文件：
118+
119+
```yaml
120+
browser:
121+
# ...
122+
# 关闭站点隔离以显著降低内存占用
123+
fission: false
124+
```
125+
126+
2. 重启 WebAI2API 服务。
127+
128+
::: tip 提示
129+
配置完成后，建议重启服务器以确保所有设置生效。
130+
:::
131+

‎docs/config/overview.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,35 @@ queue:
4242

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

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

87113
### 适配器配置 (backend.adapter)

‎docs/en/admin/optimization.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
::: info
2+
This English version is translated by **Gemini 3 Flash**.
3+
:::
4+
5+
# Linux Low Memory Optimization
6+
7+
## Enable SWAP
8+
9+
1. Check current SWAP status
10+
```bash
11+
sudo swapon --show
12+
```
13+
14+
2. Create SWAP file
15+
```bash
16+
fallocate -l 4G /swapfile
17+
```
18+
19+
3. Set permissions
20+
```bash
21+
chmod 600 /swapfile
22+
```
23+
24+
4. Format and enable SWAP
25+
```bash
26+
mkswap /swapfile
27+
swapon /swapfile
28+
```
29+
30+
5. Set auto-mount on boot
31+
```bash
32+
echo '/swapfile none swap sw 0 0' | tee -a /etc/fstab
33+
```
34+
35+
## Enable ZRAM
36+
37+
### Debian / Ubuntu
38+
39+
1. Install
40+
```bash
41+
apt update
42+
apt install zram-tools -y
43+
```
44+
45+
2. Modify configuration file
46+
```bash
47+
nano /etc/default/zramswap
48+
```
49+
50+
Add or modify the following:
51+
52+
```bash
53+
# Use zstd compression algorithm for the best balance of speed and ratio
54+
ALGO=zstd
55+
56+
# Use 60% of total memory as ZRAM size
57+
PERCENT=60
58+
59+
# [Crucial] Set priority to 100.
60+
# As long as this is higher than disk Swap (usually -2), the system will prioritize ZRAM.
61+
PRIORITY=100
62+
```
63+
64+
Press `Ctrl+O` Enter to save, `Ctrl+X` to exit.
65+
66+
3. Restart service
67+
```bash
68+
systemctl daemon-reload
69+
systemctl restart zramswap
70+
```
71+
72+
### CentOS / Arch Linux
73+
74+
Recommended to use `zram-generator` for these systems.
75+
76+
1. Install
77+
```bash
78+
# CentOS 8/9, Fedora, AlmaLinux, Rocky Linux
79+
dnf install zram-generator -y
80+
81+
# Arch Linux
82+
pacman -S zram-generator
83+
```
84+
85+
2. Modify configuration file
86+
Create or edit `/etc/systemd/zram-generator.conf`:
87+
88+
```ini
89+
[zram0]
90+
# Use 60% of total memory
91+
zram-size = ram * 0.6
92+
# Use zstd compression algorithm
93+
compression-algorithm = zstd
94+
# Higher priority than disk Swap
95+
swap-priority = 100
96+
```
97+
98+
3. Start service
99+
```bash
100+
systemctl daemon-reload
101+
systemctl start systemd-zram-setup@zram0
102+
```
103+
104+
### General Optimization
105+
106+
Regardless of the system, it is recommended to adjust `swappiness` to use ZRAM more aggressively.
107+
108+
```bash
109+
grep -q "vm.swappiness" /etc/sysctl.conf || echo "vm.swappiness=80" | tee -a /etc/sysctl.conf
110+
sysctl -p
111+
```
112+
113+
## Disable Site Isolation (fission.autostart)
114+
115+
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**.
116+
117+
::: warning Risk Disclosure
118+
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.
119+
:::
120+
121+
1. Modify `config.yaml`:
122+
123+
```yaml
124+
browser:
125+
# ...
126+
# Disable site isolation to significantly reduce memory footprint
127+
fission: false
128+
```
129+
130+
2. Restart WebAI2API service.
131+
132+
::: tip Tip
133+
After completing the configuration, it is recommended to restart the server to ensure all settings take effect.
134+
:::

‎docs/en/config/overview.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,10 +46,35 @@ queue:
4646

4747
# Browser Configuration
4848
browser:
49+
# Path to browser executable (leave empty for default)
50+
# Modification is not recommended unless necessary, as you may need to handle extra dependencies
51+
# Windows example: "C:\\camoufox\\camoufox.exe"
52+
# Linux example: "/opt/camoufox/camoufox"
4953
path: ""
54+
55+
# Whether to enable headless mode
5056
headless: false
57+
58+
# Site Isolation (fission.autostart)
59+
# Keep enabled for standard Firefox behavior
60+
# Disabling this can significantly reduce memory usage and prevent crashes on low-end servers
61+
# ⚠️ Risk: Normal Firefox users have Fission enabled by default. While disabling it does not leak common fingerprints,
62+
# extremely advanced anti-bot systems might identify automated features via "single-process model" or "IPC delays".
63+
fission: true
64+
65+
# [Global Proxy] Used if an Instance does not have its own proxy configuration
5166
proxy:
67+
# Whether to enable proxy
5268
enable: false
69+
# Proxy type: http or socks5
70+
type: http
71+
# Proxy host
72+
host: 127.0.0.1
73+
# Proxy port
74+
port: 7890
75+
# Proxy authentication (optional)
76+
# user: username
77+
# passwd: password
5378
```
5479

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

91117
### Adapter Configuration (backend.adapter)

‎docs/en/guide/requirements.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@ Before you start deploying WebAI2API, please ensure that your environment meets
2121
| **CPU** | 1 Core | 2 Cores or above | 2 Cores or above |
2222
| **Memory** | 1 GB | 2 GB or above | 4 GB or above |
2323
| **Disk** | 2 GB available | 5 GB or above | 7 GB or above |
24+
25+
::: tip Optimization Suggestions
26+
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.
27+
:::
2428

2529
::: tip Real-world Performance
2630
- **Oracle Free Tier** (1C1G, Debian 12): Limited resources, can be laggy, suitable for testing or light use only.

0 commit comments

Comments
 (0)