青龙定时任务不触发如何排查？

Question

青龙定时任务不触发如何排查？一个常见问题是容器时区与宿主机不一致，导致 cron 表达式按错误时间执行。例如，青龙运行在 Docker 容器中，默认使用 UTC 时区，而用户设定的任务时间通常基于北京时间（CST/UTC+8）。此时即使配置为“每天早上7点”，实际会在 UTC 时间7点（即北京时间15点）运行，造成“未触发”假象。排查时应首先确认容器时区是否正确，可通过 exec 进入容器执行 `date` 命令查看；解决方案包括挂载宿主机 localtime 文件或设置环境变量 `TZ=Asia/Shanghai`，确保时间同步，从而解决任务不触发问题。

Answer 1

一、青龙定时任务不触发的常见现象与初步观察

在日常运维中，青龙（QingLong）作为一款流行的定时任务管理平台，广泛应用于自动化脚本调度场景。然而，部分用户反馈“定时任务未按预期执行”，尤其是在设定为早晨7点运行的任务迟迟没有触发。通过日志查看，发现任务并未报错，也未进入执行队列，造成“任务消失”的假象。

此时，首先应确认以下几点：

• 任务是否已启用（status = active）
• Cron 表达式语法是否正确（如：0 7 * * * 是否符合标准格式）
• 青龙服务本身是否正常运行（容器状态、内存占用、Web 界面可访问性）
• 系统时间显示是否与实际期望一致

若以上均无异常，则需深入排查底层环境因素，尤其是容器化部署中的时区配置问题。

二、根本原因分析：Docker 容器时区与宿主机不一致

青龙通常以 Docker 容器方式部署，而大多数基础镜像（如 Alpine、Debian）默认使用 UTC 时区。当用户在中国大陆设定 cron 任务为“每天7点执行”时，其本质是基于北京时间（UTC+8）的理解。

但由于容器内时间为 UTC，cron 解析器会将 0 7 * * * 理解为 UTC 时间7:00，对应北京时间15:00。因此任务并非“未触发”，而是延迟至下午三点才执行，导致使用者误以为任务失效。

可通过如下命令验证容器当前时区：

docker exec -it qinglong bash
date

输出示例：

Tue Apr 5 07:23:10 UTC 2025

明显与本地时间不符，说明存在时区偏差。

三、排查流程图：系统性诊断任务未触发问题

graph TD A[任务未触发] --> B{任务是否启用?} B -- 否 --> C[启用任务] B -- 是 --> D{Cron表达式正确?} D -- 否 --> E[修正格式] D -- 是 --> F{容器时间是否正确?} F -- 否 --> G[调整时区配置] F -- 是 --> H{任务日志是否有记录?} H -- 否 --> I[检查青龙日志ql.log] H -- 是 --> J[分析脚本执行逻辑] G --> K[完成修复]

四、解决方案对比：多种方式实现时区同步

方案	操作方式	优点	缺点	适用场景
挂载 localtime 文件	-v /etc/localtime:/etc/localtime:ro	时间精准，系统级生效	依赖宿主机配置，迁移不便	单机部署
设置 TZ 环境变量	environment: - TZ=Asia/Shanghai	轻量、可移植性强	部分旧程序可能忽略该变量	Docker Compose 部署
构建自定义镜像	在Dockerfile中RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime	固化配置，适合批量分发	增加维护成本	企业级标准化部署
宿主机cron调用API	使用宿主机crontab调用青龙接口	完全绕开容器时区问题	失去青龙内部调度灵活性	极端兼容需求

五、实践案例：通过 Docker Compose 修复时区问题

以下是一个典型的 docker-compose.yml 配置片段，用于部署青龙并正确设置时区：

version: '3'
services:
  qinglong:
    image: whyour/qinglong:latest
    container_name: qinglong
    environment:
      - TZ=Asia/Shanghai
    volumes:
      - ./config:/ql/config
      - ./log:/ql/log
      - ./scripts:/ql/scripts
    ports:
      - "5700:5700"
    restart: always

启动后再次执行 docker exec qinglong date，输出应为：

Tue Apr 5 15:23:10 CST 2025

表明时区已成功切换至北京时间，后续 cron 任务将按预期时间触发。