feat: add docs

2026-03-10 17:56:25 +08:00
parent c5a9e287f4
commit 6d61c18539
37 changed files with 36567 additions and 0 deletions
@@ -0,0 +1,38 @@
+# 更新日志 ☕
+
+本页面记录了白虎面板的主要版本更新历史。
+
+## ⚠️ 重大升级与迁移说明 (v3 数据结构)
+
+本次更新包含底层数据结构的重大突破，将所有数据的 ID 类型从数字编号平滑迁移为 20 位的字符式全局唯一标识符（`xid`）。系统在启动时会**自动进行数据的清洗、映射、拷贝与外键修补**，以确保旧数据被妥善对接。
+
+- **备份位置**：执行迁移前，即使有程序自动转换逻辑（data\migration_v3_backup_backup_xxx.zip），为了数据安全，仍然建议您**提前手动进行备份**。
+- **降级机制**：如果遇到未预期的迁移失败或数据显示丢失，**请使用原本备份的数据库** 并 **降级至 `v1.0.10` 及以下旧版本** 进行恢复与使用。
+
+---
+
+## 最近更新概览
+
+### 2026.03.05 - API 文档重构
+- **OpenAPI 认证体系**：支持站点级 Token 配置与 Basic Auth 保护。
+- **自定义 UI**：新增设计感十足的全局 **404 页面**。
+
+### 2026.03.04 - 消息推送系统重构
+- **原生内置**：全新原生支持企业微信、钉钉、飞书、Telegram、Bark、邮件等十余种主流渠道。
+- **事件捕获**：接入系统级事件通知自动捕获，告别原有必配外部推送服务的繁琐历史。
+
+### 2026.02.13 - 任务执行引擎重构
+- **深度集成 Mise**：支持 Python, Node.js, Go, Rust, PHP 等几乎所有主流语言的动态安装与多版本切换。
+- **依赖管理**：同步上线跨语言统一依赖管理系统。
+
+### 2026.02.11 - 安全性增强
+- **随机密码策略**：首次启动使用随机密码并打印在日志中。
+- **暴力破解防护**：登录接口增加防暴力破解。
+- **路径遍历防护**：文件系统操作增加路径穿越锁定。
+
+### 2026.02.10 - 任务调度重构
+- **调度性能**：重写了并发控制逻辑，完善了任务队列。
+- **体验优化**：优化文件树交互体验，支持任务执行实时日志流。
+
+### 2026.02.06 - 镜像扩展
+- **Debian 13 支持**：增加对 Debian 13 (Trixie) 镜像支持，整理 Docker 目录结构。
@@ -0,0 +1,41 @@
+# 命令行工具 (CLI)
+
+白虎面板在环境内内置了同名的 `baihu` 命令行工具。如果您在终端内需要执行系统级别的操作，可以使用这些内置命令。
+
+## 常用核心指令
+
+| 命令 | 描述 |
+| :--- | :--- |
+| `baihu server` | 面板启动指令，运行服务端后台进程。 |
+| `baihu reposync` | 供定时任务调用，将远程 Git 仓库的高级特性同步到本地目录中。 |
+| `baihu resetpwd` | 交互式重置系统 admin 账号密码（密码丢失时可通过进入终端重置）。 |
+| `baihu restore <file>` | 使用本地的 .zip 备份压缩包文件，一条命令直接全量恢复系统数据。 |
+
+---
+
+## 使用场景示例
+
+### 1. 密码重置
+您可以进入 Docker 容器或通过 ssh 连入宿主机控制台：
+```bash
+docker exec -it baihu baihu resetpwd
+```
+然后根据提示，输入新的管理员密码即可重置成功。
+
+### 2. 手动启动
+如果是通过手动部署二进制文件，可以使用 `baihu server` 启动：
+```bash
+nohup ./baihu server > /dev/null 2>&1 &
+```
+
+### 3. 数据恢复
+上传备份后的 ZIP 文件至容器目录：
+```bash
+docker exec -it baihu baihu restore /app/data/backup-2026xxxx.zip
+```
+该操作会全量覆盖现有数据库和脚本文件，请谨慎操作。
+
+---
+
+## 其他帮助
+终端内直接执行 `baihu` 即可在控制台直接打印内置支持详细说明和命令列表参数。
@@ -0,0 +1,61 @@
+# 系统配置手册
+
+白虎面板支持通过环境变量和配置文件两种核心方式进行系统参数微调。
+
+## 环境变量配置 (优先级最高)
+
+环境变量在容器内自动注入，非常适合 CI/CD 和 Docker 混合编排场景。
+
+### 核心配置项列表
+
+| 环境变量 | 对应配置 | 说明 | 默认值 |
+| :--- | :--- | :--- | :--- |
+| `BH_SERVER_PORT` | server.port | 服务监听端口 | 8052 |
+| `BH_SERVER_HOST` | server.host | 监听地址 | 0.0.0.0 |
+| `BH_SERVER_URL_PREFIX` | server.url_prefix | URL 前缀，用于反向代理子路径部署 | - |
+| `BH_DB_TYPE` | database.type | 数据库类型 (sqlite/mysql) | sqlite |
+| `BH_DB_HOST` | database.host | 数据库实例地址 | localhost |
+| `BH_DB_PORT` | database.port | 数据库端口 | 3306 |
+| `BH_DB_USER` | database.user | 数据库用户名 | root |
+| `BH_DB_PASSWORD` | database.password | 数据库密码 | - |
+| `BH_DB_NAME` | database.dbname | 数据库库名 | baihu |
+| `BH_DB_PATH` | database.path | SQLite 物理文件存储路径 | ./data/baihu.db |
+| `BH_DB_TABLE_PREFIX` | database.table_prefix | 数据库表前缀 | baihu_ |
+
+---
+
+## 配置文件挂载 (config.ini)
+
+如果您希望对系统参数有更细致的控制（而非通过外部注入），可以使用配置文件。
+
+### 挂载点
+```yaml
+volumes:
+  - ./configs:/app/configs
+```
+
+### 配置文件示例 (`configs/config.ini`)
+```ini
+[server]
+port = 8052
+host = 0.0.0.0
+# 配置 URL 前缀用于反向代理，例如 /baihu/
+url_prefix = /baihu
+
+[database]
+type = sqlite
+path = /app/data/baihu.db
+table_prefix = baihu_
+```
+
+---
+
+## 调度设置说明
+
+系统采用异步任务队列 + Worker Pool 架构，可在「系统设置 > 调度设置」页面进行配置：
+
+- **Worker 数量** (默认 4)：同时在后端并发运行的任务进程数。
+- **队列大小** (默认 100)：待处理任务队列的最大容量。
+- **速率间隔** (默认 200 ms)：控制两个任务启动之间的最小等待时长。
+
+> **提示**：修改以上调度参数后，系统会立即响应并动态调整，无需重启容器。
@@ -0,0 +1,125 @@
+# 快速部署
+
+项目提供多种基础镜像，默认版本基于 Debian 12，集成了 Python 3.13 与 Node.js 23。
+
+## 基础镜像选择
+
+| 标签 (Tag) | 基础镜像 | 说明 |
+| :--- | :--- | :--- |
+| `latest` | Debian 12 | 默认版本，集成 Python 3.13 与 Node.js 23 |
+| `latest-debian13` | Debian 13 | 尝鲜版本|
+
+> **提示**：下方部署示例默认使用 `latest` 标签，如需换用 Debian 13 版，只需将 `latest` 替换为 `latest-debian13` 即可。
+
+## 环境版本重构说明 (2026.02.13+)
+
+> **警告**：架构升级破坏性变更
+> 
+> 本版本（2026.02.13+）对底层运行时环境进行了彻底重构，弃用了原有的静态 Python/Node 环境，转为使用 **Mise** 进行动态版本管理。
+> 
+> 1. **不再提供 Alpine 镜像**：由于 glibc 兼容性问题，Mise 无法在 Alpine 上完美运行，因此暂时取消 Alpine 镜像支持。
+> 2. **环境数据不兼容**：如果您是从旧版本升级上来，原有的 Python/Node 环境数据将无法迁移。您需要清空挂载的 `envs/` 目录并让其由新容器自动初始化。
+
+---
+
+## 方式一：Docker 运行 (环境变量配置)
+
+通过环境变量指定配置，简单灵活，适合一般部署。
+
+### SQLite (默认)
+```bash
+docker run -d \
+  --name baihu \
+  -p 8052:8052 \
+  -v $(pwd)/data:/app/data \
+  -v $(pwd)/envs:/app/envs \
+  -e TZ=Asia/Shanghai \
+  -e BH_SERVER_PORT=8052 \
+  -e BH_SERVER_HOST=0.0.0.0 \
+  -e BH_DB_TYPE=sqlite \
+  -e BH_DB_PATH=/app/data/baihu.db \
+  -e BH_DB_TABLE_PREFIX=baihu_ \
+  --restart unless-stopped \
+  ghcr.io/engigu/baihu:latest
+```
+
+### MySQL
+```bash
+docker run -d \
+  --name baihu \
+  -p 8052:8052 \
+  -v $(pwd)/data:/app/data \
+  -v $(pwd)/envs:/app/envs \
+  -e TZ=Asia/Shanghai \
+  -e BH_SERVER_PORT=8052 \
+  -e BH_SERVER_HOST=0.0.0.0 \
+  -e BH_DB_TYPE=mysql \
+  -e BH_DB_HOST=mysql-server \
+  -e BH_DB_PORT=3306 \
+  -e BH_DB_USER=root \
+  -e BH_DB_PASSWORD=your_password \
+  -e BH_DB_NAME=baihu \
+  -e BH_DB_TABLE_PREFIX=baihu_ \
+  --restart unless-stopped \
+  ghcr.io/engigu/baihu:latest
+```
+
+---
+
+## 方式二：Docker Compose 部署
+
+推荐的生产环境部署方式。
+
+### 核心部署模板
+```yaml
+services:
+  baihu:
+    image: ghcr.io/engigu/baihu:latest
+    container_name: baihu
+    ports:
+      - "8052:8052"
+    volumes:
+      - ./data:/app/data
+      - ./envs:/app/envs
+    environment:
+      - TZ=Asia/Shanghai
+      - BH_SERVER_PORT=8052
+      - BH_SERVER_HOST=0.0.0.0
+      - BH_DB_TYPE=sqlite
+      - BH_DB_PATH=/app/data/baihu.db
+      - BH_DB_TABLE_PREFIX=baihu_
+      # - BH_SERVER_URL_PREFIX=/baihu  # 可选：配置 URL 前缀用于反向代理
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    restart: unless-stopped
+```
+
+---
+
+## 方式三：配置文件挂载模式
+
+通过挂载 `/app/configs/config.ini` 来管理详细配置。
+
+### 配置文件挂载示例
+```yaml
+volumes:
+  - ./data:/app/data
+  - ./configs:/app/configs
+  - ./envs:/app/envs
+```
+---
+
+## Docker 启动流程
+
+容器启动时 `docker-entrypoint.sh` 会自动执行以下关键步骤：
+
+1. **环境自检**：检查 `/app/data`、`/app/configs`、`/app/envs` 挂载点并创建必要子目录。
+2. **Mise 同步**：自动将镜像内置的 Mise 核心运行时激活文件同步到持久化挂载目录中，确保容器重启后环境依然可用。
+3. **运行时激活**：动态注入环境变量，将 `mise shims` 路径加入系统 `PATH`。
+4. **包管理预设**：自动为 Python 配置清华源 (PIP) 镜像，配置 Node.js 内存限制。
+5. **主进程启动**：运行 `baihu server` 开启面板。
+
+> **提示**：通过持久化挂载 `./envs` 目录，您安装的所有运行时版本和第三方依赖库均会永久保留。
@@ -0,0 +1,24 @@
+# 免责声明
+
+白虎面板（Baihu Panel）及其开发者在提供本项目的同时，默认用户已完全知悉并同意以下条款：
+
+## 1. 免责保证
+
+-   **无业务逻辑**：本项目仅作为一个轻量级的任务托管与调度平台，不提供、不内置任何具有实际业务逻辑的第三方脚本。
+-   **脚本审核**：用户自行添加或配置的脚本来源、逻辑及潜在的系统影响均由用户自行负责。请勿执行来源不明的恶意脚本，并在执行前仔细阅读并审核其源代码，确保安全性。
+
+## 2. 软件责任
+
+-   **按“原样”提供**：本项目属于业余开源开发作品，采用 MIT License 发布。开发者不保证软件不存在任何 Bug、系统漏洞或逻辑缺陷。
+-   **损失赔偿**：因运行用户自行脚本或使用本系统带来的一切数据泄露、系统损坏、财产损失（如服务器被封、云服务欠费）及相关法律责任，均由使用者本人承担。
+
+## 3. 授权与使用
+
+-   **合理镜像申请**：由于项目涉及到网络请求和资产调度，请遵循相关的开源协议进行公平、合理的使用。
+-   **禁止非法用途**：严禁将白虎面板用于任何违反中华人民共和国法律法规及相关组织政策的行为。
+
+---
+
+## 4. 联系我们
+
+如果您在使用过程中发现任何技术问题，欢迎通过 GitHub [Issues](https://github.com/engigu/baihu-panel/issues) 反馈。
@@ -0,0 +1,43 @@
+# 访问面板
+
+部署成功并启动容器后，您只需通过浏览器即可访问白虎面板。
+
+## 默认账号
+
+-   **访问地址**：`http://localhost:8052` (或您配置的宿主机端口)
+-   **用户名**：`admin`
+-   **密码**：首次启动成功后，系统会为管理员账号生成 **12 位随机初始密码** 并打印在容器启动日志中。
+
+> **如何查找初始密码**：
+> 运行容器后，在命令行执行：
+> ```bash
+> docker logs baihu | grep "管理员账号创建成功"
+> ```
+> 找到包含密码的内容后登录，登录后建议首选操作：**修改管理员密码**。
+
+---
+
+## 登录后的首要配置
+
+### 1. 修改密码
+在右上角用户头像下拉菜单选择「个人设置」进行账号安全修改。
+
+### 2. 系统调度设置
+在「系统设置」>「调度设置」中，可以根据服务器资源微调任务队列的并发数（默认 4）和最大队列大小（默认 100）。
+
+### 3. 环境与依赖
+如果您需要执行特定语言或脚本包，请先进入「编程语言」页面确认所需的环境已安装（如已安装 Python3.x 或 Node.js.x）。
+
+---
+
+## 面板功能一览
+
+| 模块 | 说明 |
+| :--- | :--- |
+| **仪表盘 (Dashboard)** | 实时监控任务执行动态、容器状态和资源占用频率情况。 |
+| **定时任务 (Tasks)** | 管理和调度各种 Cron 脚本。 |
+| **脚本管理 (Scripts)** | 在线编辑、上传项目源代码。 |
+| **在线终端 (Terminal)** | 直接操作容器环境进行运维和调试。 |
+| **消息推送 (Notify)** | 配置各类通知渠道。 |
+| **环境变量 (Environments)** | 管理脚本所需的各种隐私信息、持久配置。 |
+| **个人设置 (Settings)** | 调整站点 UI 和账号安全信息。 |
@@ -0,0 +1,23 @@
+# 项目介绍
+
+白虎面板 (Baihu Panel) 是一款极致轻量、高性能的自动化任务调度平台。采用 Go + Vue3 架构，专注于高性能与低系统开销。
+
+## 核心亮点
+
+-   **极致性能**：采用 Go 语言开发，对比同类产品（如青龙面板），在同样的任务执行下，CPU 占用跳变降低 60% 以上。
+-   **运行时解耦**：深度集成 **Mise** 运行时管理，原生支持 Python、Node.js、Go、Rust、PHP 等所有主流语言环境的动态安装（几乎所有的版本）与统一依赖管理。
+-   **一键部署**：支持 Docker/Docker-Compose 一键部署，开箱即用。
+-   **现代 UI**：基于 Vue3 + TailwindCSS + Shadcn/ui，提供响应式设计与深色/浅色主题。
+
+
+## 主要特色
+
+-   **轻量级：** docker/compose部署，无需复杂配置，开箱即用
+-   **任务调度：** 支持标准 Cron 表达式，常用时间规则快捷选择。日志不落文件，没有磁盘频繁io的问题
+-   **脚本管理：** 在线代码编辑器，支持文件上传、压缩包解压
+-   **在线终端：** WebSocket 实时终端，命令执行结果实时输出
+-   **消息推送：** 内置强大消息推送与通知引擎，无缝兼容主流渠道，支持系统级事件告警
+-   **环境变量：** 安全存储敏感配置，任务执行时自动注入
+-   **移动端：** 适配移动小屏样式
+-   **远程执行：** 支持远程agent执行任务，展示执行结果
+-   **多语言支持：** 深度集成 Mise，支持几乎所有主流编程语言的动态安装、多版本切换及依赖管理
@@ -0,0 +1,50 @@
+# 编程语言与依赖管理
+
+白虎面板深度集成了 **Mise** 运行时管理器，这使得它具备多版本语言环境的高灵活性和隔离性。
+
+## 脚本运行环境
+
+白虎面板原生支持以下脚本的定时执行：
+- **Python3**, **Node.js**, **Bash** (内置环境)
+- 通过 **Mise** 扩展：支持几乎所有主流编程语言的动态安装与切换。
+
+## 依赖管理支持
+
+系统内置了高度集成的跨语言依赖管理器，支持自动化安装和管理以下语言的依赖项，并确保在容器内全局可用：
+
+| 语言 | 包管理器 | 功能说明 |
+| :--- | :--- | :--- |
+| **Python** | pip | 自动使用内置虚拟环境，支持清华源 |
+| **Node.js** | npm | 全局安装模式，自动配置 npmmirror 镜像 |
+| **Go** | go install | 通过 `go install` 安装二进制工具 |
+| **Rust** | cargo | 通过 `cargo install` 安装 Rust 依赖 |
+| **Ruby** | gem | 支持 `gem install` 本地安装 |
+| **Bun** | bun | 支持 `bun add -g` 全局模式 |
+| **PHP** | composer | 支持 `composer global require` |
+| **Deno** | deno | 支持 `deno install -g` |
+| **.NET** | dotnet | 支持 `dotnet tool install -g` |
+| **Elixir/Erlang** | mix | 支持 `mix archive.install` |
+| **Lua** | luarocks | 通过 `luarocks` 管理 Lua 包 |
+| **Nim** | nimble | 支持 `nimble install` |
+| **Dart/Flutter** | pub | 支持 `pub global activate` |
+| **Perl** | cpanm | 简单的 `cpanm` 安装支持 |
+| **Crystal** | shards | `shards` 项目级别或工具安装 |
+
+## 使用方法
+
+### 1. 安装环境
+进入「编程语言」页面，使用 `mise` 一键安装所需的语言及版本。
+
+### 2. 依赖管理
+在已安装列表点击「依赖管理」，输入名称（可选版本）即可自动在对应环境内完成安装。
+
+### 3. 多版本切换
+对于复杂的项目，您可以通过面板配置不同的任务版本镜像，系统基于 `mise exec` 实现了完善的环境隔离，不同版本的依赖包互不冲突。
+
+---
+
+## 隔离机制说明
+
+-   白虎面板通过动态注入 `PATH` 环境和 `mise shims` 将语言环境暴露给系统。
+-   每个任务在执行前都会根据任务配置自动加载对应的运行时环境变量。
+-   **运行时激活**：自动将 `MISE_DATA_DIR` 等环境变量指向宿主机的持久化挂载目录，确保护持久化可用。
@@ -0,0 +1,86 @@
+# Nginx 反向代理配置
+
+如果您需要通过域名和 HTTPS 访问白虎面板，推荐使用 Nginx 作为反向代理并配置 WebSocket 负载均衡。
+
+## Nginx 反向代理配置示例
+
+### 1. 配置映射
+首先，在 `nginx.conf` 的 `http` 块中添加 WebSocket 升级映射：
+```nginx
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    '' close;
+}
+```
+
+---
+
+### 2. 服务器配置
+将 `example.com` 替换为您的域名，并指定宿主机监听端口：
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name example.com;
+    
+    ssl_certificate     /etc/letsencrypt/live/example.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers off;
+    
+    access_log /var/log/nginx/example.access.log;
+    error_log  /var/log/nginx/example.error.log warn;
+    
+    location / {
+        proxy_pass http://127.0.0.1:8052; # 指定白虎面板宿主机 IP 和端口
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        
+        # WebSocket 支持（在线控制台必需）
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        
+        proxy_buffering off;
+        proxy_read_timeout 60s;
+    }
+}
+
+# 自动 HTTP 跳转 HTTPS (可选)
+server {
+    listen 80;
+    server_name example.com;
+    return 301 https://$server_name$request_uri;
+}
+```
+
+---
+
+### 3. 子路径部署场景
+
+如果您是通过 `BH_SERVER_URL_PREFIX=/baihu` 进行子路径托管，请修改 `location` 参数：
+```nginx
+location /baihu/ {
+    proxy_pass http://127.0.0.1:8052/baihu/;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+---
+
+## 验证与发布
+
+在保存配置文件后，请执行以下命令确保 Nginx 配置正确并重启：
+```bash
+# 检查语法
+nginx -t
+# 重启服务
+nginx -s reload
+```
@@ -0,0 +1,44 @@
+# 功能特性
+
+白虎面板不仅提供基础的脚本执行功能，还集成了众多的实用工具和管理模块。
+
+## 定时任务管理
+
+- **标准 Cron 表达式**：支持高度灵活的调度配置。
+- **控制台快捷键**：常用规则一键选择。
+- **手动触发执行**：支持临时执行任务。
+- **任务超时控制**：通过配置 `timeout` 参数，系统会自动隔离并中止长时间运行的任务。
+
+## 脚本文件管理
+
+- **在线代码编辑器**：集成了现代代码编辑器，支持语法高亮和编辑。
+- **文件树形结构**：直观展示项目内所有文件。
+- **文件上传与解压**：支持单文件、多文件上传和对 ZIP 压缩包的在线解压。
+- **文件管理**：支持在线进行创建、重命名、移动和删除操作。
+
+## 在线终端
+
+- **WebSocket 实时终端**：支持常用的 Shell 命令。
+- **命令输出实时推流**：实时查看脚本运行的物理设备输出。
+
+## 执行日志
+
+- **任务执行历史**：记录每次运行的状态（成功/失败/超时）。
+- **执行耗时统计**：自动统计任务耗时，辅助性能优化。
+- **日志压缩存储**：通过对旧日志进行自动清理和压缩，规避存储空间占用问题。
+
+## 消息推送与系统通知
+
+- **原生内置分发**：集成了企业微信、钉钉、飞书、Telegram、Bark、邮件等十余种主流渠道。
+- **多事件灵活通知**：您可以配置「任务失败」、「服务下线」、「登录安全报警」等事件通知条件。
+- **API 示例**：系统自动生成各种编程语言的一键集成代码片段，方便用户脚本集成。
+
+## 环境变量管理
+
+- **机密性管理**：对敏感字段（如脚本 Key、DB 密码）进行脱敏显示和加密存储。
+- **全局环境隔离**：在不同脚本运行期间动态注入，确保持久化和隔离。
+
+## 系统设置
+
+- **数据备份与恢复**：支持全量数据的本地导出和一键导入恢复。
+- **页面设置**：自定义站点标题、标语和分页显示逻辑。