青龙备份 Docker 镜像文档

镜像概述

青龙备份镜像旨在为青龙面板用户提供自动化、智能化的数据备份解决方案。青龙面板作为常用的定时任务管理工具，其配置、任务及依赖环境数据至关重要。本镜像通过容器化方式，实现对青龙面板核心数据的定时备份、存储管理及过期清理，解决手动备份繁琐、易遗漏的问题，确保数据安全与业务连续性。

核心功能与特性

1. 定时自动备份

• 基于Cron表达式配置备份周期，支持自定义备份频率（如每日、每周、每月）
• 备份触发精准可靠，无需人工干预

2. 多维度数据备份

• 全面覆盖青龙面板核心数据：
  • 面板配置文件（configs目录）
  • 定时任务数据（db目录下数据库文件）
  • 依赖环境与脚本（scripts、repo目录）
  • 容器元数据（可选，需额外配置）

3. 灵活存储与清理策略

• 支持本地目录挂载存储备份文件
• 可选集成远程存储（如S3兼容对象存储、FTP/SFTP，需额外配置环境变量）
• 自动清理过期备份：按保留天数或备份文件数量策略删除旧备份，释放存储空间

4. 备份可靠性保障

• 备份前数据完整性校验，避免损坏文件备份
• 详细日志记录：备份过程、结果及异常信息，便于问题排查
• 备份文件压缩（.tar.gz格式），减少存储空间占用

使用场景

• 个人/家庭青龙面板用户：自动备份避免因系统故障、误操作导致的任务配置丢失
• 多用户管理的青龙面板：保障多人协作场景下的任务数据一致性与可恢复性
• 重要业务依赖的青龙面板：如电商抢购、数据采集等核心任务，通过定时备份降低业务中断风险
• 青龙面板迁移/升级：备份数据可直接用于新环境部署，简化迁移流程

使用方法

前提条件

• 已部署青龙面板容器，且数据目录可通过宿主机路径访问（通常为青龙容器挂载的/ql目录）
• Docker环境版本≥20.10.0，支持容器间数据卷共享或宿主机目录挂载

快速启动（docker run）

bash
docker run -d \
  --name qinglong-backup \
  --restart always \
  -v /path/to/qinglong/data:/ql:ro \  # 只读挂载青龙面板数据目录
  -v /path/to/backup/storage:/backup  # 挂载备份存储目录
  -e BACKUP_CRON="0 3 * * *" \        # 每日凌晨3点执行备份
  -e RETENTION_DAYS=7 \               # 保留最近7天备份
  -e TZ=Asia/Shanghai \               # 设置时区（确保Cron时间准确）
  whyour/qinglong-backup:latest       # 镜像名称（请替换为实际镜像地址）

Docker Compose 配置

yaml
version: '3'
services:
  qinglong-backup:
    image: whyour/qinglong-backup:latest
    container_name: qinglong-backup
    restart: always
    volumes:
      - /path/to/qinglong/data:/ql:ro  # 青龙面板数据目录（需与青龙容器挂载路径一致）
      - /path/to/backup/storage:/backup  # 备份文件存储目录
    environment:
      - BACKUP_CRON=0 3 * * *  # Cron表达式，每日3点备份
      - BACKUP_DIR=/backup     # 容器内备份存储路径（需与挂载目录对应）
      - QINGLONG_DIR=/ql       # 容器内青龙面板数据目录（需与挂载目录对应）
      - RETENTION_DAYS=7       # 备份文件保留天数
      - COMPRESS_LEVEL=6       # 压缩级别（1-9，1最快，9压缩率最高）
      - TZ=Asia/Shanghai       # 时区设置
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

数据恢复方法

1. 停止青龙面板容器：

   bash
   docker stop qinglong
   

2. 从备份文件恢复（假设备份文件为qinglong_backup_20240520.tar.gz）：

   bash
   # 解压备份文件至青龙数据目录
   tar -zxvf /path/to/backup/storage/qinglong_backup_20240520.tar.gz -C /path/to/qinglong/data
   

3. 启动青龙面板容器：

   bash
   docker start qinglong
   

配置参数详解

核心环境变量

高级配置（远程存储，可选）

若需将备份文件同步至远程存储（如S3兼容对象存储），需额外配置以下环境变量：

注意事项

1. 数据目录挂载权限：青龙面板数据目录需以只读（ro）方式挂载至备份容器，避免备份过程中数据写入冲突
2. Cron表达式格式：请确保BACKUP_CRON符合标准Cron格式（分 时 日 月 周），可通过Cron表达式生成工具验证
3. 备份文件命名规则：备份文件名称格式为${BACKUP_PREFIX}_YYYYMMDD_HHMMSS.tar.gz，便于时间追溯
4. 远程存储依赖：启用远程存储时，需确保容器网络可访问远程服务，且密钥权限包含上传/删除文件权限
5. 日志查看：通过docker logs qinglong-backup查看备份过程日志，排查备份失败原因

常见问题

• Q：备份文件体积过大？
  A：可提高COMPRESS_LEVEL（如设为9），或通过RETENTION_DAYS减少保留份数，或排除非必要目录（需通过EXCLUDE_DIRS环境变量配置，如EXCLUDE_DIRS=/ql/logs）。

• Q：Cron定时未触发备份？
  A：检查TZ时区配置是否正确，确保与宿主机时区一致；通过日志确认Cron服务是否正常运行。

• Q：恢复后青龙面板无法启动？
  A：确认备份文件解压路径与青龙面板数据目录完全一致，且文件权限（如属主、读写权限）与原目录匹配。