当前位置：

文章详情

Docker 容器化部署 QINGLONG 面板指南

概述

QINGLONG（中文名称：青龙）是一款支持多脚本语言的定时任务管理面板，具备脚本在线管理、环境变量配置、任务日志查看、系统级通知等核心功能。该工具支持Python3、JavaScript、Shell、TypeScript等多种脚本语言，提供深色模式和移动端操作支持，适用于需要自动化任务调度的场景。

本文档提供基于Docker容器化技术的QINGLONG部署方案，通过容器化部署可实现环境隔离、快速迁移和版本控制，简化部署流程并提高系统可靠性。

环境准备

Docker环境安装

QINGLONG采用Docker容器化部署，需先确保服务器已安装Docker环境。推荐使用以下一键安装脚本：

# 一键安装Docker环境（支持主流Linux发行版） bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

脚本执行过程中需根据提示完成权限配置，安装完成后可通过以下命令验证Docker状态：

# 验证Docker服务状态 systemctl status docker # 验证Docker版本信息 docker --version

镜像准备

镜像信息确认

QINGLONG官方Docker镜像信息如下：

镜像名称：whyour/qinglong
推荐标签：latest（基于Alpine构建）、debian（基于Debian-slim构建，适用于需要特定依赖的场景）
镜像文档：QINGLONG部署文档
标签列表：QINGLONG镜像标签

镜像拉取命令

使用轩辕镜像加速地址拉取命令如下：

# 拉取最新稳定版（Alpine基础镜像） docker pull docker.xuanyuan.me/whyour/qinglong:latest # 如需使用Debian基础镜像（适用于依赖Alpine不支持的场景） docker pull docker.xuanyuan.me/whyour/qinglong:debian

说明：若需要特定版本，可将latest替换为具体版本标签，如v2.15.0，版本列表可参考QINGLONG镜像标签。

镜像验证

拉取完成后，通过以下命令验证镜像信息：

# 查看本地镜像列表 docker images | grep whyour/qinglong # 输出示例（版本号可能不同）： # docker.xuanyuan.me/whyour/qinglong latest abc12345 2 weeks ago 500MB

容器部署

基础部署（单容器模式）

推荐使用以下命令部署QINGLONG容器，包含数据持久化、端口映射和基础配置：

# 创建数据目录（用于持久化存储配置和任务数据） mkdir -p $PWD/ql/data # 启动QINGLONG容器 docker run -dit --name qinglong # 容器名称 --hostname qinglong # 容器主机名 --restart unless-stopped # 重启策略：异常退出时自动重启 -v $PWD/ql/data:/ql/data # 挂载数据卷（持久化配置和任务数据） -p 5700:5700 # 端口映射（主机端口:容器端口，默认5700） -e QlBaseUrl="/" # 基础路径（默认为"/"，子路径部署时需修改） -e QlPort="5700" # 服务端口（需与容器端口保持一致） docker.xuanyuan.me/whyour/qinglong:latest # 镜像地址及标签

参数说明：
-v $PWD/ql/data:/ql/data：数据卷挂载，确保容器重启后配置、任务和日志不丢失
-p 5700:5700：默认端口映射，若服务器5700端口已被占用，可修改主机端口（如8080:5700）
--restart unless-stopped：确保服务异常退出后自动恢复，提高可用性

高级部署（自定义配置）

根据实际需求，可添加以下环境变量和配置参数：

docker run -dit --name qinglong --hostname qinglong --restart unless-stopped -v $PWD/ql/data:/ql/data -v $PWD/ql/scripts:/ql/scripts # 额外挂载自定义脚本目录 -p 5700:5700 -e QlBaseUrl="/" -e QlPort="5700" -e QlConfig="/ql/data/config/config.js" # 配置文件路径 -e TZ="Asia/Shanghai" # 设置时区（默认可能为UTC，建议显式指定） -e LANG="zh_CN.UTF-8" # 设置语言编码 --memory 2g # 内存限制（根据服务器配置调整） --cpus 1 # CPU核心限制 docker.xuanyuan.me/whyour/qinglong:latest

Docker Compose部署（推荐生产环境）

对于多容器协同或更复杂的部署场景，推荐使用Docker Compose管理服务。

1. 安装Docker Compose

# 安装Docker Compose（适用于Linux x86_64架构） curl -L "https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose # 添加执行权限 chmod +x /usr/local/bin/docker-compose # 验证安装 docker-compose --version

2. 创建docker-compose.yml文件

version: '3.8' services: qinglong: image: docker.xuanyuan.me/whyour/qinglong:latest container_name: qinglong hostname: qinglong restart: unless-stopped volumes: - ./ql/data:/ql/data # 可选：挂载自定义脚本目录 # - ./ql/scripts:/ql/scripts ports: - "5700:5700" environment: - QlBaseUrl="/" - QlPort="5700" - TZ="Asia/Shanghai" - LANG="zh_CN.UTF-8" # 可选：资源限制 deploy: resources: limits: cpus: '1' memory: 2G

3. 启动服务

# 在docker-compose.yml所在目录执行 docker-compose up -d # 查看服务状态 docker-compose ps # 查看日志 docker-compose logs -f

功能测试

服务访问验证

容器启动后（约30秒初始化时间），通过以下方式访问QINGLONG管理界面：

http://服务器IP:5700

首次访问需完成初始化配置，根据页面提示设置管理员账号密码。

核心功能测试

1. 任务管理测试

登录管理界面后，进入「任务管理」模块
点击「新建任务」，配置以下参数：
- 任务名称：测试任务
- 命令类型：Shell
- 执行命令：echo "Hello QINGLONG" u0026u0026 date
- 定时规则：*/1 * * * *（每分钟执行一次）
保存任务并手动触发执行，查看日志输出是否正常

2. 脚本管理测试

进入「脚本管理」模块，点击「新建脚本」
输入脚本名称（如test.js），选择JavaScript类型
输入测试代码：
console.log("QINGLONG JavaScript测试脚本"); console.log("当前时间：", new Date().toLocaleString());
保存脚本后，创建任务执行该脚本，验证脚本运行正常

3. 环境变量配置测试

进入「环境变量」模块，点击「新增变量」
设置变量名：TEST_ENV，变量值：Hello World
创建测试任务，执行命令：echo $TEST_ENV
查看任务日志，确认环境变量生效（输出Hello World）

服务可用性验证

# 检查容器运行状态 docker inspect -f '{{.State.Status}}' qinglong # 输出应为"running"，表示容器正常运行 # 检查端口监听状态 netstat -tuln | grep 5700 # 输出示例（表示5700端口已正常监听）： # tcp6 0 0 :::5700 :::* LISTEN

生产环境建议

数据备份策略

QINGLONG的核心数据存储在/ql/data目录，建议配置定期备份：

# 创建备份脚本（backup_ql.sh） #!/bin/bash BACKUP_DIR="/var/backups/qinglong" TIMESTAMP=$(date +%Y%m%d_%H%M%S) mkdir -p $BACKUP_DIR # 备份数据目录 tar -zcvf $BACKUP_DIR/ql_data_$TIMESTAMP.tar.gz -C $(dirname $PWD/ql/data) $(basename $PWD/ql/data) # 保留最近30天备份 find $BACKUP_DIR -name "ql_data_*.tar.gz" -mtime +30 -delete

添加执行权限并配置定时任务：

# 添加执行权限 chmod +x backup_ql.sh # 配置每日凌晨3点自动备份 crontab -e # 添加以下内容 0 3 * * * /path/to/backup_ql.sh

安全加固措施

端口安全：生产环境建议通过反向代理（如Nginx）访问QINGLONG，避免直接暴露端口，并配置HTTPS加密传输：

# Nginx配置示例 server { listen 443 ssl; server_name qinglong.example.com; # 替换为实际域名 ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://127.0.0.1:5700; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

权限控制：限制数据目录权限，避免容器内权限溢出：

# 设置数据目录权限（仅当前用户可写） chmod 700 $PWD/ql/data

密码策略：配置强密码并定期更换，启用两步验证（在QINGLONG管理界面「系统设置」中开启）。

性能优化建议

资源配置：根据任务数量调整容器资源限制，建议最低配置：
- CPU：1核
- 内存：1GB
- 磁盘：10GB（SSD推荐，提升IO性能）
日志轮转：配置Docker日志轮转，避免日志文件占用过多磁盘空间：

# 创建Docker日志配置文件 sudo mkdir -p /etc/docker cat <

镜像选择：若任务依赖较多系统库，建议使用debian标签镜像（whyour/qinglong:debian），避免Alpine系统的依赖兼容性问题。

故障排查

容器启动失败

问题现象

执行docker run后容器未正常启动，通过docker ps查看无运行中的qinglong容器。

排查步骤

查看启动日志：
docker logs qinglong
常见原因及解决方法：
- 端口冲突：日志中出现bind: address already in use，需修改主机端口映射（如-p 5701:5700）
- 数据卷权限：日志中出现permission denied，需检查数据目录权限：
  # 修复目录权限 chown -R 1000:1000 $PWD/ql/data # 假设容器内运行用户ID为1000
- 镜像损坏：尝试重新拉取镜像：
  docker pull docker.xuanyuan.me/whyour/qinglong:latest

服务访问异常

问题现象

容器状态正常，但无法通过浏览器访问管理界面。

排查步骤

网络连通性检查：
# 检查服务器本地访问 curl http://127.0.0.1:5700 # 检查防火墙规则 firewall-cmd --list-ports # 查看开放端口（CentOS） ufw status # 查看防火墙状态（Ubuntu）
容器网络检查：
# 查看容器IP docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' qinglong # 进入容器测试服务状态 docker exec -it qinglong curl http://localhost:5700
配置检查：确认QlPort环境变量与端口映射一致，基础路径QlBaseUrl配置正确。

任务执行失败

问题现象

任务状态显示失败，日志中出现错误信息。

排查步骤

查看详细日志：在管理界面「任务管理」中点击任务「日志」按钮，查看具体错误信息。
常见原因及解决方法：
- 依赖缺失：日志中出现command not found，需在容器内安装依赖：
  # 进入容器 docker exec -it qinglong /bin/sh # Alpine系统安装依赖（以curl为例） apk add --no-cache curl # Debian系统安装依赖 apt update u0026u0026 apt install -y curl
- 脚本语法错误：根据日志提示修正脚本语法
- 环境变量缺失：检查任务依赖的环境变量是否已配置