青龙面板搭建教程：Docker 一键部署定时任务管理平台

什么是青龙面板

青龙面板（Qinglong Panel）是一款开源的定时任务管理平台，由开发者 whyour 维护，项目托管在 GitHub 上。它提供了一个简洁直观的 Web 可视化界面，让你可以方便地管理和调度各种自动化脚本。

青龙面板支持以下 4 种脚本语言：

• Python3：适合数据处理、爬虫类任务
• JavaScript（Node.js）：适合网页自动化和签到类任务
• Shell：适合系统运维和批量操作
• TypeScript：适合类型安全要求较高的复杂脚本

核心特性包括：

• 支持在线编辑和管理脚本文件
• 支持 Cron 表达式灵活配置定时规则，精确到秒级
• 支持通过订阅自动从 GitHub 等代码仓库拉取并更新脚本
• 支持环境变量管理，方便统一维护 Cookie 等敏感信息
• 内置依赖管理功能，可直接在面板中安装 Node.js 和 Python 的第三方包
• 提供完善的任务执行日志，便于排查问题
• 支持暗黑模式和手机端访问

环境准备

在开始搭建之前，你需要准备以下环境：

如果你的服务器尚未安装 Docker，可以使用一键安装脚本：

curl -fsSL https://get.docker.com | sh

安装完成后，启动 Docker 并设置开机自启：

sudo systemctl start docker
sudo systemctl enable docker

验证 Docker 是否安装成功：

docker --version

Docker 一键部署青龙面板

方式一：Docker 命令直接部署

首先拉取青龙面板的最新镜像：

docker pull whyour/qinglong:latest

然后执行以下命令启动容器：

docker run -dit \
  -v $PWD/ql/data:/ql/data \
  -p 5700:5700 \
  -e QlBaseUrl="/" \
  -e QlPort="5700" \
  --name qinglong \
  --hostname qinglong \
  --restart unless-stopped \
  whyour/qinglong:latest

参数说明：

注意：新版青龙面板（v2.12 及以上）将所有数据统一存储在 /ql/data 目录下，不再需要分别挂载 config、log、db、scripts 等多个目录。如果你在网上看到挂载多个目录的教程，那可能是针对旧版本的。

方式二：Docker Compose 部署（推荐）

使用 Docker Compose 管理容器更加方便，尤其是后续需要更新版本的时候。

先创建一个工作目录：

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

创建 docker-compose.yml 文件：

version: '2'
services:
  qinglong:
    image: whyour/qinglong:latest
    container_name: qinglong
    hostname: qinglong
    volumes:
      - ./data:/ql/data
    ports:
      - "5700:5700"
    environment:
      QlBaseUrl: '/'
      QlPort: '5700'
    restart: unless-stopped

启动容器：

docker-compose up -d

提示：如果你的服务器是 ARM 架构（比如树莓派或 M 系列 Mac），青龙面板同样支持，镜像会自动适配。如果遇到兼容性问题，可以尝试使用 whyour/qinglong:debian 镜像。

访问面板与初始化配置

容器启动后，在浏览器中访问：

http://你的服务器IP:5700

首次访问会进入初始化引导页面，按照提示完成以下步骤：

1. 设置管理员账号：输入你想要的用户名和密码
2. 配置通知渠道（可选）：支持 Telegram、钉钉、企业微信、Server 酱等多种通知方式
3. 点击完成即可进入面板主界面

如果忘记了管理员密码，可以通过以下命令重置：

# 查看当前账号信息
docker exec -it qinglong cat /ql/data/config/auth.json

# 重置登录限制（登录失败次数过多时使用）
docker exec -it qinglong ql resetlet

青龙面板核心功能详解

添加订阅（自动拉取脚本）

订阅功能是青龙面板最实用的特性之一。通过订阅，面板会定时从指定的 GitHub 仓库拉取脚本，并自动创建对应的定时任务。

操作步骤：

1. 进入面板左侧菜单的「订阅管理」

2. 点击右上角的「新建订阅」

3. 填写订阅信息：

   • 名称：给订阅起一个方便识别的名字
   • 类型：选择「公开仓库」
   • 链接：填写仓库地址，例如 https://github.com/用户名/仓库名.git
   • 定时规则：设置自动更新频率，如 0 0 * * * 表示每天凌晨更新一次
   • 白名单 / 黑名单：可选，用于过滤需要或不需要的脚本文件

4. 保存后建议先手动点击「运行」，让面板首次拉取脚本并创建定时任务

订阅成功后，面板会根据设定的频率定时拉取仓库更新，并自动维护对应的定时任务列表。

手动添加定时任务

除了通过订阅自动创建，你也可以手动添加定时任务：

1. 进入「定时任务」页面
2. 点击「新建任务」
3. 填写以下信息：
   • 名称：任务描述
   • 命令：要执行的脚本命令，如 task scripts/example.js
   • 定时规则：Cron 表达式，如 30 8 * * * 表示每天早上 8:30 执行

Cron 表达式速查表：

环境变量管理

很多脚本需要用到 Cookie 或 Token 等凭据信息。青龙面板提供了专门的「环境变量」管理功能：

1. 进入「环境变量」页面
2. 点击「新建变量」
3. 填写变量名和变量值

例如，某个签到脚本需要名为 MY_COOKIE 的环境变量，只需在面板中添加即可，脚本运行时会自动读取。

安全提示：Cookie 和 Token 属于敏感信息，不要在公开场合分享。另外，Cookie 通常有有效期，过期后需要及时更新。

依赖管理

脚本运行时如果报错 Cannot find module 'xxx' 或者 ModuleNotFoundError: No module named 'xxx'，说明缺少对应的依赖包。

青龙面板内置了可视化的依赖管理功能，无需手动进入容器安装：

1. 进入「依赖管理」页面
2. 点击「新建依赖」
3. 选择依赖类型（Node.js / Python3 / Linux）
4. 「自动拆分」选择「是」
5. 在名称栏输入需要安装的包名，多个包用换行分隔

常用 Node.js 依赖：

crypto-js
dotenv
jsdom
date-fns
tough-cookie
ts-md5
axios

常用 Python3 依赖：

requests
PyExecJS

也可以通过命令行手动安装依赖：

# 安装 Node.js 依赖
docker exec -it qinglong pnpm install axios

# 安装 Python3 依赖
docker exec -it qinglong pip3 install requests

如何获取网站 Cookie

大多数自动化脚本都需要用到目标网站的 Cookie 来模拟登录状态。以下介绍两种获取方式。

电脑端获取 Cookie

1. 打开 Chrome 或 Edge 浏览器，访问目标网站并完成登录
2. 按 F12 打开开发者工具（DevTools）
3. 切换到「Network」（网络）标签页
4. 刷新页面，点击第一个网络请求
5. 在右侧的「Headers」中找到 Cookie 字段，复制完整的值

手机端获取 Cookie

安卓手机推荐使用 Alook 浏览器，操作步骤：

1. 安装并打开 Alook 浏览器
2. 进入目标网站，使用手机号完成登录
3. 关闭浏览器自带的广告过滤功能
4. 向右滑动底部工具栏，找到「工具箱」
5. 进入「开发者工具」，点击「Cookies」即可查看和复制

实用脚本配置示例

以下是一些常见的自动化脚本配置方法，仅供参考。请注意，第三方脚本仓库可能随时失效或发生变化，使用前请自行确认脚本来源的可靠性。

阿里云盘自动签到

阿里云盘支持每日签到领取额外存储空间，利用青龙面板可以实现全自动签到。

第 1 步：添加订阅

在「订阅管理」中新建订阅，填写以下仓库地址：

https://github.com/mrabit/aliyundriveDailyCheck.git

白名单填写 autoSignin，扩展脚本填写 qlApi，定时规则建议设为 0 0 * * *（每天凌晨执行）。

第 2 步：获取 refresh_token

1. 在浏览器中登录 阿里云盘
2. 按 F12 打开开发者工具，进入 Console（控制台）
3. 粘贴以下代码并回车：

JSON.parse(localStorage.token).refresh_token

4. 复制输出的 token 值

第 3 步：添加环境变量

在「环境变量」中新建变量：

第 4 步：安装依赖

进入「依赖管理」 → 「Node.js」 → 新建依赖，名称填写 axios。

第 5 步：运行测试

在「定时任务」中找到自动创建的签到任务，手动运行一次，查看日志确认是否执行成功。

哔哩哔哩自动任务

BiliBiliToolPro 是一个功能丰富的 B 站自动化工具，支持每日经验任务、投币、直播签到等。

项目地址：RayWangQvQ/BiliBiliToolPro

具体的配置方式请参考项目仓库中 qinglong 目录下的说明文档，按照文档指引添加订阅和配置环境变量即可。

青龙面板版本更新与维护

保持青龙面板为最新版本可以获得更好的稳定性和安全性。

Docker 命令方式更新：

# 停止并移除旧容器
docker stop qinglong
docker rm qinglong

# 拉取最新镜像
docker pull whyour/qinglong:latest

# 重新启动容器（使用与部署时相同的命令）
docker run -dit \
  -v $PWD/ql/data:/ql/data \
  -p 5700:5700 \
  -e QlBaseUrl="/" \
  -e QlPort="5700" \
  --name qinglong \
  --hostname qinglong \
  --restart unless-stopped \
  whyour/qinglong:latest

Docker Compose 方式更新：

cd ~/qinglong
docker-compose down
docker-compose pull
docker-compose up -d

提醒：由于数据目录已挂载到宿主机，更新容器不会丢失你的脚本、配置和任务数据。

常见问题

Q1：访问 5700 端口显示无法连接？

首先确认容器是否正常运行：

docker ps | grep qinglong

如果容器已启动但无法访问，检查以下几点：

• 服务器防火墙是否放行了 5700 端口
• 云服务器的安全组规则是否允许 5700 端口入方向流量
• 如果使用了宝塔面板，确保在宝塔的安全设置中也放行了该端口

Q2：脚本运行报错 Cannot find module 'xxx'？

这是缺少 Node.js 依赖导致的。有两种解决方式：

• 方式一：在面板的「依赖管理」→「Node.js」中搜索并安装对应的包
• 方式二：通过命令行安装

docker exec -it qinglong pnpm install xxx

Q3：Python 脚本报错 ModuleNotFoundError: No module named 'xxx'？

类似于 Node.js 依赖问题，在面板的「依赖管理」→「Python3」中安装对应的模块，或通过命令行：

docker exec -it qinglong pip3 install xxx

Q4：登录失败次数过多被锁定了怎么办？

在服务器终端执行以下命令重置登录限制：

docker exec -it qinglong ql resetlet

Q5：面板页面出现白屏或 502 错误？

可能是容器内部服务尚未完全启动，稍等片刻后刷新页面。如果持续出现问题：

# 查看容器日志排查原因
docker logs qinglong --tail 50

# 尝试重启容器
docker restart qinglong

Q6：订阅拉取脚本失败？

常见原因：

• 仓库地址不正确或仓库已被删除
• 服务器无法访问 GitHub（国内服务器可能需要配置代理或使用镜像源）
• 白名单 / 黑名单配置有误，导致没有匹配到任何脚本文件

Q7：如何备份青龙面板的数据？

青龙面板的所有数据都在挂载的 data 目录中，直接备份这个目录即可：

tar -czf qinglong-backup-$(date +%Y%m%d).tar.gz ./ql/data

Q8：Cookie 多久需要更新一次？

不同网站的 Cookie 有效期不同，一般从几天到几个月不等。当脚本日志中出现「Cookie 已失效」或类似提示时，就需要重新获取并更新环境变量中的 Cookie 值了。

总结

青龙面板凭借简洁的 Web 界面和强大的定时任务管理能力，已经成为自动化脚本管理的主流工具之一。通过本文的介绍，相信你已经掌握了从 Docker 部署到日常使用的完整流程。

回顾一下核心要点：

1. 部署方面：推荐使用 Docker Compose 方式，方便后续的版本更新和维护
2. 数据持久化：务必通过 -v 参数挂载数据目录，防止容器重建时丢失数据
3. 依赖管理：善用面板内置的依赖管理功能，遇到模块缺失问题可以快速解决
4. 安全意识：Cookie 和 Token 等敏感信息要妥善保管，定期检查是否失效
5. 脚本来源：使用第三方脚本前请仔细审查代码，确保来源可靠

如果你在搭建或使用青龙面板的过程中遇到任何问题，欢迎在评论区留言交流，也可以前往 GitHub Issues 查看是否已有相关解答。希望这篇教程对你有所帮助！