青龙面板安装教程：Docker Compose 部署 + 创建第一个定时任务（v2.24 实测）

在 Linux 服务器上维护自动化脚本时，系统自带的 crontab 往往是大家的第一选择。然而随着脚本数量增多，纯命令行的定时任务会暴露出许多维护痛点：缺乏可视化的执行历史、日志分散难以回溯、多语言依赖隔离繁琐、环境变量分散在不同配置文件中，且临时想手动跑一次脚本必须远程登录终端敲命令。

青龙面板（Qinglong）正是为了解决这些调度与运维痛点而生的开源定时任务管理平台。项目在 GitHub 上斩获超过 2 万星标，支持原生运行 Python3、JavaScript (Node.js)、Shell 以及 TypeScript 脚本。面板内置了直观的仪表盘概览、依赖在线安装、多格式订阅更新、全局与任务级环境变量注入以及运行日志即时查看等功能，非常适合用来跑定时备份、监控探针、数据同步和自定义自动化任务。

本文基于官方 whyour/qinglong:latest 镜像（对应版本 v2.24.0，实测日期 2026-11-03），手把手演示如何使用 Docker Compose 快速部署面板、完成全新的初始化配置向导，并规范地创建、调试你的第一个自动化定时任务。

准备工作与 Docker Compose 部署

生产环境下建议将容器的所有运行数据挂载到宿主机本地，以便日常备份与后续无缝平滑升级。这里我们在宿主机创建一个专门存放青龙配置的目录，并使用 Docker Compose 统一管理容器服务。

首先在终端中创建项目工作目录并进入：

mkdir -p ~/qinglong && cd ~/qinglong

在当前目录下创建 docker-compose.yml 文件，内容如下：

services:
  qinglong:
    image: whyour/qinglong:latest
    container_name: qinglong
    restart: unless-stopped
    volumes:
      - ./ql/data:/ql/data
    ports:
      - "5700:5700"

该配置定义了容器核心参数：镜像拉取官方最新版；容器异常退出时自动拉起（unless-stopped）；将面板持久化路径 /ql/data 挂载到宿主机的 ./ql/data 目录；对外暴露默认的 5700 端口。

配置编写完成后，在终端执行以下命令以后台模式拉取镜像并启动容器：

docker compose up -d

首次拉取镜像大约需要 1 到 2 分钟。启动完成后，可以使用 docker compose ps 确认容器运行状态是否为 Up。若状态正常，打开本地浏览器，直接访问 http://<你的服务器IP>:5700 进入下一步。

走完初始化配置向导

容器启动后，浏览器首次访问 5700 端口并不会直接跳转到登录页面，而是会自动引导进入「初始化配置」安装向导。新版青龙面板已经完全去除了硬编码的初始凭证，必须通过该向导手动设定管理员账户。

1. 欢迎使用：在欢迎界面确认面板版本后，直接点击下方的「开始安装」按钮进入配置流程。
2. 通知设置：面板支持多种告警通知渠道（如邮件、Telegram、Webhook 等）。新部署环境下此项非必填，建议点击「跳过」，等后续进入系统后再根据业务需求在设置中按需配置。
3. 账户设置：在此页面设定登录管理界面的「用户名」与「密码」。请务必记住此处输入的凭证。
4. 完成安装：设置完成后点击提交，界面提示「恭喜安装完成！」，点击「去登录」按钮即可跳转至正式登录界面，输入刚才设定的账号密码登录。

登录后台与仪表盘概览

登录成功后，系统首先展现的是全局仪表盘概览。顶部卡片直观汇总了当前系统的核心运行指标：总任务数、已启用任务数、今日执行次数以及整体执行成功率；下方图表则实时渲染了近 7 日任务执行趋势曲线与健康状况，方便管理员一眼掌握近期任务调度是否存在集中报错或超时堆积。

左侧导航栏包含了面板的全部功能模块：定时任务列表、脚本在线编辑器、配置文件管理、全局与局部环境变量池、依赖管理（可在线通过 npm/pip 安装运行库），以及系统日志与高级设置。所有模块均已围绕自动化运维体系构建完备。

创建并执行第一个定时任务

为了验证调度引擎运转正常，我们无需直接引入复杂的业务代码，先通过面板创建一个最基础的标准 Shell 命令任务，并观察其调度计算与手动执行输出流程。

1. 进入任务列表：点击左侧导航栏中的「定时任务」进入任务管理大厅。
2. 打开创建弹窗：点击页面右上角蓝色的「创建任务」按钮。
3. 填写任务名称：在弹窗中将任务名称设置为 演示任务-每天打个招呼，方便后续检索与识别。
4. 指定执行命令：在「命令/脚本」一栏输入 echo hello-qinglong。青龙执行器会直接在容器内的 Shell 环境中解析并运行这行指令。如果你放置了自己的脚本，此处则对应 python3 /ql/data/scripts/your_script.py 等路径。
5. 设定 Cron 表达式：在「定时规则」中填入 0 9 * * *，表示每天早晨 9:00:00 准时触发调度。
6. 保存任务：确认参数无误后，点击弹窗右下角的「确定」完成创建。
7. 核对计算时间：任务保存后会立即出现在任务列表中。面板的调度调度器会立即根据当前服务器系统时间，自动精确计算出下一次触发时间（例如本例的 2026-11-03 09:00:00，见图 5）并呈现在表格中。
8. 手动测试触发：找到刚建好的任务行，点击操作列的「运行」图标。面板会弹出「确认运行」二次确认框，点击确认后该任务会脱离定时队列立即执行一次。
9. 查看执行日志：执行完毕后，点击该行操作栏中的「日志」按钮，控制台会立刻弹出执行终端日志，可以看到容器环境成功输出了 hello-qinglong 并显示完成状态。

生产使用与踩坑实录

在日常将青龙面板接入真实业务（如服务器状态拉取、备份脚本归档、API 定时同步）的过程中，有几个非常隐蔽但高频出现的机制陷阱需要格外留意：

1. 定时规则的字段结构差异：
青龙 v2.24.0 的定时规则输入框采用的是六段式格式规范：秒(可选) 分 时 天 月 周。虽然第一位「秒」是可选的，但在从传统 Linux Crontab 或各类网络教程中复制常见的五段式规则（分 时 天 月 周）时，切勿盲目在开头补位。如果直接输入 0 9 * * *，系统会准确识别为五段规则并判定为每日 9 点整执行；但如果误以为第一位必须传秒而多加了一个 0 写成 0 0 9 * * *，则依然有效，可一旦把五位规则误当作含秒规则去篡改，就极容易导致执行周期错位成「每小时的第 0 秒」等意外频率。编写规则后，务必在列表中核查面板自动计算的「下次运行时间」是否符合预期。

2. 数据持久化目录与平滑升级机制：
在我们的 docker-compose.yml 中，唯一挂载的宿主机路径是 ./ql/data。青龙面板的所有核心资产均集中收敛于此：内置 SQLite 数据库（记录任务与日志元数据）、全局环境变量列表、在线拉取的自定义脚本文件以及执行日志文件。正因如此，面板的版本升级极其简单干净：在项目目录下执行 docker compose pull && docker compose up -d 即可自动替换为新镜像。但在升级或对服务器做大改动之前，务必优先针对宿主机的 ./ql/data 目录打一个 tar.gz 压缩包做冷备份，只要数据目录完好，即使容器被强行销毁也能分秒级完整还原。