Docker 容器化部署 QINGLONG 面板指南

1,088次阅读

共计 6338 个字符，预计需要花费 16 分钟才能阅读完成。

概述

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 <<EOF | sudo tee /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

# 重启 Docker 服务使配置生效
sudo systemctl restart docker

镜像选择 ：若任务依赖较多系统库，建议使用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
- 脚本语法错误：根据日志提示修正脚本语法
- 环境变量缺失：检查任务依赖的环境变量是否已配置