青龙面板完整搭建与实战使用教程

引言

青龙面板是一款基于Docker的开源定时任务管理面板，核心功能是可视化调度Python、Node.js、Shell等多语言脚本，广泛适用于运维自动化、个人脚本定时执行（如数据备份、API调用、开源项目签到）、批量任务处理等场景。相较于传统的Cron命令行管理，青龙面板提供了直观的Web界面、依赖管理、日志监控、多渠道通知等功能，极大降低了定时任务的维护成本。本文面向有Linux基础的开发者与运维人员，从环境准备、部署配置到实战应用，全方位讲解青龙面板的使用方法。

—

1. 环境准备与核心概念解析

1.1 前置环境要求

青龙面板推荐通过Docker部署，需确保服务器满足以下条件：

• 系统版本：Ubuntu 20.04+/CentOS 7+/Debian 10+（优先推荐Ubuntu，生态更完善）

• 硬件配置：至少1核1G内存，带宽1M以上（多脚本并行时建议2核2G以上）

• 网络配置：开放5700端口（青龙面板默认端口），服务器可访问公网（用于拉取镜像、脚本仓库）

1.2 核心概念提前掌握

• Cron表达式：定时任务的时间规则，格式为分 时 日 月 周，例如0 2 代表每日凌晨2点执行，/5 代表每5分钟执行一次。

• 脚本容器：青龙面板通过Docker隔离不同脚本的运行环境，避免依赖冲突，每个脚本可独立配置运行环境。

• 依赖管理：面板内置Python、Node.js等语言的依赖安装工具，可一键安装脚本所需的第三方库。

1.3 Docker环境安装

# Ubuntu系统安装Docker与Docker Compose

sudo apt update && sudo apt install -y docker.io docker-compose

启动Docker服务并设置开机自启

sudo systemctl start docker && sudo systemctl enable docker

验证安装是否成功

docker –version # 输出Docker版本信息即成功

docker-compose –version # 输出Docker Compose版本信息即成功

> 若服务器位于国内，建议配置Docker镜像加速器（如阿里云镜像源），避免镜像拉取缓慢：

> “`json

> # 编辑Docker配置文件/etc/docker/daemon.json

> {

> “registry-mirrors”: [“https://你的阿里云镜像加速器地址.mirror.aliyuncs.com”]

> }

> “`

> 配置完成后重启Docker：sudo systemctl restart docker

—

2. 青龙面板的Docker部署与初始化配置

2.1 两种部署方式选择

#### 方式一：Docker Compose部署（推荐）

Docker Compose可通过YAML文件统一管理容器配置，便于后续修改与迁移。

1. 创建青龙面板数据目录：

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

1. 编写docker-compose.yml配置文件：

version: '3.8'

services:

  qinglong:

    image: whyour/qinglong:latest  # 拉取最新版青龙面板镜像

    container_name: qinglong

    hostname: qinglong

    restart: always  # 容器异常退出时自动重启

    ports:

      - "5700:5700"  # 宿主机端口:容器内端口

    volumes:

      - ./config:/ql/config  # 配置文件持久化

      - ./log:/ql/log  # 日志文件持久化

      - ./db:/ql/db  # 数据库文件持久化

      - ./repo:/ql/repo  # 脚本仓库持久化

      - ./scripts:/ql/scripts  # 自定义脚本持久化

      - ./raw:/ql/raw  # 原始脚本文件持久化

    environment:

      - ENABLE_HANGUP=true  # 启用进程守护

      - ENABLE_WEB_PANEL=true  # 启用Web面板

1. 启动青龙面板容器：

docker-compose up -d

#### 方式二：单容器快速部署

若仅需临时测试，可直接使用docker run命令部署：

docker run -dit \

  -v $PWD/ql/config:/ql/config \

  -v $PWD/ql/log:/ql/log \

  -v $PWD/ql/db:/ql/db \

  -v $PWD/ql/repo:/ql/repo \

  -v $PWD/ql/raw:/ql/raw \

  -v $PWD/ql/scripts:/ql/scripts \

  -p 5700:5700 \

  --name qinglong \

  --hostname qinglong \

  --restart always \

  whyour/qinglong:latest

2.2 面板初始化配置

1. 访问青龙面板：在浏览器中输入http://你的服务器IP:5700，首次进入需设置管理员用户名与密码。
2. 依赖预安装：登录面板后进入「依赖管理」，点击「批量安装」，选择Python3、Node.js 16+、Shell等常用环境的基础依赖（如requests、axios），避免后续脚本因依赖缺失报错。
3. 安全配置：进入「系统设置」-「安全设置」，开启「登录验证码」，并修改默认端口5700为自定义端口（如5701），降低被扫描风险。

—

3. 定时任务创建与脚本管理实战

3.1 手动创建定时任务

以「每日凌晨2点备份服务器文件到阿里云OSS」为例：

1. 编写备份脚本：在宿主机的~/qinglong/scripts目录下创建oss_backup.py：

import os

import oss2

from datetime import datetime

阿里云OSS配置（替换为你的实际信息）

ACCESSKEYID = “你的AccessKeyId”

ACCESSKEYSECRET = “你的AccessKeySecret”

BUCKET_NAME = “你的Bucket名称”

ENDPOINT = “http://oss-cn-beijing.aliyuncs.com”

待备份文件路径与OSS存储路径

LOCALBACKUPFILE = “/root/data/backup.tar.gz”

OSSBACKUPPATH = f”serverbackup/{datetime.now().strftime(‘%Y%m%d%H%M%S’)}_backup.tar.gz”

执行备份

auth = oss2.Auth(ACCESSKEYID, ACCESSKEYSECRET)

bucket = oss2.Bucket(auth, ENDPOINT, BUCKET_NAME)

if os.path.exists(LOCALBACKUPFILE):

bucket.putobjectfromfile(OSSBACKUPPATH, LOCALBACKUP_FILE)

print(f”备份成功：{OSSBACKUPPATH}”)

else:

raise Exception(“备份文件不存在，请检查路径！”)

1. 创建定时任务：

• 进入青龙面板「任务管理」-「添加任务」

• 填写任务信息：

• 任务名称：服务器文件每日备份到OSS

• 命令：python3 /ql/scripts/oss_backup.py

• Cron表达式：0 2 *（每日凌晨2点执行）

• 备注：自动备份服务器核心数据

• 点击「确定」保存，可手动点击「运行」测试脚本是否正常执行。

3.2 通过脚本仓库批量导入任务

青龙面板支持一键拉取GitHub/Gitee上的开源脚本仓库，以拉取热门的faker2签到脚本仓库为例：

1. 进入「脚本管理」-「拉取脚本」
2. 输入仓库地址：https://github.com/shufflewzc/faker2.git
3. 选择分支：main，点击「确定」开始拉取
4. 拉取完成后进入「任务管理」，即可看到仓库中预设的定时任务，按需修改Cron表达式与配置参数即可使用。

3.3 脚本调试与日志排查

任务执行失败时，可通过「日志管理」查看详细报错信息：

• 若报错ModuleNotFoundError: No module named 'oss2'：进入「依赖管理」，添加Python依赖oss2，点击「安装」即可。

• 若报错Permission denied：在宿主机中给脚本添加执行权限：chmod +x ~/qinglong/scripts/oss_backup.py。

• 若报错Connection refused：检查服务器是否能访问阿里云OSS endpoint，可通过ping oss-cn-beijing.aliyuncs.com验证网络连通性。

—

4. 高级功能与优化配置

4.1 多渠道通知配置

青龙面板支持钉钉、企业微信、Telegram、Server酱等多渠道通知，任务执行成功/失败时自动推送告警：

1. 以钉钉通知为例：

• 进入钉钉开发者后台，创建自定义机器人，复制Webhook地址。

• 进入青龙面板「系统设置」-「通知设置」，选择「钉钉」，粘贴Webhook地址，开启「任务执行失败通知」与「任务执行成功通知」。

• 点击「测试通知」，若钉钉收到测试消息则配置成功。

4.2 面板HTTPS配置（Nginx反向代理）

为提升面板安全性，可通过Nginx配置HTTPS访问：

1. 安装Nginx：sudo apt install -y nginx
2. 编写Nginx配置文件/etc/nginx/conf.d/qinglong.conf：

server {

    listen 443 ssl;

    server_name your-domain.com;  # 替换为你的域名

# SSL证书配置（替换为你的证书路径）

ssl_certificate /etc/nginx/ssl/your-cert.pem;

sslcertificatekey /etc/nginx/ssl/your-key.key;

# 反向代理到青龙面板

location / {

proxy_pass http://127.0.0.1:5700;

proxysetheader Host $host;

proxysetheader X-Real-IP $remote_addr;

proxysetheader X-Forwarded-For $proxyaddxforwardedfor;

proxysetheader X-Forwarded-Proto $scheme;

}

}

强制HTTP跳转HTTPS

server {

listen 80;

server_name your-domain.com;

return 301 https://$servername$requesturi;

}

3. 重启Nginx：`sudo systemctl restart nginx`，即可通过`https://your-domain.com`访问青龙面板。

4.3 多容器隔离管理

若需同时运行不同类型的脚本（如签到脚本与运维脚本），可部署多个青龙面板容器，通过不同端口区分：

# 部署第二个青龙面板容器（端口5701）

docker run -dit \

  -v $PWD/ql2/config:/ql/config \

  -v $PWD/ql2/log:/ql/log \

  -p 5701:5700 \

  --name qinglong2 \

  --restart always \

  whyour/qinglong:latest

—

5. 常见问题排查与解决方案

| 问题现象 | 排查方向与解决方法 |

|———|——————-|

| 面板无法访问 | 1. 检查服务器防火墙是否开放端口：sudo ufw allow 5700（Ubuntu）；2. 检查容器是否运行：docker ps，若未运行则执行docker start qinglong；3. 检查端口是否被占用：netstat -tulpn | grep 5700 |

| 镜像拉取失败 | 1. 配置Docker国内镜像加速器；2. 检查服务器网络是否正常：ping github.com；3. 手动拉取镜像：docker pull whyour/qinglong:latest |

| 通知功能失效 | 1. 检查Webhook地址是否正确；2. 测试第三方服务连通性：ping api.dingtalk.com；3. 检查面板通知配置是否开启「任务执行通知」 |

| 脚本依赖安装失败 | 1. 检查服务器是否能访问PyPI/npm仓库：pip3 install requests；2. 手动进入容器安装依赖：docker exec -it qinglong bash，然后执行pip3 install oss2 |

—

总结

核心要点回顾

1. 环境准备优先选择Docker部署，确保Docker与Docker Compose安装正确，国内服务器建议配置镜像加速器；
2. 定时任务的核心是Cron表达式，需熟练掌握其时间规则，复杂任务可借助在线Cron表达式生成器验证；
3. 脚本管理需注意持久化目录的权限与路径，避免容器删除后数据丢失；
4. 高级功能中，通知配置可提升运维效率，HTTPS配置可增强面板安全性。

注意事项

• 安全防护：设置复杂的管理员密码，开启登录验证码，避免运行来源不明的脚本，防止服务器被入侵；

• 数据备份：定期备份青龙面板的config、scripts、db目录，可通过定时任务自动备份到云存储；

• 版本更新：定期拉取最新青龙面板镜像，更新容器：docker pull whyour/qinglong:latest && docker-compose restart。

青龙面板的核心价值是将复杂的定时任务管理可视化、标准化，通过合理配置，可大幅减少运维人员的重复劳动，实现脚本任务的自动化运行。