项目介绍
青龙面板用于管理脚本、环境变量和定时任务。下面介绍容器配置,以及项目目录准备、访问与任务验证步骤。先使用一个不涉及账号操作的测试脚本检查定时执行和日志,再接入自己的实际任务。
version: '3'
services:
qinglong:
image: whyour/qinglong:latest
container_name: qinglong
ports:
- 5700:5700
volumes:
- /volume1/docker/qinglong:/ql/data
environment:
- QlPort=5700
restart: always
network_mode: bridge补充:部署与使用
安装与使用步骤
- 按仓库说明部署并持久化数据,完成管理员和通知设置。
- 添加一段只输出时间的测试脚本,检查时区、运行环境与日志。
- 明确任务频率、超时和失败通知,再导入自己审核过的脚本,限制凭据与目录范围。
首次使用与操作检查
创建只输出当前时间的脚本,分别手动和定时运行,检查时区。再添加一个无副作用的文件统计任务。
任务重叠先调整周期或加互斥。依赖失败与业务失败分开检查,凭据不写进脚本正文及公开日志。
Docker Compose
依据官方 README 的 Debian 镜像、qinglong 用户与 /ql/data 目录整理,使用命名卷。启动后打开 http://NAS_IP:5700 完成初始化,备份时包含 qinglong_data 卷。
群晖目录准备
在群晖 SSH 终端执行下面这一段,再将下方配置保存为 /volume1/docker/qinglong/compose.yaml。也可在 Container Manager 中新建项目,选择该目录并粘贴配置。
sudo sh <<'HALO_PREPARE'
set -eu
mkdir -p /volume1/docker/qinglong
cd /volume1/docker/qinglong
HALO_PREPARE
cd /volume1/docker/qinglong
配置中的命名卷由 Docker 创建并管理,不需要手动填写 UID/GID。备份时同时保存这些数据卷,不能只备份项目目录。
services:
qinglong:
image: whyour/qinglong:debian
user: qinglong
restart: unless-stopped
ports:
- "5700:5700"
volumes:
- qinglong_data:/ql/data
volumes:
qinglong_data:
在项目目录保存为 compose.yaml 后,先检查配置,再启动:
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100
配置与常见问题
- 不要为了安装依赖无差别执行陌生脚本合集;平台规则与账号权限仍需遵守。
- 页面无法打开:先用
docker compose ps检查状态,再核对宿主机端口、NAS 防火墙与应用日志。不要把容器端口随意改成另一个数字。 - 文件无法保存:核对宿主目录是否存在、挂载方向及运行用户的读写权限。不要直接给整个存储卷开放所有权限。
更新与备份
保存脚本、定时配置和必要变量,含 Cookie 的备份加密处理。
更新前保留原配置和数据备份,阅读所用版本的升级说明;确认兼容后再执行 docker compose pull 和 docker compose up -d。只回退镜像不一定能回退已经迁移过的数据库。
先用无副作用脚本验证定时任务
在面板新建测试脚本,只输出当前时间:
#!/bin/sh
date '+%Y-%m-%d %H:%M:%S %Z'
手动运行后先核对日志与时区,再通过当前面板支持的计划格式建立短期测试。确认定时执行时间正确后停用测试任务。不要把传统 cron 的字段数直接套到所有计划编辑器,以界面的实际提示为准。
正式任务逐项记录运行目录、依赖、输入变量、超时和失败通知。出现重叠运行时先设置互斥或调整周期;凭据存到面板变量,并检查脚本是否会把变量全部打印到日志。备份 /ql/data 对应的持久化数据,恢复后先暂停任务,再验证变量和计划。
参考资料
配图来自 whyour/qinglong 官方仓库,按 Apache-2.0 许可 保留来源与许可;图片只做等比例缩小和压缩。
界面展示

图 1:官方仓库提供的项目示意图,用于说明功能与布局。