MyTube/documents/zh/hooks-guide.md

任务钩子使用指南 (Task Hooks Guide)

MyTube 允许您在下载任务的不同阶段执行自定义 Shell 脚本，用于后处理、通知或外部集成。

可用钩子 (Available Hooks)

钩子名称	触发时机	描述
任务开始前 (task_before_start)	下载开始前	在下载开始前立即执行。
任务成功 (task_success)	下载成功后	下载/合并完成后执行，且在云存储上传（若启用）或删除之前执行。
任务失败 (task_fail)	任务失败时	下载失败时执行。
任务取消 (task_cancel)	任务取消时	用户取消正在运行的任务时执行。

默认脚本目录为 backend/data/hooks。

环境变量 (Environment Variables)

变量	描述	示例
MYTUBE_TASK_ID	任务唯一标识	335e98f0-15cb-46a4-846d-9d4351368923
MYTUBE_TASK_TITLE	视频/任务标题	Awesome Video Title
MYTUBE_SOURCE_URL	视频原始 URL	https://www.youtube.com/watch?v=...
MYTUBE_TASK_STATUS	当前状态	start, success, fail, cancel
MYTUBE_VIDEO_PATH	视频文件绝对路径	/app/uploads/videos/video.mp4
MYTUBE_THUMBNAIL_PATH	缩略图绝对路径	/app/uploads/images/video.jpg
MYTUBE_ERROR	错误消息（仅 task_fail）	Network timeout

配置 (Configuration)

1. 进入 设置 (Settings)。
2. 打开 高级设置 (Advanced Settings)。
3. 找到 任务钩子 (Task Hooks)。
4. 上传对应事件的 .sh 脚本。
5. 需要时可删除或重新上传。

钩子脚本使用 bash 执行，上传后会自动赋予可执行权限。

查看日志 (Viewing Logs)

脚本输出 (stdout/stderr) 会被后端捕获并记录。

• 标准输出 (echo "...") 记录为 INFO。
• 标准错误 (>&2 echo "...") 记录为 WARN。

示例：

echo "Hook started for task $MYTUBE_TASK_ID"

在服务器日志中将显示为： [INFO] [HookService] task_success stdout: Hook started for task 123...

示例 (Examples)

1. 简单日志记录

将每个成功的下载记录到自定义文件中。 钩子: task_success

#!/bin/bash
# 请提供日志文件的完整路径
echo "[$(date)] Downloaded: $MYTUBE_TASK_TITLE" >> /tmp/mytube_downloads.log

2. 发送通知 (例如 ntfy.sh)

当任务失败时发送通知。 钩子: task_fail

#!/bin/bash
curl -d "MyTube Download Failed: $MYTUBE_TASK_TITLE - $MYTUBE_ERROR" https://ntfy.sh/my_topic

3. 文件后处理

运行 Python 脚本处理文件。 钩子: task_success

#!/bin/bash
python3 /path/to/process_video.py "$MYTUBE_VIDEO_PATH"

安全警告 (Security Warning)

Warning

钩子命令以与 MyTube 后端相同的权限执行。

• 使用修改或删除文件的命令时请务必小心。
• 请勿复制粘贴来自不可信来源的脚本。
• 确保脚本能正确处理错误。