青龙控制面板如何配置定时任务？

Question

如何在青龙控制面板中正确配置定时任务的Cron表达式？常见问题包括：为何添加的定时任务未按时执行？是否支持秒级调度？如何设置每日多次运行的任务？特别是在跨时区部署时，时间是否需手动调整？此外，从GitHub拉取的脚本如何自动注入环境变量并绑定定时规则？请结合实际场景说明配置要点与排错方法。

Answer 1

青龙面板定时任务Cron表达式配置深度解析

一、基础概念：Cron表达式的结构与语法

Cron表达式是用于定义周期性任务执行时间的字符串，通常由6或7个字段组成。青龙面板（QingLong Panel）基于Linux Cron标准，并扩展支持秒级字段。

字段位置	含义	取值范围
1	秒	0-59
2	分钟	0-59
3	小时	0-23
4	日期	1-31
5	月份	1-12
6	星期	0-7 (0和7都表示周日)
7（可选）	年份	留空或1970-2099

例如：0 0 8 * * * 表示每天上午8点整执行一次。

二、是否支持秒级调度？

青龙面板使用的Node.js定时库（如node-cron）默认不支持秒级，但青龙通过集成time-out-manager或自研调度器实现了扩展Cron格式，支持6位（含秒）表达式。

• 原生Cron（5位）：不支持秒，最小粒度为分钟
• 扩展Cron（6位）：格式为 s m h D M W，支持秒级触发

验证方式可通过添加测试任务：

5 * * * * * echo "每分钟第5秒执行"

若该任务能准时触发，则说明环境已启用秒级调度。

三、如何设置每日多次运行的任务？

实际场景中，如京东签到脚本需在每日多个时间段重试以应对网络波动，可使用以下Cron配置：

需求	Cron表达式	说明
每天7点、12点、18点运行	0 0 7,12,18 * * *	使用逗号分隔多个小时
每30分钟执行一次	0 */30 * * * *	注意分钟字段步长写法
工作日上午9点执行	0 0 9 * * 1-5	仅周一至周五

四、跨时区部署下的时间偏差问题

青龙面板的时间基准取决于宿主机系统时区。若服务器位于UTC时区而用户期望北京时间（UTC+8）执行任务，则必须进行换算。

例如：希望每天早上7:00北京时间执行，对应UTC时间为前一日23:00：

0 0 23 * * *

解决方案建议：

1. 统一容器/服务器时区为Asia/Shanghai
2. 在docker-compose.yml中挂载时区文件或设置环境变量TZ
3. 避免手动换算，提升可维护性

五、从GitHub拉取脚本并自动绑定定时规则

青龙支持通过“脚本管理”→“导入在线脚本”功能从GitHub URL批量导入，并可配合extra.sh或task_before.sh实现自动化注入。

典型流程如下：

graph TD A[从GitHub获取脚本URL] --> B(调用QL API /api/v1/crontab) B --> C{判断是否包含cron标签} C -->|是| D[提取Cron表达式] C -->|否| E[使用默认间隔] D --> F[创建定时任务] F --> G[自动注入环境变量] G --> H[启用任务]

六、环境变量自动注入机制

许多JS脚本依赖环境变量（如Cookie），可通过以下方式实现自动绑定：

• 在脚本注释中声明//^ cron: 0 0 8 * * * 和 //^ new Env('京东签到')
• 青龙解析这些元信息后自动创建任务并关联变量
• 确保开启“自动恢复任务”和“自动导入定时”选项

示例脚本头部：

/**
 * @Author: QLScript Generator
 * cron: 0 30 7,12 * * *
 * new Env('美团领券');
 */
const $ = new Env('美团领券');
// 脚本逻辑...
    

七、常见问题排查清单

现象	可能原因	解决方法
任务未执行	时区不匹配	检查宿主机date命令输出
执行时间偏移	使用了UTC而非本地时间	设置TZ=Asia/Shanghai
重复导入任务	脚本含多个cron标签	清理冗余注释
环境变量未生效	未正确绑定或命名错误	核对env name大小写
秒级任务失效	底层库未启用秒级支持	升级青龙至v2.15+
GitHub脚本无定时	缺少cron元数据	手动添加或修改源码

八、高级实践：动态Cron与API控制

对于复杂调度需求（如节假日跳过、条件性执行），可结合外部服务动态更新Cron。

利用青龙OpenAPI，通过curl实现程序化管理：

# 更新任务Cron表达式
curl -X PUT 'http://your-qinglong:5700/api/v1/crontab' \
-H 'Authorization: Bearer <token>' \
-d '{
  "id": 123,
  "command": "node /scripts/jd_sign.js",
  "schedule": "0 0 9 * * *"
}'
    

此方式适用于CI/CD流水线中自动同步调度策略。