From fb617ae24cc1488c0a1bd6eee532586b77fc7e7c Mon Sep 17 00:00:00 2001
From: duorameng <2997944583@qq.com>
Date: Mon, 11 May 2026 20:19:11 +0800
Subject: [PATCH] chore: add env deps isntall docs  #91

---
 docs/guide/languages.md              | 10 ++++++
 docs/guide/tasks.md                  | 13 +++++++
 example/deps/install_php_env_deps.sh | 53 ++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 example/deps/install_php_env_deps.sh

diff --git a/docs/guide/languages.md b/docs/guide/languages.md
index 9de205f..7ce641c 100644
--- a/docs/guide/languages.md
+++ b/docs/guide/languages.md
@@ -8,6 +8,7 @@
 - **Python3**, **Node.js**, **Bash** (标准版镜像内置环境)
 - 通过 **Mise** 扩展：支持几乎所有主流编程语言的动态安装与切换。
 
+
 > [!TIP]
 > **Minimal 镜像注意**：如果您使用的是 `minimal` 标签的镜像，系统初始不包含 Python 和 Node.js。您需要进入「编程语言」页面手动点击安装您所需的运行时。
 
@@ -62,6 +63,15 @@ mise use -g ansible@latest
 
 安装完成后，您可以在「脚本管理」或「定时任务」中直接调用 `ansible` 或 `ansible-playbook` 命令。
 
+## PHP 环境特别说明
+
+在 Docker 容器或精简版 Linux 环境中，通过 `mise` 安装某些 PHP 版本时，如果官方没有提供预编译的二进制包，系统会尝试从源码编译。这需要额外的系统级构建依赖（如 `autoconf`, `bison`, `pkg-config` 等）。
+
+如果您在安装 PHP 时遇到 `autoconf not found` 或 `buildconf failed` 等错误，请参考以下方案：
+
+1. **运行预设脚本**: 我们在项目根目录提供了示例脚本 [install_php_env_deps.sh](file:///example/deps/install_php_env_deps.sh)，它会自动安装所需的系统库。
+2. **配置为开机任务**: 由于 Docker 容器层通常是只读的或在重启后重置（非挂载目录），建议在面板中创建一个 **触发类型为 `baihu_startup`** 的定时任务，命令填写 `bash example/deps/install_php_env_deps.sh`。这样可以确保每次容器启动时都会自动准备好 PHP 编译环境。
+
 ---
 
 ## 隔离机制说明
diff --git a/docs/guide/tasks.md b/docs/guide/tasks.md
index ea04fed..27c3360 100644
--- a/docs/guide/tasks.md
+++ b/docs/guide/tasks.md
@@ -21,3 +21,16 @@
 
 - **预设 Cron 规则**：在编辑任务时，提供常用的 `每分钟执行`、`每小时整点` 等预设样式。
 - **下次触发预测**：实时计算并展示任务下一次执行的北京时间，帮助验证调度逻辑是否符合预期。
+
+## 特殊任务类型
+
+除了标准的 Cron 定时触发，白虎面板还支持以下特殊触发场景：
+
+### 开机启动任务 (`baihu_startup`)
+
+当您在定时规则（Schedule）中填写 `baihu_startup` 时，该任务将被标记为**系统启动任务**。
+- **触发时机**: 面板主进程启动或重启完成后立即执行。
+- **应用场景**: 
+  - 自动挂载磁盘或网络共享。
+  - **环境预热**: 例如安装 PHP 编译依赖（参考 [PHP 编译依赖说明](languages.md#php-环境特别说明)）。建议命令: `bash example/deps/install_php_env_deps.sh`
+  - 启动自定义的后台常驻服务。
diff --git a/example/deps/install_php_env_deps.sh b/example/deps/install_php_env_deps.sh
new file mode 100644
index 0000000..2fb41ef
--- /dev/null
+++ b/example/deps/install_php_env_deps.sh
@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# ==============================================================================
+# PHP 环境构建依赖安装脚本
+# ==============================================================================
+# 说明：
+# 如果你需要使用 PHP 环境，由于 mise 安装某些 PHP 版本时需要从源码编译，
+# 建议在面板的“任务训练”中创建一个“开机任务”，并关联此脚本，
+# 以确保容器重启后依然具备编译 PHP 所需的系统依赖。
+# ==============================================================================
+
+set -e
+
+echo "正在检测 PHP 编译依赖..."
+
+# 根据系统定义包列表
+if [ -f /etc/debian_version ]; then
+    PACKAGES="autoconf bison build-essential libssl-dev libxml2-dev pkg-config libsqlite3-dev zlib1g-dev libcurl4-openssl-dev libpng-dev libjpeg-dev libonig-dev libzip-dev"
+    CHECK_CMD="dpkg -l"
+    INSTALL_CMD="apt-get install -y"
+    UPDATE_CMD="apt-get update"
+elif [ -f /etc/alpine-release ]; then
+    PACKAGES="autoconf bison build-base openssl-dev libxml2-dev pkgconfig sqlite-dev zlib-dev curl-dev libpng-dev libjpeg-turbo-dev oniguruma-dev libzip-dev"
+    CHECK_CMD="apk info -e"
+    INSTALL_CMD="apk add --no-cache"
+    UPDATE_CMD=""
+else
+    echo "未检测到支持的包管理器 (APT/APK)，请手动安装依赖。"
+    exit 1
+fi
+
+MISSING_PACKAGES=""
+for pkg in $PACKAGES; do
+    if ! $CHECK_CMD "$pkg" >/dev/null 2>&1; then
+        MISSING_PACKAGES="$MISSING_PACKAGES $pkg"
+    fi
+done
+
+if [ -z "$MISSING_PACKAGES" ]; then
+    echo "所有依赖已就绪，跳过安装。"
+    exit 0
+fi
+
+echo "检测到缺失依赖: $MISSING_PACKAGES"
+
+# 执行安装
+if [ -n "$UPDATE_CMD" ]; then
+    $UPDATE_CMD
+fi
+
+$INSTALL_CMD $MISSING_PACKAGES
+
+echo "PHP 编译依赖安装完成！"