🚀 使用 Docker Compose 部署 Qinglong 面板（定时任务管理工具）

🚀 使用 Docker Compose 部署青龙面板

本教程将指导您使用 Docker Compose 部署青龙面板（QingLong），这是一个功能强大的自动化任务管理平台，可以帮助您轻松管理和执行定时任务。

📝 项目简介

青龙面板是一个开源的可视化定时任务管理平台，支持多种脚本语言，通过友好的 Web 界面让用户能够轻松管理自动化任务。

核心特点：

多语言支持：支持 JavaScript、Python、Shell 等多种脚本语言
Web 可视化界面：通过浏览器即可轻松管理任务，无需命令行操作
灵活的任务调度：支持定时任务、手动执行等多种触发方式
强大的扩展能力：支持自定义环境变量、依赖管理，可灵活扩展功能
开源免费：基于 MIT 协议开源，完全免费使用

应用场景： - 自动化签到：各大网站、平台的自动签到领取积分 - 数据采集：自动抓取网页数据、商品信息、股票数据等 - 自动化运维：定时备份、清理文件等运维任务 - 自定义脚本：集中管理各种自定义脚本，方便维护和升级

🔧 部署前准备

系统环境要求

操作系统：支持 Linux、Windows、macOS 等主流操作系统
Docker 引擎：确保已安装 Docker 服务
Docker Compose：确保已安装 Docker Compose
硬件资源：
内存：至少 512MB（推荐 1GB 以上）
存储空间：至少 2GB 可用空间
CPU：1 核心以上

环境检查

检查 Docker 服务状态 bash systemctl status docker 确保 Docker 服务处于 active (running) 状态
检查 Docker 版本 bash docker -v 确保版本为 24.0 或更高
创建部署目录 bash mkdir -p /home/compose/qinglong && cd /home/compose/qinglong 此目录将作为您的工作目录，后续的配置文件都将放置于此

⚙️ 配置 Docker Compose

准备配置文件

在您的工作目录（例如 /home/compose/qinglong）下，创建以下配置文件：

创建 docker-compose.yml 文件

networks:
    1panel-network:
        external: true # 引用外部已创建的网络（必须提前执行 docker network create 命令）
services:
    qinglong:
        container_name: ${CONTAINER_NAME}  # 从 .env 读取容器名（默认 qinglong）
        deploy:
            resources:
                limits:
                    cpus: ${CPUS}  # 从 .env 读取 CPU 限制（默认 0，不限制）
                    memory: ${MEMORY_LIMIT}  # 从 .env 读取内存限制（默认 0，不限制）
        image: whyour/qinglong:2.19.2  # 固定使用 2.19.2 版本（稳定版，避免自动更新风险）
        labels:
            createdBy: Apps # 容器标签（用于 1Panel 识别，无实际功能）
        networks:
            - 1panel-network  # 加入外部网络，可与 1Panel 等应用通信
        ports:
            - ${HOST_IP}:${PANEL_APP_PORT_HTTP}:5700 # 端口映射：主机端口→容器 5700（从 .env 读取参数）
        restart: always # 容器退出后自动重启（保障服务稳定）
        volumes:
            - ./data:/ql/data # 核心数据持久化（任务、脚本、日志）
            #- /home/compose/Docsify/docs:/docs
            - ./docs:/docs    # 可选：挂载文档目录（存储脚本说明等）

创建 .env 环境配置文件

CONTAINER_NAME="qinglong"   # 容器名称
CPUS=0   # CPU 核心限制（0=不限制）
HOST_IP=""   # 绑定主机 IP（空=监听所有 IP）
MEMORY_LIMIT=0   # 内存限制（0=不限制）
PANEL_APP_PORT_HTTP=5700   # Web 界面端口（默认 5700，冲突时修改）

创建 data.yml 文件（如需要）

additionalProperties:
    formFields:
        - default: 5700
          edit: true
          envKey: PANEL_APP_PORT_HTTP
          labelEn: WebUI Port
          labelZh: 网页端口
          required: true
          rule: paramPort
          type: number

关键配置说明

网络配置：
使用外部网络 1panel-network，确保容器间通信
如网络不存在，需先创建：docker network create 1panel-network
端口映射：
${HOST_IP}:${PANEL_APP_PORT_HTTP}:5700：将容器的 5700 端口映射到宿主机的指定端口
可通过 .env 文件中的 PANEL_APP_PORT_HTTP 变量自定义宿主机端口
数据持久化：
./data:/ql/data：青龙面板的核心数据目录
./docs:/docs：文档目录，用于存放相关文档
资源限制：
CPUS：CPU 限制，0 表示无限制
MEMORY_LIMIT：内存限制，0 表示无限制
可根据实际需求调整这些参数
镜像版本：
whyour/qinglong:2.19.2：使用稳定的 2.19.2 版本
也可使用 whyour/qinglong:latest 获取最新版本

🚀 启动与验证

启动服务

在包含配置文件的目录下，执行以下命令启动服务：

docker compose up -d

参数 -d 表示在后台运行容器。

验证服务状态

检查容器运行状态 bash docker ps 应该看到名为 qinglong 的容器处于 Up 状态
查看服务日志 bash docker compose logs -f
访问 Web 界面 在浏览器中访问 http://你的服务器IP:5700（端口号以 .env 文件中 PANEL_APP_PORT_HTTP 的设置为准）

初始设置

首次访问会显示初始化界面： 1. 设置账号密码：填写管理员账号和密码 2. 跳过通知设置：初次使用可跳过通知配置，后续再设置 3. 完成安装：点击确认完成初始化设置

🔌 基础配置与使用

依赖管理

青龙面板需要安装相关依赖才能正常运行脚本：

配置镜像源（加速依赖下载）
Node.js 镜像源：https://registry.npmmirror.com/
Python 镜像源：https://pypi.tuna.tsinghua.edu.cn/simple/
安装 Node.js 依赖 bash crypto-js prettytable dotenv jsdom date-fns tough-cookie tslib ws@7.4.3 ts-md5 jsdom -g jieba fs form-data json5 global-agent png-js @types/node require typescript js-base64 axios moment ds
安装 Python 依赖 bash requests canvas ping3 jieba aiohttp

添加脚本仓库

通过添加脚本仓库，可以快速获取常用脚本：

通过定时任务添加仓库
进入"定时任务" → "创建任务"
填写任务名称和拉库命令
设置定时规则（如每天 0 点执行：0 0 * * *）
常用仓库示例 bash # Faker 仓库 ql repo https://ghproxy.com/https://github.com/shufflewzc/faker2.git "jd_|jx_|gua_|jddj_|getJDCookie" "activity|backUp" "^jd[^_]|USER|ZooFaker_Necklace.js|JDJRValidator_Pure|sign_graphics_validate"
通过订阅管理添加仓库
进入"订阅管理" → "创建订阅"
输入仓库地址（如：https://github.com/ximalaay/script.git）

环境变量配置

为脚本设置必要的环境变量：

创建环境变量
进入"环境变量" → "创建变量"
输入变量名称和值
例如：JD_COOKIE 用于存储京东签到所需的 Cookie
多账号支持
多个账号只需创建多个同名环境变量即可

🛠️ 维护与管理

日常维护操作

服务启动/停止 ```bash # 停止服务 docker compose down

# 启动服务 docker compose up -d

# 重启服务 docker compose restart ```

数据备份 bash # 备份数据目录 tar -czf qinglong-backup-$(date +%Y%m%d).tar.gz ./data
服务更新 ```bash # 进入部署目录 cd /home/compose/qinglong

# 拉取最新镜像（如需更新版本） docker compose pull

# 重启服务 docker compose down docker compose up -d ```

常用 Docker 命令

命令	说明
`docker exec -it qinglong ql update`	更新青龙面板
`docker exec -it qinglong ql check`	检测青龙环境并修复
`docker exec -it qinglong ql rmlog 7`	删除 7 天前的所有日志
`docker exec -it qinglong task test.js now`	立即执行脚本
`docker exec -it qinglong task test.js conc`	并行执行脚本

监控与日志

查看实时日志 bash docker compose logs -f
查看青龙面板日志
通过青龙面板 Web 界面的"日志"功能查看任务执行日志
或查看容器内的 /ql/data/log 目录
监控资源使用 bash docker stats qinglong

🐛 常见问题排查

1. 容器启动失败

问题现象：docker ps 显示容器状态不是 Up

解决方案： - 检查日志：docker compose logs - 验证端口占用：netstat -tulpn | grep 5700 - 检查网络配置：确保 1panel-network 存在，或修改为其他网络

2. 无法访问 Web 界面

问题现象：浏览器访问 http://IP:5700 无响应

解决方案： - 检查防火墙设置： bash # 开放对应端口（以 5700 为例） ufw allow 5700 - 验证服务绑定：确保服务绑定到 0.0.0.0 而不是 127.0.0.1 - 检查 .env 文件中的端口配置

3. 依赖安装失败

问题现象：脚本执行失败，提示依赖缺失

解决方案： - 配置国内镜像源加速下载 - 手动安装缺失的依赖包 - 检查网络连接，确保可以访问依赖源

4. 脚本执行失败

问题现象：任务执行失败，日志显示错误

解决方案： - 检查环境变量配置是否正确 - 验证脚本语法和兼容性 - 查看详细日志定位具体错误

5. 忘记管理员密码

解决方案：

# 查看容器中的认证文件
docker exec -it qinglong cat /ql/data/config/auth.json

通过本教程，您应该已经成功部署并配置了青龙面板，现在可以开始添加自动化任务，享受自动化带来的便利了。如果在使用过程中遇到其他问题，可以参考项目官方文档或社区支持资源。