From 8879e7002f71f11f039ae077dd20ad317b1c0405 Mon Sep 17 00:00:00 2001 From: engigu Date: Tue, 31 Mar 2026 15:36:15 +0800 Subject: [PATCH] chore: update docs --- docs/.vitepress/config.mts | 29 ++++++++++++----- docs/guide/agents.md | 23 ++++++++++++++ docs/guide/dashboard.md | 16 ++++++++++ docs/guide/environments.md | 19 ++++++++++++ docs/guide/examples/browser.md | 57 ++++++++++++++++++++++------------ docs/guide/history.md | 24 ++++++++++++++ docs/guide/languages.md | 2 +- docs/guide/notify.md | 32 +++++++++++++++++++ docs/guide/scripts.md | 23 ++++++++++++++ docs/guide/sync.md | 25 +++++++++++++++ docs/guide/tasks.md | 23 ++++++++++++++ docs/guide/terminal.md | 15 +++++++++ docs/guide/usage.md | 21 ++++++++++--- 13 files changed, 276 insertions(+), 33 deletions(-) create mode 100644 docs/guide/agents.md create mode 100644 docs/guide/dashboard.md create mode 100644 docs/guide/environments.md create mode 100644 docs/guide/history.md create mode 100644 docs/guide/notify.md create mode 100644 docs/guide/scripts.md create mode 100644 docs/guide/sync.md create mode 100644 docs/guide/tasks.md create mode 100644 docs/guide/terminal.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index cfe0ed9..cad1be3 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -18,27 +18,40 @@ export default defineConfig({ { text: '基础指南', items: [ - { text: '产品介绍', link: '/guide/introduction' }, + { text: '项目介绍', link: '/guide/introduction' }, { text: '部署说明', link: '/guide/deployment' }, { text: '开始使用', link: '/guide/getting-started' }, { text: 'API 文档', link: '/guide/api' } ] }, { - text: '使用说明', + text: '功能指南', items: [ - { text: '功能特性', link: '/guide/usage' }, - { text: '编程语言与依赖管理', link: '/guide/languages' }, - { text: '脚本示例总览', link: '/guide/examples/' }, - { text: '浏览器示例', link: '/guide/examples/browser' }, - { text: '命令行工具 (CLI)', link: '/guide/cli' } + { text: '数据仪表', link: '/guide/dashboard' }, + { text: '定时任务', link: '/guide/tasks' }, + { text: '远程执行', link: '/guide/agents' }, + { text: '脚本管理', link: '/guide/scripts' }, + { text: '执行历史', link: '/guide/history' }, + { text: '变量机密', link: '/guide/environments' }, + { text: '语言依赖', link: '/guide/languages' }, + { text: '终端命令', link: '/guide/terminal' }, + { text: '消息中心', link: '/guide/notify' }, + { text: '仓库同步', link: '/guide/sync' }, + { text: '命令行(CLI)', link: '/guide/cli' }, + { + text: '脚本示例', + link: '/guide/examples/', + items: [ + { text: '浏览器示例', link: '/guide/examples/browser' } + ] + } ] }, { text: '部署配置', items: [ { text: '系统配置', link: '/guide/configuration' }, - { text: '反向代理 (Nginx)', link: '/guide/nginx' } + { text: '反向代理', link: '/guide/nginx' } ] }, { diff --git a/docs/guide/agents.md b/docs/guide/agents.md new file mode 100644 index 0000000..52b1f42 --- /dev/null +++ b/docs/guide/agents.md @@ -0,0 +1,23 @@ +# 远程执行 (Agents) + +远程执行模块（Agents）是实现分布式、多节点任务管理的关键，允许您在一台主控制面板上协同调度部署在不同区域、不同操作系统的任务。 + +## Agents 架构 + +- **Agent 节点**：独立运行的小型客户端程序，监听主面板的任务分配。 +- **通信协议**：基于高效且稳定的消息队列与 WebSocket 协议，确保持久化双向实时通信。 +- **异构环境**：Agent 完全支持 Linux、Windows 及 macOS。您可以将 Agent 安装在轻量级树莓派、本地闲置电脑甚至异地数据中心。 + +## 节点管理 + +- **节点注册**：通过唯一的指纹认证，确保存储与数据传输的安全性。 +- **多状态监控**： + - `在线`：节点准备就绪，可以接受任务。 + - `离线`：失去连接，所有指派的任务将自动进入等待或失败逻辑（取决于具体任务配置）。 + - `异常`：连接握手失败或版本由于过低暂不支持。 + + +## 指派任务 + +1. 在 `定时任务` 编辑页面，将执行器选项从 `本地执行` 切换为特定的 Agent 节点。 +2. 任务执行完成后，所有的控制台日志将通过加密隧道回传至主面板进行统一存储与检索。 diff --git a/docs/guide/dashboard.md b/docs/guide/dashboard.md new file mode 100644 index 0000000..d6cdae0 --- /dev/null +++ b/docs/guide/dashboard.md @@ -0,0 +1,16 @@ +# 数据仪表 + +数据仪表提供了白虎面板的全局运行状态、任务执行统计及关键指标的可视化展示。 + +## 主要功能 + +- **总体概览**：实时统计当前面板的总任务数、正在运行的任务数、总脚本数以及 Agent 节点的状态。 +- **执行状况统计**：通过饼图展示过去 24 小时或 7 天内任务执行的成功、失败及因超时被自动强制终止的比例。 +- **并发趋势监测**：折线图实时呈现任务并发执行的高峰与低谷，辅助管理员评估物理硬件或云服务器的负载情况。 +- **资源监控**：实时获取主机 CPU、内存在线占用状态，确保面板在资源充裕的环境下高效运转。 + +## 面板布局 + +1. **状态卡片**：位于顶部，快速掌握系统规模。 +2. **执行热力图**：展示不同时段的任务运行频次。 +3. **系统性能仪表**：直观展示核心硬件利用率。 diff --git a/docs/guide/environments.md b/docs/guide/environments.md new file mode 100644 index 0000000..b49f678 --- /dev/null +++ b/docs/guide/environments.md @@ -0,0 +1,19 @@ +# 变量机密 + +变量机密提供了统一的环境变量管理功能，旨在保护敏感数据并提高配置的灵活性，包含环境变量和机密。 + +## 环境变量 (Environment Variables) + +- **全局作用域**：一旦在变量机密页面配置成功，所有的 `定时任务` 与 `命令行交互` 在运行期间均会自动注入这些环境变量。 +- **变量命名规范**：建议使用大写字母加下划线的形式，例如 `DB_PASSWORD` 或 `AUTH_TOKEN`。 + + +## 机密 (Secrets) + +- **字段脱敏**：对于标记为 `Secret` 的变量，面板在浏览列表中将以星号 `*******` 显示，避免在协作或投屏场景下泄露机密信息。 +- **加密存储**：数据库中的敏感字段均由系统后端进行深度加密，确保存储层的物理安全。 +- **编辑权限**：某些机密字段可能在编辑后不可见其原始值，仅支持通过覆盖更新的方式进行修改。 + +## 注入机制 + +- **任务运行时动态挂载**：在启动任务对应的进程前，主进程或 Agent 会将配置好的键值对同步至子进程的 `Environment` 参数中，确保脚本可以直接通过 `os.environ` 或 `process.env` 获取到该配置。 diff --git a/docs/guide/examples/browser.md b/docs/guide/examples/browser.md index eb1fec8..532ef2f 100644 --- a/docs/guide/examples/browser.md +++ b/docs/guide/examples/browser.md @@ -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 连接远程浏览器： diff --git a/docs/guide/history.md b/docs/guide/history.md new file mode 100644 index 0000000..15c55e9 --- /dev/null +++ b/docs/guide/history.md @@ -0,0 +1,24 @@ +# 执行历史 + +执行历史详细记录了面板中所有任务的运行状态、实时日志及耗时统计。 + +## 日志详情 + +- **实时日志推流**：即使任务仍在运行，也可以在历史日志详情页实时看到程序的控制台输出（stdout/stderr）。 +- **历史归档**：系统默认保留最近一段时间的任务运行快照。 +- **状态统计**： + - `SUCCESS`：任务按计划成功运行并返回正常退出代码。 + - `FAILURE`：脚本运行时报错或程序异常终止。 + - `TIMEOUT`：任务执行超出了设定的最大运行时间，由系统强制中止并标记为超时。 + +## 日志管理 + +- **搜索与过滤**：支持通过 `任务名称`、`脚本文件名` 或 `状态` 快速检索历史。 +- **自动清理策略**： + - **最大保留份数**：支持在系统设置中配置每个任务保留的历史日志最大数量。 + - **日志滚动更新**：当产生新日志且超过最大份数时，最旧的记录将被自动清除，确保存储空间的动态平衡。 + +## 执行耗时 + +- **精准计时**：精确统计每次任务执行从启动到退出的全周期耗时。 +- **性能分析**：通过历史耗时数据对比，可辅助用户排查脚本是否出现了性能退化。 diff --git a/docs/guide/languages.md b/docs/guide/languages.md index 71bafd4..9de205f 100644 --- a/docs/guide/languages.md +++ b/docs/guide/languages.md @@ -1,4 +1,4 @@ -# 编程语言与依赖管理 +# 语言依赖 白虎面板深度集成了 **Mise** 运行时管理器，这使得它具备多版本语言环境的高灵活性和隔离性。 diff --git a/docs/guide/notify.md b/docs/guide/notify.md new file mode 100644 index 0000000..f5948dc --- /dev/null +++ b/docs/guide/notify.md @@ -0,0 +1,32 @@ +# 消息中心 + +消息中心集成了一整套灵活且现代的消息分发引擎，支持多场景自动推送到外部 IM 工具。 + +## 消息通道 + +- **企业 IM**：支持集成 **企业微信** (WeCom)、**钉钉** (DingTalk)、**飞书** (Lark)。 +- **个人推送到位**：支持 **Telegram** Bot、**Bark**、以及基于 **Wpush** 的推送服务。 +- **公共渠道**：标准的 **SMTP 邮件** 及 **Webhook** 回调。 + +## 事件通知规则 + +- **多事件配置**：您可以灵活定义在哪些场景下触发通知，包括但不限于： + - **任务失败**：定时任务在 Cron 触发后运行报错。 + - **任务超时**：任务由于运行过长被系统中止。 + - **登录安全**：检测到异地登录或多次密码错误。 + - **服务下线**：Agent 节点掉线提醒。 + +## 任务快速配置 + +白虎面板支持在 **「定时任务」** 页面直接为单个任务配置通知规则，无需跳转： + +1. **新建或编辑任务**：在任务弹窗底部可以看到「通知配置」栏目。 +2. **选择渠道**：从已安装的通知渠道中选择一个作为该任务的提醒路径。 +3. **设置时机**：勾选 `成功时`、`失败时` 或 `超时时` 触发通知。 +4. **日志附带**：开启后，通知消息将自动截取任务执行的最后一部分日志并发送，支持自定义日志字数限制。 + +## 审计日志 (Logout) + +- **发送记录**：实时记录每一条通过白虎面板发送至外部的消息。 +- **回执查询**：在 `消息日志` 页面可以查看到推送是否成功，若失败则提供详细的错误代码。 + diff --git a/docs/guide/scripts.md b/docs/guide/scripts.md new file mode 100644 index 0000000..4965987 --- /dev/null +++ b/docs/guide/scripts.md @@ -0,0 +1,23 @@ +# 脚本管理 + +脚本管理提供了白虎面板的在线文件资源浏览器和编辑器。 + +## 资源管理器 + +- **目录树视图**：清晰层级化展示位于 `scripts` 目录下的所有子文件夹及文件。 +- **动态预览**：支持常见的文本文件预览。 +- **文件操作**： + - **创建/重命名**：在浏览器中直接对脚本文件进行管理和修订。 + - **极速上传**：支持直接在 Web 端上传单文件或进行多选拖拽上传。 + - **在线解包**：支持一键解压缩 `.zip` 包，大大优化了脚本部署流程。 + +## 在线编辑器 + +- **语法高亮**：集成了现代代码编辑器，完美支持 JavaScript、Python、Shell、Go、TypeScript 等主流开发语言。 +- **编辑器增强**：支持常见的代码查找与替换、自动缩进和括号匹配。 +- **一键保存**：编辑后的内容将实时写入服务器端物理存储，配合 `定时任务` 可快速生效。 + +## 权限控制 + +- **安全防御**：默认只能在指定的 `scripts` 根路径内进行相关文件操作，防止跨目录读取系统敏感文件。 +- **文件保护**：系统核心配置文件不可在脚本管理器中直接修改。 diff --git a/docs/guide/sync.md b/docs/guide/sync.md new file mode 100644 index 0000000..21be330 --- /dev/null +++ b/docs/guide/sync.md @@ -0,0 +1,25 @@ +# 仓库同步 (Repo) + +仓库同步允许白虎面板直接以 Git 仓库的形式管理和更新脚本库，极大地方便了脚本的大规模分发与自动化部署。 + +## 同步源管理 + +- **青龙 (QL) 指令解析**：如果您曾经是青龙面板的用户，您可以直接粘贴类似的 `ql repo ` 指令，系统将自动提取各项参数。 + > [!IMPORTANT] + > **依赖管理说明**：由于该面板采用基于 Mise 的多版本语言管理系统，与青龙的全局环境不同，系统 **无法通过 `dependence` 字段自动安装依赖**。用户需要手动前往「语言依赖」页面，或者在终端中自己执行依赖，在对应的运行中安装脚本所需的依赖包。 +- **Git 源管理**：支持从 **GitHub**, **GitLab**, **Gitee** 等主流代码托管平台同步脚本。 +- **SSH/Token 访问**：支持私有仓库的访问，可以在环境变量中配置对应的 Git 鉴权秘钥。 + +## 扫描与注册规则 + +- **自动解析配置**：在同步代码至本地物理磁盘后，面板将深度扫描每个 `.js` 或 `.py` 文件。 +- **配置探测**： + - `new Env('任务名称')`：解析 JavaScript 脚本定义的展示名。 + - `cron "0 0 * * *"`：自动提取文件头部的 Cron 注释规则。 +- **白名单/黑名单**：通过正则表达式（Regex）过滤哪些子目录或特定命名的文件需要被注册为定时任务。 + +## 增量同步 + +- **Git 离线拉取**：支持增量更新，仅下载变更部分，降低带宽压力。 +- **分支切换**：支持指定任意分支进行同步，方便用户在生产与测试环境间切换脚本源。 +- **稀疏检出 (Sparse Checkout)**：如果仓库过于庞大，您可以配置仅同步特定的子文件夹以节省存储空间。 diff --git a/docs/guide/tasks.md b/docs/guide/tasks.md new file mode 100644 index 0000000..ea04fed --- /dev/null +++ b/docs/guide/tasks.md @@ -0,0 +1,23 @@ +# 定时任务 + +定时任务是白虎面板的核心模块，支持对各类多语言脚本、命令进行精细化执行管理。 + +## 任务属性 + +- **任务名称**：给任务起一个直观的名称，例如 `每日签到任务`。 +- **Cron 表达式**：支持标准 cron 规则（分、时、日、月、周）。 +- **脚本路径**：关联到 `scripts` 目录下的具体脚本文件或直接输入 Shell 命令。 +- **执行终端**：允许选择运行在 `本机` 或是指定的 `远程 Agent` 节点。 +- **任务超时**：设定单次运行的最大时长，防止僵尸进程占用资源。 + +## 管理操作 + +- **启动/停止**：手动控制任务的状态，支持一键切换自动调度与临时暂停。 +- **立即执行**：不等待 Cron 触发，即刻拉起脚本运行。 +- **查看日志**：直接跳转到与该任务关联的最新执行历史详情。 +- **批量管理**：支持对选中的多个任务执行批量禁用、启用或删除动作。 + +## 交互设计 + +- **预设 Cron 规则**：在编辑任务时，提供常用的 `每分钟执行`、`每小时整点` 等预设样式。 +- **下次触发预测**：实时计算并展示任务下一次执行的北京时间，帮助验证调度逻辑是否符合预期。 diff --git a/docs/guide/terminal.md b/docs/guide/terminal.md new file mode 100644 index 0000000..ac6f8fe --- /dev/null +++ b/docs/guide/terminal.md @@ -0,0 +1,15 @@ +# 终端命令 + +终端命令模块（Terminal）允许用户在 Web 端直接与服务器的 Shell 环境进行交互。 + +## 实时交互 + +- **WebSocket 双工连接**：不仅是单向的命令发送，您可以获得一个可以输入交互（如 `yes/no` 確認、`npm init` 交互等）的伪终端（PTY）。 +- **实时输出回传**：秒级显示命令的执行结果，支持 ANSI 转义序列以正确渲染终端样式与彩色文本。 +- **自定义工作目录**：可以选择在哪一个文件夹（如 `scripts` 或系统根目录）下启动终端。 + + +## 常用指令 + +- `ls -la`：查看当前目录详细文件列表。 +- `git status`：在 `scripts` 目录下查看仓库 Git 定位状态。 diff --git a/docs/guide/usage.md b/docs/guide/usage.md index 785399d..3e45c8e 100644 --- a/docs/guide/usage.md +++ b/docs/guide/usage.md @@ -2,6 +2,11 @@ 白虎面板不仅提供基础的脚本执行功能，还集成了众多的实用工具和管理模块。 +## 数据仪表 + +- **运行状态概览**：实时展示系统运行状态、任务执行统计及资源消耗。 +- **动态图表**：通过直观的图表展示任务成功率、并发趋势及系统负载。 + ## 定时任务管理 - **标准 Cron 表达式**：支持高度灵活的调度配置。 @@ -9,6 +14,11 @@ - **手动触发执行**：支持临时执行任务。 - **任务超时控制**：通过配置 `timeout` 参数，系统会自动隔离并中止长时间运行的任务。 +## 远程分布式执行 (Agents) + +- **子节点管理**：支持注册多个远程 Agent 节点，实现分布式任务分发。 +- **跨平台支持**：Agent 可部署在 Linux、Windows、macOS 等不同系统，覆盖异构执行环境。 + ## 脚本文件管理 - **在线代码编辑器**：集成了现代代码编辑器，支持语法高亮和编辑。 @@ -27,16 +37,17 @@ - **执行耗时统计**：自动统计任务耗时，辅助性能优化。 - **日志压缩存储**：通过对旧日志进行自动清理和压缩，规避存储空间占用问题。 +## 环境变量管理 (Secret) + +- **机密性管理**：对敏感字段（如脚本 Key、DB 密码）进行脱敏显示和加密存储。 +- **全局环境隔离**：在不同脚本运行期间动态注入，确保持久化和隔离。 + ## 消息推送与系统通知 - **原生内置分发**：集成了企业微信、钉钉、飞书、Telegram、Bark、邮件等十余种主流渠道。 - **多事件灵活通知**：您可以配置「任务失败」、「服务下线」、「登录安全报警」等事件通知条件。 - **API 示例**：系统自动生成各种编程语言的一键集成代码片段，方便用户脚本集成。 - -## 环境变量管理 - -- **机密性管理**：对敏感字段（如脚本 Key、DB 密码）进行脱敏显示和加密存储。 -- **全局环境隔离**：在不同脚本运行期间动态注入，确保持久化和隔离。 +- **消息日志**：详细记录每条推送消息的状态、接收人和尝试发送的日志，方便故障排查。 ## 仓库任务同步