青龙面板升级失败起不来？玩客云 / Docker 环境完整排查全指南

青龙面板升级失败起不来？玩客云 / Docker 环境完整排查全指南

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

ql update 跑完，浏览器一刷新，面板页面打不开了——青龙面板升级失败就发生在这种瞬间。这篇文章按升级全周期，讲清玩客云与 Docker 部署的定时任务平台，升级前做什么、故障时看哪里、恢复后怎么验证。

升级前的检查清单：动手前该做的三件事

• 备份 data 目录。定时任务、环境变量、脚本、日志都在 data 下。Docker 部署（把面板装进容器、开箱即用的运行方式）默认用卷挂载——把宿主机目录映射进容器，删容器也不丢数据——所以只需备份宿主机上对应的那份目录：

# 升级前把 data 目录打包一份 tar -czf ql-data-$(date +%F).tar.gz data

• 确认架构与镜像匹配。玩客云或其他小主机，先确认 CPU 是 x86 还是 ARM（两种架构互不兼容，拉错架构的镜像根本起不来）。官方镜像分 alpine 基础的 whyour/qinglong:latest 与 debian 基础的 whyour/qinglong:debian 两类，在 docker/docker-compose.yml 中指定：

# 查看本机架构 uname -m

• 记录当前配置。端口等关键项在 data/config/config.sh（示例格式见 sample/config.sample.sh），登录信息在 data/config/auth.json，把当前值抄下来，升级后方便比对。顺手看一眼 version.yaml，确认目标版本改了什么。

故障时的症状对照：看现象，找第一处该查的地方

⚠️ 升级失败后常见的四种现象如下，对号入座即可：

• 现象：面板页面一直转圈或连接失败。最可能的原因：后台进程没起来，或启动后立刻崩溃。第一处该查：容器日志末尾（直接部署则看 data/syslog/ 下最新的日志文件）。
• 现象：5700 端口不通，但容器显示在运行。最可能的原因：端口映射没配对，或配置里把 QlPort 从默认 5700 改成了别的值。第一处该查：docker-compose.yml 的 ports 段，以及 config.sh 里的端口值。
• 现象：日志里 npm install 失败、Cannot find module 报错。最可能的原因：依赖锁定没完成——依赖是按 package.json 记录的版本安装的，下载源不稳或该架构没有预编译包时就会中断。第一处该查：data/log/update/ 下的每次升级日志，重点看含 Failed 的行。
• 现象：面板能打开，但登录不上、密码不对。最可能的原因：data/config/auth.json 损坏或被样例文件覆盖。第一处该查：auth.json 内容是否与升级前一致，有备份直接还原。

恢复操作：容器故障排查按两条部署线分开做

Docker 部署线

确认：先看容器状态与最近日志，定位真实报错，而不是反复重启碰运气。

docker-compose ps # 查看容器状态 docker logs <容器名> --tail 100 # 看报错日志末尾

恢复：升级失败最常见的是依赖或配置装了一半。官方 shell/check.sh 会检测并修复配置文件、重装依赖、重启服务：

docker exec -it <容器名> bash -c "cd /ql && bash shell/check.sh" # 容器部署 cd /ql && bash shell/check.sh # 直接部署

验证：端口和后台都恢复响应，才算修好。若改过 QlPort，把下面的 5700 换成实际值：

netstat -tlnp | grep 5700 # 看端口是否在监听 curl -s http://localhost:5700/api/health # 看后台是否返回正常

直接部署线

确认：翻 data/log/update/ 里最近一次执行日志和 data/syslog/ 下最新文件，确认升级断在源码下载、依赖安装还是服务重启哪一步。

恢复：在青龙目录直接执行上面 check.sh 那条命令；纯依赖问题也可以手动重装 npm 依赖，国内网络建议把下载地址换成国内镜像源（就近的下载源，包一样、速度更快）。

验证：同容器线的端口与健康检查两条命令，再补一条 pm2 status，确认进程状态为 online。

长期稳定建议：三条定期做的事

• 定期跑一次内置环境检测，把配置与依赖漂移处理在升级失败之前：ql check
• 定期清理旧日志，避免磁盘写满拖累定时任务：ql rmlog 30
• 升级前先拉取最新镜像比对、确认变更清单再决定升不升：docker pull whyour/qinglong:latest

按这套流程走完，绝大多数升级故障都能自行定位。如果还是起不来，把日志输出原样贴到项目官方文档或 issue 区，注明部署方式、当前版本和卡住的位置，维护者会更快帮你定位。

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