尧图网站建设 
青龙面板部署排障与修复完全指南如何快速解决启动失败、白屏、定时任务不执行【免费下载链接】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 的定时任务管理平台。在玩客云或小服务器上 Docker 部署或升级后面板打不开、登录页白屏、定时任务集体停摆跟着本文分场景处理常规故障大约 10 分钟即可恢复。快速分诊先确认你掉进哪个坑别急着重装30 秒对照下表定位你的故障分支然后直接跳到对应场景你看到的现象最可能的原因跳到浏览器连接超时/拒绝5700 端口不通容器没起来或进程崩溃场景一页面能打开但白屏或访问报 404部署路径QlBaseUrl配置与访问地址不匹配场景二面板正常但定时任务到点不执行调度器crond/node没工作场景三启动即崩日志报 Cannot find module如 sqlite3依赖与 ARM 架构不匹配或未装全场景四所有场景共用一个总开关命令建议先跑一遍它会自动检测配置、重装依赖、重启服务并给出面板/后台两项健康检查结果# 容器部署 docker exec -it 容器名 bash -c ./shell/check.sh # 裸机部署 ./shell/check.sh修复脚本位于 shell/check.sh它检查的后台健康接口是http://localhost:5700/api/health返回code:200且status:ok才算后台正常。场景一端口不通面板打不开 确认症状浏览器访问http://服务器IP:5700一直转圈或提示无法访问此网站。在服务器上确认端口确实没人监听# 两种部署方式命令相同 netstat -tulpn | grep 5700没有任何输出说明服务根本没在跑。执行操作先看它为什么没起来。容器部署的启动日志在容器日志里青龙面板自身的容器内日志不落盘早期错误只能从 docker logs 找# 容器部署 docker ps -a | grep qinglong # 确认容器状态是 Up 还是 Exited docker logs --tail 100 容器名裸机部署用 pm2 查# 裸机部署 pm2 status pm2 logs qinglong --lines 100容器状态是 Exited、日志里出现权限错误无法写入 /ql/data数据卷权限不对在宿主机执行chown -R 容器用户UID:容器用户UID 你挂载的data目录后docker restart 容器名。挂载关系见 docker/docker-compose.yml默认./data:/ql/data。日志里出现 Cannot find module直接走场景四。其它崩溃docker restart 容器名容器部署或pm2 restart all裸机部署后再看日志。验证是否修好curl -s http://127.0.0.1:5700/api/health?t$(date %s)看到code:200和status:ok且浏览器能打开登录页本场景结束。场景二白屏或 404但服务明明在跑 ️执行操作这个分支的典型特征是/api/health能返回 200但页面一片白或者你通过反向代理路径访问时 404。九成是部署路径没对齐。容器启动时通过环境变量QlBaseUrl指定访问前缀以斜杠开头结尾例如/test/裸机部署则改在data/config/config.sh里。改法以你的实际部署方式为准容器在 docker/docker-compose.yml 的environment下核对QlBaseUrl后docker compose restart裸机编辑data/config/config.sh后重启服务。拿不准就先改回默认/用 IP 直连验证。验证是否修好curl -s http://127.0.0.1:5700/ | grep -o div idroot/div能打印出div idroot/div且浏览器加载出登录界面即修复成功。场景三面板正常定时任务到点不执行 ⏰确认症状先排除任务本身报错在面板里对某个任务点立即执行然后看任务日志目录data/log/里有没有新增该任务的日志文件。有日志且任务执行了说明调度器没问题是 cron 表达式写错或任务被暂停。点立即执行也没动静、没有新日志基本是调度器没工作。执行操作青龙的调度模式分两种有 crond 二进制时走系统 crontabsystem 模式否则走 Node 内置调度node 模式容器启动脚本 docker/docker-entrypoint.sh 会自动探测也可用QL_SCHEDULER环境变量显式指定。# 容器部署 docker exec -it 容器名 sh -c ps -ef | grep -v grep | grep crond; cat /ql/data/config/config.sh | grep -i scheduler # 裸机部署 ps -ef | grep -v grep | grep crondsystem 模式下 crond 没起来就手动拉起docker exec -it 容器名 sh -c crond -f 裸机直接crond。如果确认 crond 用不了把模式改成 node 模式再重启容器即可两种模式对使用方式无感。验证是否修好新建一个* * * * *每分钟执行的任务等 1~2 分钟任务在面板里出现多条执行成功记录且data/log/下持续新增日志文件。场景四Cannot find module装不上依赖 确认症状启动日志里反复出现Cannot find module sqlite3之类的报错或docker ps里容器反复重启。玩客云这类 ARM 设备最容易踩这个坑。执行操作项目已把 sqlite3 锁定为带预编译二进制的替代包见 package.json 中的 overrides版本以项目内实际版本为准所以不要自己单独装原生 sqlite3直接用官方检查脚本重装整套依赖# 容器部署 docker exec -it 容器名 bash -c ./shell/check.sh # 裸机部署国内网络建议加镜像源加速 npm i -g pnpm8.3.1 pm2 ts-node typescript5 ./shell/check.sh跑完后它会重装 pnpm/pm2/ts-node/typescript 和项目依赖、重建 notify 通知文件并重启 pm2。若网络不通导致下载失败先给 npm 配置镜像源再重试。验证是否修好curl -s http://127.0.0.1:5700/api/health?t$(date %s)返回code:200且status:ok且pm2 status或docker ps里服务稳定在线、不再反复重启即修复完成。原因速览为什么偏偏是这四个坑端口不通多数不是代码问题而是数据卷/ql/data挂载目录的属主对不上启动脚本 docker/docker-entrypoint.sh 权限自检失败直接退出容器。白屏/404前端静态资源是按QlBaseUrl构建出来的访问路径和构建前缀不一致时资源 404页面自然一片白。任务不执行system 模式依赖 crond 进程常驻容器重启或精简环境里它悄悄消失面板 UI 却一切正常所以最容易隐身。模块丢失原生 sqlite3 需要按 CPU 架构编译玩客云的 ARM 设备若装了不匹配的预编译包就会在加载时报 Cannot find module。一次升级不翻车动手前的四件事备份数据目录cp -a 你的数据目录 备份路径把 config、db、scripts、log 一起带走。能防住升级中途断电/失败导致配置损坏、数据库异常场景一、场景四的兜底。记下当前版本与改动过的配置版本信息见 version.yaml重点比对data/config/config.sh里改过的项端口、QlBaseUrl、调度模式。能防住新配置格式不兼容、自定义配置被重置场景二。核对数据卷挂载确认 compose 里数据目录映射为/ql/data且宿主机目录属主正确。能防住升级后容器因权限直接退出场景一。升级后立即跑一遍./shell/check.sh并看/api/health把问题拦在第一批定时任务触发之前。能防住场景三、场景四在任务停摆时才被发现的被动局面。出问题了你的第一个动作下次再翻车记住第一动作永远是看日志容器部署查docker logs --tail 100 容器名裸机部署查pm2 logs qinglong和data/syslog/、data/log/升级过程日志在data/log/update/拿到报错关键字再对号入座本文场景。若日志指向的模块你改不动带着版本号和报错片段去项目官方仓库的 Issues 区搜索或提交同架构ARM/玩客云的历史问题基本都能找到现成答案。【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台Timed task management platform supporting Python3, JavaScript, Shell, Typescript项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 青龙面板部署排障与修复完全指南：如何快速解决启动失败、白屏、定时任务不执行
青龙面板部署排障与修复完全指南如何快速解决启动失败、白屏、定时任务不执行【免费下载链接】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 的定时任务管理平台。在玩客云或小服务器上 Docker 部署或升级后面板打不开、登录页白屏、定时任务集体停摆跟着本文分场景处理常规故障大约 10 分钟即可恢复。快速分诊先确认你掉进哪个坑别急着重装30 秒对照下表定位你的故障分支然后直接跳到对应场景你看到的现象最可能的原因跳到浏览器连接超时/拒绝5700 端口不通容器没起来或进程崩溃场景一页面能打开但白屏或访问报 404部署路径QlBaseUrl配置与访问地址不匹配场景二面板正常但定时任务到点不执行调度器crond/node没工作场景三启动即崩日志报 Cannot find module如 sqlite3依赖与 ARM 架构不匹配或未装全场景四所有场景共用一个总开关命令建议先跑一遍它会自动检测配置、重装依赖、重启服务并给出面板/后台两项健康检查结果# 容器部署 docker exec -it 容器名 bash -c ./shell/check.sh # 裸机部署 ./shell/check.sh修复脚本位于 shell/check.sh它检查的后台健康接口是http://localhost:5700/api/health返回code:200且status:ok才算后台正常。场景一端口不通面板打不开 确认症状浏览器访问http://服务器IP:5700一直转圈或提示无法访问此网站。在服务器上确认端口确实没人监听# 两种部署方式命令相同 netstat -tulpn | grep 5700没有任何输出说明服务根本没在跑。执行操作先看它为什么没起来。容器部署的启动日志在容器日志里青龙面板自身的容器内日志不落盘早期错误只能从 docker logs 找# 容器部署 docker ps -a | grep qinglong # 确认容器状态是 Up 还是 Exited docker logs --tail 100 容器名裸机部署用 pm2 查# 裸机部署 pm2 status pm2 logs qinglong --lines 100容器状态是 Exited、日志里出现权限错误无法写入 /ql/data数据卷权限不对在宿主机执行chown -R 容器用户UID:容器用户UID 你挂载的data目录后docker restart 容器名。挂载关系见 docker/docker-compose.yml默认./data:/ql/data。日志里出现 Cannot find module直接走场景四。其它崩溃docker restart 容器名容器部署或pm2 restart all裸机部署后再看日志。验证是否修好curl -s http://127.0.0.1:5700/api/health?t$(date %s)看到code:200和status:ok且浏览器能打开登录页本场景结束。场景二白屏或 404但服务明明在跑 ️执行操作这个分支的典型特征是/api/health能返回 200但页面一片白或者你通过反向代理路径访问时 404。九成是部署路径没对齐。容器启动时通过环境变量QlBaseUrl指定访问前缀以斜杠开头结尾例如/test/裸机部署则改在data/config/config.sh里。改法以你的实际部署方式为准容器在 docker/docker-compose.yml 的environment下核对QlBaseUrl后docker compose restart裸机编辑data/config/config.sh后重启服务。拿不准就先改回默认/用 IP 直连验证。验证是否修好curl -s http://127.0.0.1:5700/ | grep -o div idroot/div能打印出div idroot/div且浏览器加载出登录界面即修复成功。场景三面板正常定时任务到点不执行 ⏰确认症状先排除任务本身报错在面板里对某个任务点立即执行然后看任务日志目录data/log/里有没有新增该任务的日志文件。有日志且任务执行了说明调度器没问题是 cron 表达式写错或任务被暂停。点立即执行也没动静、没有新日志基本是调度器没工作。执行操作青龙的调度模式分两种有 crond 二进制时走系统 crontabsystem 模式否则走 Node 内置调度node 模式容器启动脚本 docker/docker-entrypoint.sh 会自动探测也可用QL_SCHEDULER环境变量显式指定。# 容器部署 docker exec -it 容器名 sh -c ps -ef | grep -v grep | grep crond; cat /ql/data/config/config.sh | grep -i scheduler # 裸机部署 ps -ef | grep -v grep | grep crondsystem 模式下 crond 没起来就手动拉起docker exec -it 容器名 sh -c crond -f 裸机直接crond。如果确认 crond 用不了把模式改成 node 模式再重启容器即可两种模式对使用方式无感。验证是否修好新建一个* * * * *每分钟执行的任务等 1~2 分钟任务在面板里出现多条执行成功记录且data/log/下持续新增日志文件。场景四Cannot find module装不上依赖 确认症状启动日志里反复出现Cannot find module sqlite3之类的报错或docker ps里容器反复重启。玩客云这类 ARM 设备最容易踩这个坑。执行操作项目已把 sqlite3 锁定为带预编译二进制的替代包见 package.json 中的 overrides版本以项目内实际版本为准所以不要自己单独装原生 sqlite3直接用官方检查脚本重装整套依赖# 容器部署 docker exec -it 容器名 bash -c ./shell/check.sh # 裸机部署国内网络建议加镜像源加速 npm i -g pnpm8.3.1 pm2 ts-node typescript5 ./shell/check.sh跑完后它会重装 pnpm/pm2/ts-node/typescript 和项目依赖、重建 notify 通知文件并重启 pm2。若网络不通导致下载失败先给 npm 配置镜像源再重试。验证是否修好curl -s http://127.0.0.1:5700/api/health?t$(date %s)返回code:200且status:ok且pm2 status或docker ps里服务稳定在线、不再反复重启即修复完成。原因速览为什么偏偏是这四个坑端口不通多数不是代码问题而是数据卷/ql/data挂载目录的属主对不上启动脚本 docker/docker-entrypoint.sh 权限自检失败直接退出容器。白屏/404前端静态资源是按QlBaseUrl构建出来的访问路径和构建前缀不一致时资源 404页面自然一片白。任务不执行system 模式依赖 crond 进程常驻容器重启或精简环境里它悄悄消失面板 UI 却一切正常所以最容易隐身。模块丢失原生 sqlite3 需要按 CPU 架构编译玩客云的 ARM 设备若装了不匹配的预编译包就会在加载时报 Cannot find module。一次升级不翻车动手前的四件事备份数据目录cp -a 你的数据目录 备份路径把 config、db、scripts、log 一起带走。能防住升级中途断电/失败导致配置损坏、数据库异常场景一、场景四的兜底。记下当前版本与改动过的配置版本信息见 version.yaml重点比对data/config/config.sh里改过的项端口、QlBaseUrl、调度模式。能防住新配置格式不兼容、自定义配置被重置场景二。核对数据卷挂载确认 compose 里数据目录映射为/ql/data且宿主机目录属主正确。能防住升级后容器因权限直接退出场景一。升级后立即跑一遍./shell/check.sh并看/api/health把问题拦在第一批定时任务触发之前。能防住场景三、场景四在任务停摆时才被发现的被动局面。出问题了你的第一个动作下次再翻车记住第一动作永远是看日志容器部署查docker logs --tail 100 容器名裸机部署查pm2 logs qinglong和data/syslog/、data/log/升级过程日志在data/log/update/拿到报错关键字再对号入座本文场景。若日志指向的模块你改不动带着版本号和报错片段去项目官方仓库的 Issues 区搜索或提交同架构ARM/玩客云的历史问题基本都能找到现成答案。【免费下载链接】qinglong支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台Timed task management platform supporting Python3, JavaScript, Shell, Typescript项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考