青龙面板升级失败：玩客云 ARM 环境的 6 项恢复排查手册

青龙面板升级失败玩客云 ARM 环境的 6 项恢复排查手册【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台Timed task management platform supporting Python3, JavaScript, Shell, Typescript项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong青龙面板QingLong是一款支持 Python3、JavaScript、Shell、TypeScript 的定时任务管理平台。很多用户把它跑在玩客云这类 ARM 架构的低功耗设备上一旦升级失败面板就打不开任务也全排不出去。这篇文章不堆理论直接给你一套排查路线先分清你的部署方式再按症状把问题圈到「配置、依赖、服务、鉴权」四格中的一格然后照单处理最后用检查清单确认真的恢复了。动手前先分诊你的面板是怎么跑的同样是升级失败Docker 部署和直接部署的排查入口完全不同先花十秒确认自己属于哪一种Docker 部署平时用docker-compose up -d启动数据目录挂载到容器里的/ql/data。日志、重启都从容器侧入手。直接部署代码直接克隆在服务器上由 PM2 拉起进程。问题往往出在node_modules和系统环境里。确认部署形态后对着下面的症状表把问题圈个格子你看到的现象大概率出在哪一环容器反复 Crash / 起不来卷挂载、端口映射、镜像架构容器在跑但 5700 端口连不上进程挂了或端口被占用日志里报Cannot find moduleNode 依赖没装全或与 ARM 架构不匹配面板能打开但登录进不去 / 反复提示错误auth.json鉴权配置异常容器反复崩溃卷挂载和镜像架构是头号嫌疑玩客云是 ARM 架构第一件要排除的事是镜像架构对不对。Docker 镜像分 Alpine 和 Debian 两种基底见 Docker 部署配置 里的注释选错基底或架构不符容器起来就是立刻退出的样子。再看挂载Docker 部署配置 中默认把./data挂到/ql/data端口是5700:5700。如果你改过自定义目录检查宿主机目录是否存在、容器里是否还指向它。两条命令先看个大概docker logs 容器名 21 | grep -iE error|fail docker-compose ps5700 端口没监听确认进程是不是真的活着容器状态显示 running浏览器却还是超时说明问题在容器内部的进程。直接部署场景下同理重点看 PM2 进程和端口监听两个地方pm2 status netstat -tulpn | grep 5700端口被别的进程占用、或者 PM2 进程处于 errored 状态都会造成这种「容器活着、面板打不开」的假象。确认异常后用docker-compose restart或pm2 restart all拉起再回来看端口。国内环境重装依赖一条命令搞定Cannot find module这类报错几乎都指向依赖问题。依赖清单 里声明了grpc/grpc-js等需要原生编译的包在 ARM 设备玩客云上升级后如果node_modules没随版本同步更新就会缺模块。最省事的做法是进部署目录强制重装国内网络建议直接走镜像源npm install --force --registryhttps://registry.npmmirror.comDocker 场景下进容器执行同一条命令即可docker exec -it 容器名 bash。登录异常auth.json 是最后的手术刀面板和端口都正常但登录进不去通常卡在data/config/auth.json。三个动作按轻重缓急来./shell/update.sh resetpwd # 重置登录密码 ./shell/update.sh resetlet # 清空登录错误次数如果auth.json本身损坏可参照 鉴权配置样例 的结构手动修复字段或从配置备份中恢复升级过程会自动把配置副本留在data/config/下的备份位置。另外提醒一句升级脚本会覆盖config.sh一类的运行配置但账号密码存在auth.json里两者损坏的后果完全不同别混为一谈。收个尾跑一遍环境体检脚本上面的症状分组处理完后最稳的做法是执行一次官方内置的环境体检它会依次检查配置文件、重装青龙依赖、重载 PM2并主动请求面板和后台接口验证是否真正起来了./shell/check.sh即 环境修复脚本。结尾会明确打印「面板服务启动正常 / 后台服务启动正常」看到这两行才算恢复闭环。恢复验证逐项打勾再宣布成功☐docker-compose ps或pm2 status状态全部正常无 restart 循环☐netstat -tulpn | grep 5700能看到监听进程☐ 浏览器访问面板可登录账号密码与升级前一致☐ 定时任务列表能打开手动触发一个任务能正常出日志☐data/config/config.sh中的自定义项如端口、部署路径没有被覆盖丢☐./shell/check.sh结尾输出「面板服务启动正常」和「后台服务启动正常」升级前做三件事下次升级少受罪先把数据搬出去。把data/目录整体挂到外接硬盘等更可靠的存储上修改 Docker 部署配置 的volumes映射即可玩客云自带 eMMC 长期高频读写并不可靠。升级前手动整备一次数据目录备份或使用官方备份命令ql backup备份产物落在data/bak/下升级脚本的完整记录在data/log/update/目录出问题先翻这里。核对版本兼容性。打开 版本说明 看一眼当前版本的变更日志——不同版本间 Alpine / Debian 分支、gRPC 配置都有过调整跨大版本升级前确认一下能省掉很多弯路。把体检变成习惯。每月跑一次./shell/check.sh给环境做个体检每季度手动备份一次data/到外部存储。升级失败大多不是玄学而是这三个动作里漏掉了一个。【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台Timed task management platform supporting Python3, JavaScript, Shell, Typescript项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考