青龙（Qinglong）项目中的Python脚本定时任务管理技巧：从入门到精通

你是否还在为Python脚本的定时执行烦恼？手动运行太麻烦，系统自带的定时任务配置复杂，出错了还难以排查？本文将带你全面掌握青龙（Qinglong）定时任务管理平台中Python脚本的高效管理技巧，从基础配置到高级优化，让你的自动化任务稳定又高效。读完本文，你将学会如何创建、调试、监控Python定时任务，以及如何利用青龙的高级功能提升任务可靠性和可维护性。

青龙项目简介

青龙（Qinglong）是一个功能强大的定时任务管理平台，支持Python3、JavaScript、Shell和Typescript等多种脚本语言。它提供了直观的Web界面，让用户可以轻松管理定时任务，包括任务创建、编辑、删除、禁用、启用等操作，同时还支持日志查看、环境变量管理、依赖管理等高级功能。

青龙的主要功能包括：

• 支持多种脚本语言（python3、javaScript、shell、typescript）
• 支持在线管理脚本、环境变量、配置文件
• 支持在线查看任务日志
• 支持秒级任务设置
• 支持系统级通知
• 支持暗黑模式
• 支持手机端操作

更多详细信息，请参考青龙项目官方文档。

Python脚本定时任务基础

创建Python定时任务

在青龙中创建Python定时任务非常简单，只需按照以下步骤操作：

1. 登录青龙管理界面，进入"定时任务"页面。
2. 点击"添加任务"按钮，打开任务创建窗口。
3. 填写任务名称、定时规则（Cron表达式）、命令（Python脚本路径）等信息。
4. 点击"确定"按钮，完成任务创建。

青龙提供了一个Python脚本示例，位于sample/ql_sample.py，内容如下：

"""
任务名称
name: script name
定时规则
cron: 1 9 * * *
"""

print("test script")
print(QLAPI.notify("test script", "test desc"))
print("test systemNotify")
print(QLAPI.systemNotify({"title": "test script", "content": "dddd"}))
print("test getEnvs")
print(QLAPI.getEnvs({"searchValue": "1"}))
print("test desc")

从示例中可以看到，Python脚本的定时规则通过注释中的cron字段指定，格式为标准的Cron表达式。任务名称通过name字段指定。

Cron表达式详解

Cron表达式是一种用于指定定时任务执行时间的字符串格式，由5个或6个空格分隔的字段组成，分别表示分钟、小时、日、月、周（可选）。

青龙项目中定义了Cron相关的模型和状态枚举，位于back/data/cron.ts。其中，Cron任务的状态包括运行中（running）、排队中（queued）、空闲（idle）和已禁用（disabled）等。

以下是一些常用的Cron表达式示例：

Cron表达式	含义
* * * * *	每分钟执行一次
0 * * * *	每小时的第0分钟执行
0 0 * * *	每天凌晨0点执行
0 0 * * 1	每周一凌晨0点执行
0 0 1 * *	每月1日凌晨0点执行

任务管理API

青龙提供了丰富的API用于管理定时任务，相关接口定义位于back/api/cron.ts。通过这些API，我们可以实现任务的创建、查询、更新、删除、启用、禁用、运行、停止等操作。

例如，创建任务的API接口为POST /crons，请求体中需要包含任务的名称、命令、定时规则等信息。获取任务列表的API接口为GET /crons，可以通过查询参数筛选任务。

Python脚本高级功能

环境变量管理

在Python脚本中，我们可以通过青龙提供的QLAPI.getEnvs()方法获取环境变量。环境变量的管理可以通过青龙的Web界面进行，也可以通过API接口操作。

以下是一个获取环境变量的示例：

import QLAPI

# 获取所有环境变量
envs = QLAPI.getEnvs()
print(envs)

# 按名称搜索环境变量
envs = QLAPI.getEnvs({"searchValue": "API_KEY"})
print(envs)

任务通知

青龙提供了任务通知功能，可以通过QLAPI.notify()和QLAPI.systemNotify()方法发送通知。通知可以通过多种渠道发送，如邮件、短信、企业微信等，具体配置可以在青龙的设置页面进行。

以下是发送通知的示例：

import QLAPI

# 发送普通通知
QLAPI.notify("任务完成通知", "Python脚本定时任务已成功执行")

# 发送系统通知
QLAPI.systemNotify({"title": "系统通知", "content": "Python脚本定时任务执行结果"})

依赖管理

青龙支持Python脚本的依赖管理，可以通过Web界面安装、更新和卸载Python依赖包。依赖管理相关的代码位于back/data/dependence.ts。

在Python脚本中，可以直接导入已安装的依赖包，无需额外配置。

任务监控与调试

日志查看

青龙提供了详细的任务执行日志，可以通过Web界面查看，也可以通过API接口获取。日志相关的API接口定义位于back/api/cron.ts中的GET /crons/:id/log和GET /crons/:id/logs接口。

通过日志，我们可以了解任务的执行情况，排查脚本错误。例如，以下代码可以获取指定任务的日志：

import requests

# 青龙API地址
QL_API_URL = "http://localhost:5700/api"
# 青龙API令牌
QL_API_TOKEN = "your_api_token"

# 获取任务日志
def get_task_log(task_id):
    url = f"{QL_API_URL}/crons/{task_id}/log"
    headers = {"Authorization": f"Bearer {QL_API_TOKEN}"}
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        return response.json()["data"]
    else:
        return None

# 示例：获取ID为1的任务日志
log = get_task_log(1)
print(log)

任务状态监控

青龙提供了任务状态监控的功能，可以通过Web界面实时查看任务的运行状态，也可以通过API接口获取任务状态。任务状态相关的API接口定义位于back/api/cron.ts中的PUT /crons/status接口。

以下是一个监控任务状态的示例：

import requests
import time

# 青龙API地址
QL_API_URL = "http://localhost:5700/api"
# 青龙API令牌
QL_API_TOKEN = "your_api_token"

# 获取任务状态
def get_task_status(task_id):
    url = f"{QL_API_URL}/crons/{task_id}"
    headers = {"Authorization": f"Bearer {QL_API_TOKEN}"}
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        return response.json()["data"]["status"]
    else:
        return None

# 监控任务状态
def monitor_task(task_id, interval=5):
    while True:
        status = get_task_status(task_id)
        print(f"任务状态：{status}")
        # 任务完成（状态为idle）或失败时退出监控
        if status == 1 or status is None:  # 1表示idle状态
            break
        time.sleep(interval)

# 示例：监控ID为1的任务
monitor_task(1)

性能优化技巧

任务优先级设置

青龙支持任务的优先级设置，可以通过任务的isPinned属性将重要任务置顶。相关的API接口为PUT /crons/pin和PUT /crons/unpin，定义位于back/api/cron.ts。

以下是通过API设置任务置顶的示例：

import requests

# 青龙API地址
QL_API_URL = "http://localhost:5700/api"
# 青龙API令牌
QL_API_TOKEN = "your_api_token"

# 置顶任务
def pin_task(task_id):
    url = f"{QL_API_URL}/crons/pin"
    headers = {"Authorization": f"Bearer {QL_API_TOKEN}", "Content-Type": "application/json"}
    data = [task_id]
    response = requests.put(url, headers=headers, json=data)
    return response.status_code == 200

# 取消置顶任务
def unpin_task(task_id):
    url = f"{QL_API_URL}/crons/unpin"
    headers = {"Authorization": f"Bearer {QL_API_TOKEN}", "Content-Type": "application/json"}
    data = [task_id]
    response = requests.put(url, headers=headers, json=data)
    return response.status_code == 200

# 示例：置顶ID为1的任务
pin_task(1)

任务依赖管理

当多个Python脚本任务之间存在依赖关系时，我们可以通过青龙的任务前后置功能来管理。相关的属性为任务的task_before和task_after，定义位于back/data/cron.ts中的Crontab模型。

task_before表示当前任务执行前需要执行的任务ID，task_after表示当前任务执行后需要执行的任务ID。通过设置这两个属性，我们可以实现任务之间的顺序执行。

以下是一个设置任务依赖的示例：

import requests

# 青龙API地址
QL_API_URL = "http://localhost:5700/api"
# 青龙API令牌
QL_API_TOKEN = "your_api_token"

# 更新任务信息
def update_task(task_id, task_data):
    url = f"{QL_API_URL}/crons"
    headers = {"Authorization": f"Bearer {QL_API_TOKEN}", "Content-Type": "application/json"}
    task_data["id"] = task_id
    response = requests.put(url, headers=headers, json=task_data)
    return response.status_code == 200

# 示例：设置任务2在任务1之后执行
update_task(2, {"task_before": 1})

总结与展望

通过本文的介绍，我们了解了青龙项目中Python脚本定时任务的管理技巧，包括任务的创建、Cron表达式的使用、环境变量管理、任务通知、日志查看、状态监控等基础功能，以及任务优先级设置、依赖管理等高级技巧。

青龙项目提供了丰富的API接口，位于back/api/cron.ts，通过这些API，我们可以实现任务的自动化管理。未来，我们可以进一步探索青龙的高级功能，如分布式任务调度、任务负载均衡等，以满足更复杂的定时任务管理需求。

希望本文对你有所帮助，让你的Python脚本定时任务管理更加高效、稳定。如果你有任何问题或建议，欢迎在青龙项目的Issues页面反馈。

最后，记得点赞、收藏、关注，获取更多青龙项目的使用技巧和最佳实践！