Initial commit: TaskPool React panel

- React frontend with route-level code splitting - Backend rebranded from Baihu to TaskPool - DB brand migration script and local compatibility
2026-07-26 08:43:52 +08:00
commit e6956aa001
397 changed files with 73621 additions and 0 deletions
@@ -0,0 +1,191 @@
+# 浏览器示例
+
+`example/playwright` 提供了一组远程浏览器脚本示例，演示如何连接 **Browserless**。
+
+> [!NOTE]
+> 本示例以 Browserless 为主要演示对象。以此类推，您也可以使用其他的浏览器镜像（如原生的 `headless-shell` 或其他的浏览器集群服务）进行部署，只要它们支持 CDP 协议。
+
+---
+
+## 部署方式对比
+
+taskpool强烈建议采用 **单独部署浏览器服务（如 Browserless）** 的方案，而不是在任务池镜像内部安装浏览器。
+
+### 本地部署 (在任务池容器内安装) 的缺点
+- **资源争抢**：浏览器是极度的“内存/CPU 杀手”，在同一容器内运行多任务极易导致任务池主进程因 OOM (内存溢出) 而崩溃。
+- **镜像臃肿**：安装 Chromium 后，原本精简的 Docker 镜像体积会暴增数倍（增加 500MB+），导致拉取和更新缓慢。
+- **依赖环境复杂**：在精简镜像中安装浏览器常会遇到各种缺失 `.so` 库文件的底层错误，排查极其困难。
+- **不利于扩展**：无法实现多节点负载均衡，一个容器内的资源始终是有限的。
+
+### 远程部署 (Browserless) 的优势
+- **性能隔离**：浏览器的负载波动不会影响taskpool的稳定性。
+- **开箱即用**：专业的浏览器镜像是针对性优化的，包含所有底层依赖和沙箱安全配置。
+- **可视化调试**：大多数服务（如 Browserless）支持通过 VNC 同步查看浏览器画面，方便排查脚本逻辑。
+- **弹性伸缩**：支持多会话、多实例模式，可以应对高并发爬虫需求。
+
+---
+
+## 准备工作
+
+在taskpool中运行浏览器自动化脚本前，需要先配置好对应的 **语言环境** 与 **第三方依赖包**。
+
+### 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 连接远程浏览器：
+
+- 不要执行 `playwright install`
+- 不需要额外下载 Chromium / Firefox / WebKit
+- 直接使用 `connect_over_cdp` 连接远程浏览器即可
+
+## 适用场景
+
+- 验证任务池到 Browserless 的网络连通性
+- 验证远程浏览器地址和 Token 是否配置正确
+- 快速测试浏览器自动化脚本是否能正常运行
+- 快速确认 Node.js / Python 语言环境是否已经配置完成
+- 作为后续网页自动化脚本的基础模板
+
+## 推荐部署方式
+
+建议配合 `browserless/chromium` 一起使用，再由任务池中的脚本连接远程浏览器服务。
+
+参考 `docker-compose.yml`：
+
+```yaml
+version: "3.8"
+
+services:
+  browser:
+    image: ghcr.io/browserless/chromium:latest
+    container_name: browser
+    restart: unless-stopped
+    environment:
+      MAX_CONCURRENT_SESSIONS: 5
+      MAX_QUEUE_LENGTH: 20
+      CONNECTION_TIMEOUT: 300000
+      DEFAULT_LAUNCH_ARGS: '["--no-sandbox","--disable-setuid-sandbox","--disable-dev-shm-usage"]'
+      TOKEN: your-secret-token
+      ENABLE_DEBUGGER: "false"
+    shm_size: "1gb"
+    mem_limit: 2g
+    cpus: 2
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/healthz"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+
+  taskpool:
+    image: ghcr.io/engigu/taskpool:latest
+    container_name: taskpool
+    restart: unless-stopped
+    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/taskpool.db
+      - BH_DB_TABLE_PREFIX=taskpool_
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+    depends_on:
+      - browser
+```
+
+## 使用步骤
+
+1. 启动 `browser` 和 `taskpool` 服务。
+2. 在任务池的“语言依赖”中安装对应包。
+3. 按实际环境修改脚本中的 Browserless 地址和 Token。
+4. 在任务池中创建任务并运行对应脚本。
+
+Python 示例的核心写法如下：
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.connect_over_cdp(
+        "http://browser:3000?token=your-secret-token"
+    )
+    page = browser.new_page()
+    page.goto("https://www.baidu.com")
+    page.screenshot(path="baidu.png")
+    browser.close()
+```
+
+## 运行前检查
+
+- Browserless 服务已经正常启动
+- 任务池可以访问 Browserless 地址
+- `TOKEN` 与 Browserless 配置保持一致
+- 脚本中的地址、端口和协议填写正确
+
+## 常见问题
+
+### 1. 报错提示找不到模块
+
+通常是还没有在“语言依赖”中安装对应包：
+
+- Node.js 示例需要 `puppeteer-core`
+- Python 示例需要 `playwright`
+
+### 2. 为什么没有执行 `playwright install`
+
+这是预期行为。
+
+如果你使用的是 Browserless 这类远程浏览器服务，Playwright 只是作为客户端发起连接，不需要在任务池容器里再下载本地浏览器，所以通常不要执行 `playwright install`。
+
+### 3. 连接不上 Browserless
+
+请优先检查：
+
+- Browserless 服务是否正常启动
+- Token 是否正确
+- 任务池与 Browserless 是否在同一网络中
+- 地址是否写成了当前运行环境可访问的地址
+
+### 4. 页面打开超时
+
+可以尝试：
+
+- 换一个更稳定的目标站点
+- 调大超时时间
+- 增加 Browserless 容器的 `shm_size`
+- 检查容器 CPU / 内存是否不足
+
+### 5. 没有看到截图文件
+
+请确认：
+
+- 脚本已经执行成功
+- 截图保存路径是否正确
+- 任务工作目录是否符合预期
+
+## 说明
+
+这组示例主要用于快速验证任务池与远程浏览器服务之间的连通性，以及对应语言环境是否已经配置完成。
@@ -0,0 +1,296 @@
+# 内置库示例
+
+taskpool提供了一个名为 `taskpool` 的内建包（Built-in SDK），支持 Python 和 Node.js。通过该内置库，您可以在脚本中实现**消息推送**、**环境变量管理**以及**任务执行控制**等高级功能。
+
+---
+
+## 准备工作
+
+在运行内置库脚本之前，请确保完成了以下步骤：
+
+### 1. 安装内置包
+在taskpool的「终端」页面中，或者通过创建临时任务执行以下命令，为面板管理的所有语言环境安装 `taskpool` 包：
+
+```bash
+taskpool builtininstall
+```
+
+### 2. 配置环境变量
+根据您需要调用的功能，在定时任务的“环境变量”或“机密”中配置以下对应 Key：
+
+#### 消息推送所需环境变量
+- **`BHPKG_NOTIFY_TOKEN`**：进入「消息推送」->「脚本调用说明」页面即可找到。
+- **`BHPKG_NOTIFY_CHANNEL`**：进入「消息推送」->「渠道列表」页面，查看对应渠道的 **ID**。
+- **`BHPKG_NOTIFY_URL`** (可选)：默认为 `http://localhost:8052/api/v1/notify/send`。如果修改了主服务端口，需要同步修改。
+
+#### 环境变量管理与定时任务控制所需环境变量
+- **`BHPKG_OPENAPI_TOKEN`** (或 `OPENAPI_TOKEN`)：用于 OpenAPI 接口鉴权，进入「系统设置」->「OpenAPI」页面，生成并复制 Token。
+- **`BHPKG_OPENAPI_URL`** (或 `OPENAPI_URL`，可选)：默认为本地面板 API 地址。若在非标准环境下运行，可手动指定（例如 `http://localhost:8052`）。
+
+---
+
+## 消息通知示例
+
+只需要一行代码即可触发零配置推送。
+
+::: code-group
+
+```python [Python]
+import taskpool
+
+def main():
+    print("正在尝试发送 Python 内建通知...")
+    try:
+        # 调用内置 notify 函数
+        # 内部会自动使用环境变量进行鉴权和投递
+        response = taskpool.notify(
+            title="Python 任务提醒",
+            text="这是一条来自 Python 示例脚本的通知消息。调用非常简单！"
+        )
+        print("发送请求已处理。")
+        if response:
+            print(f"服务器响应: {response}")
+            
+    except Exception as e:
+        print(f"发送过程发生异常: {e}")
+
+if __name__ == "__main__":
+    main()
+```
+
+```javascript [Node.js]
+const taskpool = require('taskpool');
+
+console.log("正在尝试发送 Node.js 内建通知...");
+
+try {
+    // 简单的一行代码即可完成推送，内置包采用异步非阻塞发送
+    taskpool.notify(
+        "Node.js 任务提醒", 
+        "这是一条来自 Node.js 示例脚本的通知消息。无需配置 API 地址或 Token。"
+    );
+    console.log("发送请求已提交。");
+    
+} catch (e) {
+    console.error(`通知失败: ${e.message}`);
+}
+```
+
+:::
+
+---
+
+## 环境变量管理
+
+内置库支持对面板的环境变量进行增删改查。
+
+### 支持方法
+
+* **Python**: 
+  - `get_envs()`: 获取所有环境变量列表。
+  - `get_env(name)`: 根据变量名称获取详情。
+  - `add_env(name, value, remark)`: 添加新的环境变量。
+  - `update_env(id, name, value, remark)`: 更新指定 ID 的环境变量值。
+  - `delete_env(id)`: 根据 ID 删除环境变量。
+* **Node.js**:
+  - `getEnvs()`: 获取所有环境变量列表。
+  - `getEnv(name)`: 根据变量名称获取详情。
+  - `addEnv(name, value, remark)`: 添加新的环境变量。
+  - `updateEnv(id, name, value, remark)`: 更新指定 ID 的环境变量值。
+  - `deleteEnv(id)`: 根据 ID 删除环境变量。
+
+### 代码示例
+
+::: code-group
+
+```python [Python]
+import taskpool
+
+def main():
+    print("====== 开始运行 Python 环境变量管理示例 ======")
+    try:
+        # 1. 获取全部环境变量
+        envs = taskpool.get_envs()
+        print(f"当前共有 {len(envs)} 个环境变量")
+        
+        # 2. 新增一个临时环境变量
+        new_env_name = "BHPKG_TEST_KEY"
+        new_env_val = "HelloTaskPool"
+        print(f"正在创建环境变量: {new_env_name}...")
+        created_env = taskpool.add_env(
+            name=new_env_name,
+            value=new_env_val,
+            remark="Python SDK 测试自动创建"
+        )
+        print(f"创建成功: ID={created_env.get('id')}, Name={created_env.get('name')}")
+
+        # 3. 查询刚才创建的环境变量详情
+        checked_env = taskpool.get_env(new_env_name)
+        if checked_env:
+            print(f"成功查询到变量: {checked_env.get('name')} = {checked_env.get('value')}")
+
+            # 4. 修改该环境变量的值
+            updated_val = "HelloTaskPool_Updated"
+            print(f"正在修改环境变量的值为: {updated_val}...")
+            updated_env = taskpool.update_env(
+                id=checked_env.get("id"),
+                name=new_env_name,
+                value=updated_val,
+                remark="Python SDK 测试自动更新"
+            )
+            print(f"更新成功: Value={updated_env.get('value')}")
+
+            # 5. 删除该临时环境变量
+            print(f"正在删除临时环境变量: ID={checked_env.get('id')}...")
+            taskpool.delete_env(checked_env.get("id"))
+            print("删除成功！")
+            
+    except Exception as e:
+        print(f"环境变量操作失败: {e}")
+        print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。")
+
+if __name__ == "__main__":
+    main()
+```
+
+```javascript [Node.js]
+const taskpool = require('taskpool');
+
+async function main() {
+    console.log("====== 开始运行 Node.js 环境变量管理示例 ======");
+    try {
+        // 1. 获取全部环境变量
+        const envs = await taskpool.getEnvs();
+        console.log(`当前共有 ${envs.length} 个环境变量`);
+
+        // 2. 新增一个临时环境变量
+        const newEnvName = "BHPKG_TEST_KEY_JS";
+        const newEnvVal = "HelloTaskPoolJS";
+        console.log(`正在创建环境变量: ${newEnvName}...`);
+        const createdEnv = await taskpool.addEnv(
+            newEnvName,
+            newEnvVal,
+            "Node.js SDK 测试自动创建"
+        );
+        console.log(`创建成功: ID={createdEnv.id}, Name={createdEnv.name}`);
+
+        // 3. 查询该环境变量
+        const checkedEnv = await taskpool.getEnv(newEnvName);
+        if (checkedEnv) {
+            console.log(`成功查询到变量: ${checkedEnv.name} = ${checkedEnv.value}`);
+
+            // 4. 修改该环境变量的值
+            const updatedVal = "HelloTaskPoolJS_Updated";
+            console.log(`正在修改环境变量的值为: ${updatedVal}...`);
+            const updatedEnv = await taskpool.updateEnv(
+                checkedEnv.id,
+                newEnvName,
+                updatedVal,
+                "Node.js SDK 测试自动更新"
+            );
+            console.log(`更新成功: Value=${updatedEnv.value}`);
+
+            // 5. 删除该临时环境变量
+            console.log(`正在删除临时环境变量: ID={checkedEnv.id}...`);
+            await taskpool.deleteEnv(checkedEnv.id);
+            console.log("删除成功！");
+        }
+
+    } catch (e) {
+        console.error(`环境变量操作失败: ${e.message}`);
+        console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。");
+    }
+}
+
+main();
+```
+
+:::
+
+---
+
+## 定时任务管理与控制
+
+内置库支持查询面板的任务列表、最近的执行结果以及手动触发特定任务的运行。
+
+### 支持方法
+
+* **Python**: 
+  - `get_tasks()`: 获取所有定时任务列表。
+  - `execute_task(id)`: 立即触发指定 ID 任务的运行。
+  - `get_last_results()`: 获取最近任务的执行记录。
+* **Node.js**:
+  - `getTasks()`: 获取所有定时任务列表。
+  - `executeTask(id)`: 立即触发指定 ID 任务的运行。
+  - `getLastResults()`: 获取最近任务的执行记录。
+
+### 代码示例
+
+::: code-group
+
+```python [Python]
+import taskpool
+
+def main():
+    print("====== 开始运行 Python 任务管理与执行控制示例 ======")
+    try:
+        # 1. 获取所有任务列表
+        tasks = taskpool.get_tasks()
+        print(f"成功获取到 {len(tasks)} 个定时任务:")
+        for task in tasks[:5]:  # 仅打印前5个
+            print(f"  - [{task.get('id')}] {task.get('name')} (表达式: {task.get('schedule')}, 备注: {task.get('remark')})")
+
+        # 2. 尝试触发第一个任务的运行
+        if tasks:
+            target_task = tasks[0]
+            print(f"\n尝试手动触发任务运行: [{target_task.get('id')}] {target_task.get('name')}...")
+            taskpool.execute_task(target_task.get("id"))
+            print("执行指令发送成功。")
+
+        # 3. 获取最近的执行结果列表
+        results = taskpool.get_last_results()
+        print(f"\n最近共有 {len(results)} 条任务执行记录。")
+            
+    except Exception as e:
+        print(f"任务操作失败: {e}")
+        print("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。")
+
+if __name__ == "__main__":
+    main()
+```
+
+```javascript [Node.js]
+const taskpool = require('taskpool');
+
+async function main() {
+    console.log("====== 开始运行 Node.js 任务管理与执行控制示例 ======");
+    try {
+        // 1. 获取所有任务列表
+        const tasks = await taskpool.getTasks();
+        console.log(`成功获取到 ${tasks.length} 个定时任务:`);
+        tasks.slice(0, 5).forEach(task => { // 仅展示前5项
+            console.log(`  - [${task.id}] ${task.name} (表达式: ${task.schedule || ''}, 备注: ${task.remark || ''})`);
+        });
+
+        // 2. 尝试触发第一个任务的运行
+        if (tasks.length > 0) {
+            const targetTask = tasks[0];
+            console.log(`\n尝试手动触发任务运行: [${targetTask.id}] ${targetTask.name}...`);
+            await taskpool.executeTask(targetTask.id);
+            console.log("执行指令发送成功。");
+        }
+
+        // 3. 获取最近的执行结果列表
+        const results = await taskpool.getLastResults();
+        console.log(`\n最近共有 ${results.length} 条任务执行记录。`);
+
+    } catch (e) {
+        console.error(`任务操作失败: ${e.message}`);
+        console.log("提示: 请确保在面板任务设置中正确注入了 OpenAPI Token。");
+    }
+}
+
+main();
+```
+
+:::
@@ -0,0 +1,27 @@
+# 脚本示例
+
+任务池内置了一批可直接参考的脚本示例，适合用来验证运行环境、演示常见用法，或者作为你自己脚本的起点。
+
+如果你使用 Docker 镜像启动任务池，容器启动后会自动将仓库中的 `example` 目录同步到脚本目录下。通常你可以在脚本目录中看到：
+
+```text
+example/
+```
+
+使用脚本示例前，建议先完成下面几步：
+
+1. 确认示例文件已经同步到脚本目录。
+2. 根据脚本语言，到“语言依赖”页面安装对应依赖包。
+3. 按实际环境修改脚本中的地址、Token、账号或其他配置。
+4. 在任务管理中选择对应脚本并运行。
+
+> [!TIP]
+> 如果示例脚本依赖第三方包，但你还没有在“语言依赖”中安装，对应任务通常会直接报缺少模块或包。
+
+## 当前示例
+
+目前文档已经整理出的示例类型：
+
+- [浏览器示例](./browser.md)
+- [内置库示例](./builtin.md)
+- [Linux 环境依赖示例](./linux-deps.md)
@@ -0,0 +1,111 @@
+# Linux 系统依赖处理
+
+在使用taskpool时，您可能会在运行某些脚本时遇到缺少底层 Linux 系统级依赖（例如 `apt` 或 `apk` 包）的情况。这篇指南将详细讲解如何优雅、持久地解决这些依赖问题。
+
+## 背景与痛点
+
+taskpool通常以 Docker 容器的形式运行。Docker 的文件系统具有以下特性：
+- **挂载目录（持久化）**：像 `data/` 这样的目录被映射到了宿主机，其中的数据（如脚本、日志、配置文件）在重启或升级镜像时会保留。
+- **容器层（非持久化）**：容器自身的系统目录（如 `/usr/bin`, `/lib`, `/etc`）是临时层。如果您直接在终端里手动执行 `apt-get install xxx`，虽然当下可以立即使用，**但在容器被销毁重建或更新镜像后，这些刚安装的系统包就会全部丢失。**（注意：仅仅是普通的 `docker restart` 重启容器并不会丢失，只有重建容器时才会重置）
+
+## 核心解决思路
+
+为了解决依赖丢失的问题，taskpool提供了一种自动化的解决方案：**利用 `taskpool_startup`（开机触发）类型的定时任务，在面板每次启动时自动执行一段依赖安装脚本。**
+
+这样，无论您如何更新镜像或重启容器，系统依赖都能在面板核心服务就绪前自动被补充安装，并且对后续的普通脚本任务透明。
+
+---
+
+## 具体操作步骤
+
+### 第一步：编写依赖安装脚本
+
+首先，在您的脚本目录（通常为 `data/scripts` 下，或者您可以单独建一个 `data/scripts/deps` 目录）创建一个 Shell 脚本，例如 `install_my_deps.sh`。
+
+由于taskpool的镜像目前均基于 Debian 系统，您可以直接在脚本中使用 `apt` 或 `apt-get` 命令来管理系统依赖。
+
+**示例 1：安装 Puppeteer (无头浏览器) 的依赖动态库**
+```bash
+#!/bin/bash
+# 遇到错误即停止执行
+set -e
+
+echo "正在检测并安装 Puppeteer 依赖..."
+
+# 提前 update 索引是非常重要的一步
+apt-get update
+apt-get install -y libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2
+
+echo "Puppeteer 依赖安装完成！"
+```
+
+**示例 2：安装 Python/C++ 编译所需的基础工具链**
+```bash
+#!/bin/bash
+set -e
+
+apt-get update
+# 安装 gcc, g++, make 以及 python3 相关的头文件
+apt-get install -y build-essential python3-dev
+```
+
+**示例 3：带 Hash 检查的高阶依赖安装脚本（推荐）**
+此脚本利用 `/tmp` 目录和脚本自身内容的哈希值，完美匹配 Docker 容器的生命周期，避免在普通重启时无意义地检测。
+```bash
+#!/bin/bash
+set -e
+
+# 生成当前脚本的哈希标识
+SCRIPT_HASH=$(md5sum "$0" | awk '{print $1}')
+FLAG_FILE="/tmp/deps_installed_${SCRIPT_HASH}"
+
+# 如果标识文件存在，说明在此容器生命周期内已安装过，且脚本未被修改，直接退出
+if [ -f "$FLAG_FILE" ]; then
+    echo "系统依赖已就绪，跳过安装。"
+    exit 0
+fi
+
+echo "开始安装系统环境依赖..."
+apt-get update
+# 假设您需要安装 ffmpeg 和 imagemagick
+apt-get install -y ffmpeg imagemagick
+
+# 安装成功后写入标识文件
+touch "$FLAG_FILE"
+echo "系统依赖安装完成！"
+```
+
+### 第二步：配置开机触发任务
+
+脚本编写并保存到面板后，接下来只需将其配置为开机任务：
+
+1. 进入面板的 **「定时任务」** 页面，点击 **「新建任务」**。
+2. **任务名称**: 填写容易辨识的名称，例如 “安装系统底层依赖”。
+3. **执行命令**: 输入执行该脚本的命令，例如 `bash deps/install_my_deps.sh` （假设您将脚本放在了 `deps` 文件夹下）。
+4. **触发类型**: 在下拉菜单中选择 **`taskpool_startup` (开机触发)**。
+5. **保存** 任务。
+
+现在，你可以尝试在终端中执行一下该任务验证脚本是否无误。一旦无误，未来每次容器重启，面板都会自动在后台静默执行这个任务，确保环境完备。
+
+---
+
+## 官方预设示例：PHP 编译依赖
+
+为了方便用户参考，我们在项目源码中内置了一个更完善的依赖安装脚本示例。
+
+通过 `mise` 安装某些 PHP 版本时，系统会尝试从源码编译，这就需要用到 `autoconf`, `bison`, `pkg-config` 等工具。
+
+如果您在安装 PHP 时遇到 `autoconf not found` 或 `buildconf failed`，可以直接使用项目根目录下的预设示例脚本：
+- **路径位置**: `example/deps/install_php_env_deps.sh`
+- **使用方法**: 新建 `taskpool_startup` 触发类型的任务，执行命令填写 `bash example/deps/install_php_env_deps.sh` 即可。
+
+此示例脚本中还包含了“检测是否已安装再决定是否执行 apt install”的逻辑，您可以查阅其源码作为编写自己依赖脚本的最佳实践参考。
+
+---
+
+## 注意事项与进阶建议
+
+1. **幂等性 (Idempotency)**：开机脚本在每次重启时都会在后台异步执行。像 `apt-get install -y` 这种命令天然是幂等的（如果已安装就不会重新下载），虽然它不会阻塞面板的启动速度，但每次无意义地检查和刷新软件源仍会白白占用开机初期的系统资源。建议您在脚本中先用 `dpkg -l <包名>` 或 `command -v <命令>` 判断依赖是否存在，不存在时再执行安装。
+   - **进阶技巧**：您也可以在依赖安装完成后，向 `/tmp` 目录下写入一个带有当前脚本内容 Hash 值的标识文件（例如 `touch /tmp/deps_installed_$(md5sum "$0" | awk '{print $1}')`）。在脚本开头判断该文件是否存在，若存在则直接退出。由于容器被销毁重建时 `/tmp` 目录和您安装的系统依赖会一并丢失，而在普通的重启中它们又会一并保留，这种方式完美契合了容器的临时层生命周期，能避免反复执行依赖检测逻辑，进一步加速开机任务。
+2. **网络环境**： Docker 镜像已经**默认将 APT 源替换为了清华源 (TUNA)**，因此在国内网络下执行 `apt-get` 也能获得很快的下载速度，您通常不需要在脚本中再次手动替换源。
+3. **避免冲突**：请仅安装您脚本运行强依赖的底层库，尽量不要通过 `apt` 安装 Node.js 或 Python 的运行环境，这些高级语言环境应交由面板的 **「编程语言」** (Mise) 模块统一管理。