chore: update docs

2026-03-31 15:36:15 +08:00
parent 4ca87111c8
commit 8879e7002f
13 changed files with 276 additions and 33 deletions
@@ -1,32 +1,51 @@
 # 浏览器示例

-`example/playwright` 提供了一组远程浏览器脚本示例，用于连接 Browserless / Chromium 服务，并完成一次最小可用的页面访问与截图。
+`example/playwright` 提供了一组远程浏览器脚本示例，演示如何连接 **Browserless**。

-目录结构如下：
+> [!NOTE]
+> 本示例以 Browserless 为主要演示对象。以此类推，您也可以使用其他的浏览器镜像（如原生的 `headless-shell` 或其他的浏览器集群服务）进行部署，只要它们支持 CDP 协议。

-```text
-example/
-└── playwright/
-    ├── playwright.js
-    ├── playwright.py
-    └── readme.md
-```
+---

- `playwright.js`：Node.js 示例，使用 `puppeteer-core` 连接 Browserless
- `playwright.py`：Python 示例，使用 `playwright` 连接 Browserless
+## 部署方式对比

-其中 Python 的 `playwright` 是目前最主流、也最接近 Puppeteer 使用体验的方案。
-同时建议在白虎中为 Python 示例安装并使用 Python `3.11` 版本，因为过高版本的 Python 可能会出现依赖安装失败。
+白虎面板强烈建议采用 **单独部署浏览器服务（如 Browserless）** 的方案，而不是在白虎镜像内部安装浏览器。

-## 先安装语言依赖
+### 本地部署 (在白虎容器内安装) 的缺点
+- **资源争抢**：浏览器是极度的“内存/CPU 杀手”，在同一容器内运行多任务极易导致白虎主进程因 OOM (内存溢出) 而崩溃。
+- **镜像臃肿**：安装 Chromium 后，原本精简的 Docker 镜像体积会暴增数倍（增加 500MB+），导致拉取和更新缓慢。
+- **依赖环境复杂**：在精简镜像中安装浏览器常会遇到各种缺失 `.so` 库文件的底层错误，排查极其困难。
+- **不利于扩展**：无法实现多节点负载均衡，一个容器内的资源始终是有限的。

-运行脚本前，请先到白虎的“语言依赖”页面安装对应的包，否则任务会因为缺少模块而失败。
+### 远程部署 (Browserless) 的优势
+- **性能隔离**：浏览器的负载波动不会影响白虎面板的稳定性。
+- **开箱即用**：专业的浏览器镜像是针对性优化的，包含所有底层依赖和沙箱安全配置。
+- **可视化调试**：大多数服务（如 Browserless）支持通过 VNC 同步查看浏览器画面，方便排查脚本逻辑。
+- **弹性伸缩**：支持多会话、多实例模式，可以应对高并发爬虫需求。

- 运行 `playwright.js` 前，请在 Node.js 语言依赖中安装：`puppeteer-core`
- 运行 `playwright.py` 前，请在 Python 语言依赖中安装：`playwright`
- Python 运行环境建议选择：`3.11`，避免因为版本过高导致依赖安装失败
+---

-安装完成后，再创建任务执行对应脚本。
+## 准备工作
+
+在白虎面板中运行浏览器自动化脚本前，需要先配置好对应的 **语言环境** 与 **第三方依赖包**。
+
+### 1. Node.js 环境 (JavaScript)
+如果您使用 `playwright.js` 脚本：
+- **依赖安装**：前往「语言依赖」->「Node.js」，安装 `puppeteer-core`。
+- **说明**：该脚本使用 `puppeteer-core` 通过 CDP 协议连接远程浏览器，无需安装完整的 puppeteer 及其内置浏览器。
+
+### 2. Python 环境
+如果您使用 `playwright.py` 脚本：
+- **版本推荐**：建议在「语言环境」中安装并使用 **Python 3.11**。
+    > [!TIP]
+    > 建议避开更高版本的 Python（如 3.12+），因为目前部分 Playwright 依赖在极新版本的 Python 环境下可能会遭遇编译或安装失败。
+- **依赖安装**：前往「语言依赖」->「Python」，安装 `playwright`。
+
+---
+
+配置完成后，即可创建定时任务并关联对应的脚本文件。
+
+## Browserless 连接要点

 如果你当前是通过 Browserless 连接远程浏览器：