青龙面板Docker版本升级：解决重启后回退旧版本的完整教程

青龙面板Docker版本升级：解决重启后回退旧版本的完整教程

【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台（Timed task management platform supporting Python3, JavaScript, Shell, Typescript）项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong

青龙面板 Docker 版本升级中最常见的卡点：你在面板里点了更新（或执行了ql update），界面提示成功，可容器一重启，登录进去版本号又变回了旧的。根源在于青龙的程序代码装在容器内部，只有挂载到/ql/data的数据目录是持久的；面板更新改的是容器里的代码，容器重建后代码就回到镜像里的老版本。按本文步骤操作，你会完成一次不丢脚本、不丢配置的版本升级，并掌握升级失败时的回退方法。

📋 动手前自查：确认你的处境

开始之前，花两分钟确认四条，后文的命令才能对上号：

• 容器在运行：docker ps能看到你的青龙容器，5700端口已映射（默认 Web 端口）。
• 数据目录已挂载：部署时把宿主机某个目录挂到了容器内/ql/data，配置、脚本、日志、数据库全在这个目录下（项目里 docker-compose.yml 的写法是./data:/ql/data）。
• 症状符合：更新后版本号不变，或容器重启/重建后回退到旧版本。
• 网络可用：宿主机能正常docker pull镜像，否则会卡在第 3 步。

🚀 主路径：更换镜像升级（推荐）

思路一句话：拉最新镜像、删旧容器、用同一个数据目录重建容器。数据在挂载目录里，全程不会丢。

第 1 步：记下当前版本号，升级后用来对比。

docker exec qinglong cat /ql/version.yaml

输出形如version: 2.21.0，仓库里这个文件就是版本号的唯一来源（version.yaml）。

第 2 步：备份数据目录。升级前留一份快照，出问题才回得去。

# 把宿主机上挂载给 /ql/data 的目录完整复制一份（-a 保留权限） cp -a ./data ./data_backup_$(date +%Y%m%d)

第 3 步：停止并删除旧容器。删除容器不会删除挂载在外的数据目录，放心执行。

docker stop qinglong docker rm qinglong

第 4 步：拉取最新镜像。latest是最新版标签；如果你之前用的是 Debian 基础版，请拉whyour/qinglong:debian。

docker pull whyour/qinglong:latest

第 5 步：用原参数重建容器。关键是-v必须指向原来的数据目录，端口和容器名保持一致。

docker run -dit \ --name qinglong \ -p 5700:5700 \ -v $PWD/data:/ql/data \ # 挂载原来的数据目录，脚本和配置都在里面 --restart unless-stopped \ whyour/qinglong:latest

启动完成后，容器启动脚本会自动检测/ql/data权限、加载配置并把后台服务拉起，看到日志里出现「容器启动成功」即可。

🔄 备选路径

只想临时体验新版本：容器内ql update

适用场景：不想动镜像，先试新版本功能。代价是这次更新的代码只存在于当前容器，容器重建后会回到镜像版本，适合"先试后升"，不适合当正式升级手段。

docker exec -it qinglong ql update

这条命令会自动下载新版本源码并重启内部服务，不用你停容器。执行完刷新面板，确认版本号和任务都正常，再按主路径正式升级镜像。

拿不准升级结果：先给当前容器拍快照

适用场景：大版本跨越，担心升级后回不去。docker commit会把容器当前的代码和系统状态存成镜像，升级后出问题可以直接从快照恢复。

docker commit qinglong qinglong_backup:$(date +%Y%m%d)

需要回退时，删掉新容器后用快照镜像原参数重建即可：

docker run -dit --name qinglong -p 5700:5700 -v $PWD/data:/ql/data qinglong_backup:20260906

🔍 验证结果：确认升级真的生效

逐条执行，全部通过才算升级完成：

1. 版本号变了：docker exec qinglong cat /ql/version.yaml输出的版本比升级前新；同时登录面板，「设置 → 关于」里显示的版本号一致。
2. 服务是健康的：curl http://127.0.0.1:5700/api/health返回正常状态（镜像内置的健康检查探测的正是这个接口）；docker ps里容器状态是Up，而不是反复Restarting。
3. 数据完整：用原来的账号密码登录成功；任务列表、订阅、脚本数量与升级前一致；ls data/scripts能看到脚本文件仍在。
4. 任务能跑：在面板里手动执行一个已有任务，日志页显示执行完成，没有依赖报错。

⚠️ 常见报错自救

报错 1：容器起不来，日志打印「权限错误：无法写入 /ql 目录」或「无法写入 /ql/data (Volume 挂载点)」。

• 原因：容器内进程的用户 UID 和宿主机数据目录属主不匹配。启动脚本（docker-entrypoint.sh）会先做写权限检测，检测不过直接退出。
• 处理：日志里会打印当前 UID 和目录属主 UID，按提示在宿主机把数据目录属主改成日志中的 UID，例如chown -R <日志中的UID>:$PWD/data后重启容器；或按日志提示用--user指定镜像内置用户。

报错 2：重建容器后版本号没变，还是旧版。

• 原因：docker run用了本地缓存的旧镜像，即拉取失败被忽略了。
• 处理：重新docker pull whyour/qinglong:latest，然后docker images whyour/qinglong核对 IMAGE ID 是否更新，删容器后重建。

报错 3：docker pull超时，提示无法连接镜像仓库。

• 原因：宿主机到镜像仓库的网络不通。
• 处理：检查代理与防火墙；或在能下载镜像的机器上docker save导出、拷到目标机器docker load导入，再执行主路径。

报错 4：升级后登录不了面板，怀疑配置丢了。

• 原因：登录账号存在/ql/data/config/auth.json，只要数据目录挂载正确就不会丢。多数情况是端口或QlBaseUrl（部署路径，如/test/）环境变量的映射与升级前不一致。
• 处理：核对-p端口和QlBaseUrl环境变量与原来一致；若确实忘记密码，可用命令重置：docker exec -it qinglong ql resetpwd 新密码（用户名可用ql resetname同理重置）。

收尾

把"拉镜像、停旧容器、原参数重建容器"这三步固化成习惯，青龙的 Docker 升级就不再依赖面板内更新；数据永远跟着挂载目录走，代码永远跟着镜像走，两边各管各的，版本回退问题自然消失。建议每次升级前先cp -a备份数据目录、大版本跨越前docker commit留快照，这两步加起来不到一分钟。下面是可直接复用的升级命令片段，把./data换成你的实际数据目录即可：

cp -a ./data ./data_backup_$(date +%Y%m%d) && \ docker stop qinglong && docker rm qinglong && \ docker pull whyour/qinglong:latest && \ docker run -dit --name qinglong -p 5700:5700 \ -v $PWD/data:/ql/data --restart unless-stopped \ whyour/qinglong:latest

执行完用「验证结果」一节逐条核对，确认无误后删除多余的备份目录即可。

【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台（Timed task management platform supporting Python3, JavaScript, Shell, Typescript）项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong