宝塔面板+Docker部署青龙面板完整实操指南

说实话青龙面板这名字乍一听确实让人摸不着头脑但用过的人都知道它本质上就是一个非常好用的定时任务管理平台。你可以把周期性执行的脚本、命令统一丢进去由面板帮你调度执行跑完自动记录日志出错还能推送提醒彻底告别了以前“crontab写一长串、日志还得自己翻”的原始状态。前段时间我帮朋友在一台新服务器上部署这套环境研究了一圈最终选定了宝塔面板 Docker 的组合方案来安装青龙面板整个过程踩了几个坑也把重点都摸清了。这篇就算是一份完整的实操记录给那些准备在宝塔面板上用 Docker 跑青龙面板的朋友做个参考少走点弯路。1. 为什么我坚持用 Docker 方式部署青龙面板1.1 青龙面板解决的核心问题青龙面板QingLong Panel是一个支持多种脚本语言的定时任务管理面板它提供了可视化的 Web 界面可以统一管理、调度 Node.js、Python3、Shell 等脚本。平时最典型的用法就是你想让某些脚本每天定点跑一次把脚本扔进面板设置好 cron 表达式就行执行结果、日志、状态一目了然不用再去 SSH 里敲 crontab 碰运气。这套工具最大的好处就是把“定时任务”这件事产品化了。普通 crontab 只能告诉你“跑了还是没跑”而青龙面板能告诉你“什么时候跑的、跑了多久、日志里输出了什么、是否报错”同时还支持多账户 Cookie 管理、环境变量管理、任务依赖隔离等进阶能力。也因此很多人把它当作个人服务器的“任务调度中心”来用。1.2 Docker 部署与直接安装的取舍早期大部分教程推荐的是“一键脚本直接部署”就是在服务器上装 Node.js 环境然后把青龙面板的源码拉下来跑。这种方式简单直接但我在实际使用中发现了几个问题第一宿主环境被污染。面板依赖的 Node 版本、全局包、Python 库全部装到了系统环境里以后再部署别的项目经常出现版本冲突、依赖互相打架的情况。第二升级和回滚很麻烦。面板出新版本你得手动去拉代码、装依赖、重启服务一旦新版有 bug 想回退又是一通折腾。第三卸载不干净。源码部署卸载时留下的文件、环境变量、开机自启动项手动清理很容易漏。Docker 容器化则完全不同青龙面板连同它的运行环境被打包在一个独立容器里和宿主机其它服务天然隔离升级就是拉新镜像重建容器回滚就是换回旧镜像卸载就删容器删镜像数据目录一清干干净净。所以我一直跟朋友说在条件允许的情况下优先用 Docker 方案省心是长期的事情。2. 部署前的环境准备宝塔面板与 Docker 的安装细节2.1 服务器配置建议与系统选择青龙面板本身并不吃资源因为绝大多数任务脚本都很轻量但考虑到 Docker 本身有一定内存占用加上还要跑任务脚本我个人建议配置不要低于 1 核 2G 内存。如果你计划跑的任务脚本比较多、并发高那直接上 2 核 4G体验会好很多否则容器很容因为内存不足被杀掉。系统方面兼容性最好的是 Debian 系和 CentOS 系。我这次用的是 CentOS 7.9实际上 7.x 已经停止维护新环境更推荐 Debian 11/12 或者 Ubuntu 20.04/22.04。宝塔面板对这些系统的支持都很成熟安装过程差异不大。2.2 宝塔面板安装 Docker 的两种方式对比宝塔面板安装 Docker 有两条路软件商店安装和 SSH 命令行安装。第一种打开宝塔面板后台左侧菜单找到“软件商店”在搜索框输入“Docker”会看到“Docker管理器”这个插件。直接点击安装即可安装完成后在“Docker”菜单里就能看到容器、镜像、网络等管理界面。这是最直观的方式适合不习惯敲命令的人。第二种通过 SSH 登录服务器用官方安装脚本安装curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun systemctl enable docker systemctl start docker我通常更推荐第二种方式原因有几点宝塔插件本质是调用的系统 Docker 服务有些老版本面板自带的 Docker 插件版本偏旧直接在系统层安装能拿到较新的 Docker Engine。通过系统 systemd 管理 Docker 服务开机自启、日志查看都更符合 Linux 习惯。安装完成后宝塔面板的“Docker”菜单其实也能识别到系统级 Docker两边不冲突。两种方式装好后可以用docker -v验证版本用docker ps验证服务是否正常运行。注意安装完 Docker 后建议重启一次宝塔面板在面板设置里操作即可让面板正确加载 Docker 的 Socket 连接。如果装完发现宝塔的 Docker 菜单报错“连接不到 Docker 服务”十有八九是没重启面板。另外国内服务器拉取 Docker Hub 镜像经常很慢甚至超时。我建议在装好 Docker 后顺手配置一下镜像加速。在/etc/docker/daemon.json里写入{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com ] }然后执行systemctl daemon-reload systemctl restart docker让配置生效。这一步非常关键不配置的话后面拉取青龙面板镜像可能要等很久。2.3 端口规划与防火墙策略青龙面板默认监听 5700 端口这个端口可以自定义但没必要改记住默认值就行。需要注意的是很多人在第一步就卡住是服务器安全组云控制台和系统防火墙firewalld/ufw没有放行 5700 端口。如果你用的是阿里云、腾讯云这类云服务器控制台里的“安全组规则”记得添加入方向 TCP 5700 端口。系统层面CentOS 执行firewall-cmd --zonepublic --add-port5700/tcp --permanent firewall-cmd --reloadDebian/Ubuntu 就检查 ufwufw allow 5700/tcp做完这两步浏览器访问才有戏。3. 青龙面板容器部署完整步骤从拉镜像到容器运行3.1 镜像版本选择latest 还是固定版本青龙面板的 Docker 镜像由官方维护仓库地址是whyour/qinglong。在拉取之前先去 Docker Hub 看一眼 tags 列表了解当前最新版本。我做了一个简单的对比方便你决定用哪个 tag镜像 tag适用场景注意事项latest追求新功能能接受尝鲜版本迭代快界面和数据结构可能有变动2.17.x固定版本生产环境求稳锁定版本号升级前手动操作2.15.x旧版本依赖旧插件/旧脚本兼容性部分老脚本只兼容旧版数据结构我这次安装选择的是latesttag因为需要演示面板当前最完整的功能形态。但如果你是正式使用、跑重要任务我更推荐指定固定版本比如whyour/qinglong:2.17.9。原因很简单latest 是个动态标签哪天重建容器可能拉到一个新版本而新版本不一定兼容你已经在跑的脚本这种“意外惊喜”没人想要。3.2 数据目录规划容器删了数据不能丢Docker 容器是无状态的任何写在容器内部的数据都会在容器被删除时消失。所以数据目录必须挂载到宿主机上这是整个安装过程中最重要的一环。青龙面板新版2.15 及以上的容器内数据路径是/ql/data这一点和早期版本不一样老教程里写的大多是/ql/config、/ql/log、/ql/scripts这类目录如果你的镜像版本较新挂载路径就得按新版来否则目录挂载后面板识别不到配置。我个人的目录规划如下mkdir -p /opt/ql/data把整个/ql/data挂载到宿主机的/opt/ql/data所有配置、日志、数据库、脚本都在里面。这样即使容器哪天出问题被删了只要重新建一个容器挂载同一个目录数据就全回来了。如果你用的是早期版本的镜像那么需要按旧路径分别挂载-v /opt/ql/config:/ql/config -v /opt/ql/log:/ql/log -v /opt/ql/db:/ql/db -v /opt/ql/scripts:/ql/scripts -v /opt/ql/jbot:/ql/jbot这段时间我踩过最大的坑就是看了一篇老教程按旧路径挂载目录结果容器起来之后面板一直提示初始化异常日志里全是配置文件找不到的错误。后来发现是因为拉的是最新版镜像数据目录结构已经变了。所以请务必先确认镜像版本再决定挂载路径。3.3 docker run 命令详解每个参数都是干什么的数据目录准备好之后直接执行容器创建命令。我这里给出最新版镜像数据路径/ql/data的标准命令docker run -dit \ -v /opt/ql/data:/ql/data \ -p 5700:5700 \ --name qinglong \ --hostname qinglong \ --restart unless-stopped \ whyour/qinglong:latest逐个参数解释一下-dit-d表示后台运行容器-i保持标准输入打开-t分配一个伪终端。三个参数组合在一起容器会在后台持续运行同时你还能通过docker exec进入容器操作。-v /opt/ql/data:/ql/data把宿主机的数据目录挂载进容器的数据目录实现数据持久化。-p 5700:5700将容器的 5700 端口映射到宿主机的 5700 端口。如果服务器上 5700 端口已占用可以改成-p 5800:5700这样访问http://IP:5800也能进面板。--name qinglong给容器起个名字后续管理、查看日志都直接用这个名字不用记一长串容器 ID。--hostname qinglong设置容器的主机名部分脚本在运行时会读取主机名保持一致可以避免奇怪的报错。--restart unless-stopped容器异常退出时自动重启服务器重启后也会自动拉起容器。这句一定要加否则服务器重启后青龙面板就没了。whyour/qinglong:latest指定镜像和标签。有些教程还会加--net host宿主机网络模式我个人不太建议。桥接网络模式虽然多了一层 NAT但端口管理、多容器共存更灵活也方便宝塔面板的 Docker 插件识别和管理。3.4 容器运行后的验证方法容器启动后先确认它是不是真的活在docker ps看到qinglong容器的 STATUS 是Up说明容器在跑。如果 STATUS 显示Exited别慌先看日志docker logs qinglong日志里能看到青龙面板的启动过程包括监听端口、初始化数据库等输出。正常启动后最后几行一般是类似“服务已启动”的信息。再确认端口映射是否正确curl -I http://127.0.0.1:5700如果返回 HTTP 200说明服务已经在监听如果连接被拒绝那就从容器状态、端口映射、防火墙三个方向排查。4. 青龙面板初始化配置从浏览器访问到账号安全设置4.1 第一次访问初始化账号的流程容器跑起来之后浏览器访问http://服务器IP:5700第一次打开会进入初始化页面。这一步和大多数面板一样需要设置管理员用户名和密码设置完成后用这套账号登录。初始化时有个细节值得注意青龙面板默认会开启“登录验证码”第一次初始化时就会让你预留安全邮箱用于忘记密码时找回。建议把这一步认真填掉别跳到下一步就忽略否则后面忘记密码只能去容器里改数据库比较麻烦。登录进面板后第一件事是看左下角的版本号确认当前实际运行的青龙版本。后续查资料、问问题都要基于这个版本因为青龙 2.15 之后的界面和功能布局变化很大很多旧教程的菜单名和实际操作对不上。4.2 面板的核心设置项哪些必须调整初始化完成后我建议按这个顺序过一遍设置进入“系统设置”第一个要动的是“通知设置”。青龙面板支持 Server酱、企业微信、钉钉、Telegram 等多种通知渠道配置好之后任务跑完、出错、面板异常都能推送消息到手机。我个人最常用的是 Server酱关注个公众号拿到 SendKey 填进去就行整个过程五分钟不到。通知这块虽然不影响任务执行但强烈建议配一下别等脚本出错了你还在眼巴巴刷面板日志。第二个要动的是“安全设置”。把“登录失败锁定阈值”打开防止有人暴力试密码。青龙面板默认端口暴露在公网如果没有防护很容易被撞库扫描。如果你只有自己用还可以把面板地址改到非标准端口或者干脆在防火墙层面只允许自己的 IP 访问 5700 端口。第三个是“系统参数”里的任务并发数。青龙面板默认并发数是 1也就是同一时间只跑一个任务。如果你的任务脚本互相不依赖可以适当调高到 2-3能明显缩短整批任务的执行时间。但如果任务之间共享同一个账号的 Cookie并发过高可能触发风控这里建议保守一点一个一个来。4.3 手动备份面板配置未雨绸缪青龙面板的备份不像宝塔面板那种一键整机备份它所有的配置都在数据目录里。我的备份习惯是每周对/opt/ql/data做一次压缩打包备份到另一块磁盘或者对象存储tar -zcvf ql_backup_$(date %Y%m%d).tar.gz /opt/ql/data恢复时只需要把备份文件解压回/opt/ql/data再重建容器即可。这个习惯让我免过好几次“手贱改坏配置”的尴尬真心建议有正经任务在跑的人把备份这件事放在和安装同等重要的位置。5. 依赖管理脚本能不能跑起来全看这一环5.1 为什么说依赖是青龙面板的核心运维项青龙面板本身只是一个调度器它负责到点把任务脚本拉起来执行但脚本要跑必须依赖它所需的运行库。以最常见的 Node.js 脚本为例如果脚本里require(axios)而面板环境里没装 axios 这个库执行时直接报Cannot find module axios任务失败。这和脚本代码本身无关就是环境不完备。青龙面板把依赖管理做成了独立功能在“依赖管理”菜单里可以集中查看、安装、卸载各种依赖。这一点比传统在自己服务器上一个个 pip/npm install 要方便太多了尤其当你有多个环境需要统一管理时优势非常明显。5.2 最常装的依赖清单按语言分类青龙面板的脚本最常见的是 Node.js 和 Python3 两种下面我给出一个经过多次验证的基础依赖清单适用于日常绝大多数任务脚本。Node.js 依赖在“依赖管理”里选 npm 类型添加crypto-js加密库几乎每个签到类脚本都会用axiosHTTP 请求库核心中的核心tough-cookie处理 Cookie 的库ts-md5MD5 加密部分脚本登录逻辑需要wsWebSocket 客户端库dotenv读取 .env 环境变量配置jsdomDOM 解析库有些脚本要模拟浏览器环境Python3 依赖在“依赖管理”里选 pip 类型添加requestsHTTP 请求库Python 脚本的标配pip本身也要更新到最新版旧 pip 装新包经常报错aiohttp异步 HTTP 库用到 asyncio 的脚本需要beautifulsoup4HTML 解析库爬虫类脚本常用pycryptodome加密库pandas数据处理库部分数据分析脚本依赖Linux 系统依赖在“依赖管理”里选 linux 类型添加wget下载文件工具git拉取代码工具curl请求工具注意不要试图把依赖一次性全装完因为依赖装太多不但浪费时间还可能引入版本冲突。我的做法是“先跑脚本报什么缺什么就装什么”这样最省事也最干净。比如脚本报Cannot find module jsdom那就只补装 jsdom 一个包装完再重跑。等你的脚本库稳定下来依赖清单也就固定了。5.3 依赖安装的实操技巧与避坑在青龙面板的“依赖管理”页面点“添加依赖”选择类型和名称确认即可。面板会自动去对应的包管理器npm/pip下载安装。这个过程在网页上能看到实时日志装完会提示成功。几个实操经验第一安装依赖时尽量使用面板自带功能不要在容器里手动docker exec -it qinglong bash然后npm install。原因很简单容器一旦重建手动装的依赖全部丢失而面板依赖管理里安装的依赖虽然同样装在容器内但青龙的镜像升级脚本会尝试保留它们比手动装靠谱得多。第二pip 安装某些包非常慢甚至超时。这种情况可以在“依赖管理”里配置 pip 镜像源把 Python 依赖的下载源切换为国内镜像比如清华 PyPI 镜像安装速度会快很多。第三如果任务脚本跑得正常但某天突然报缺某个包不用慌大概率是面板升级时把依赖目录重置了。重新在依赖管理里补装一次就行。5.4 脚本管理从添加、测试到定时调度依赖到位后把脚本放进面板的方式主要有两种一是从“脚本管理”页面直接新建一个脚本把代码粘贴进去保存二是通过定时任务的“拉取脚本”功能从 GitHub 仓库自动拉取指定仓库到面板。我自己更常用第二种方式因为很多脚本更新频率高手动复制粘贴容易拉到旧版。在“定时任务”页面新建任务填写任务名称、执行命令和 cron 表达式再填一个仓库地址青龙会定期去拉取最新代码并执行。定时表达式是cron格式青龙面板里也内置了常见任务示例比如每天凌晨跑一次的0 0 0 * * ?。刚开始不熟悉 cron 语法的朋友建议先在面板的“定时任务”页面用可视化工具生成表达式而不是手写手写 cron 十有八九会写错。6. 常见问题排查我实际遇到过的情况和解决办法6.1 容器反复重启或直接 Exited这个问题的核心原因有两个内存不足和启动脚本报错。服务器内存不足时Docker 容器很容易被系统 OOM Killer 干掉表现就是docker ps看到容器一直在 Restarting。查看系统日志dmesg | tail -50如果看到Out of memory相关的记录基本就实锤了。解决办法升级服务器内存或者在创建容器时限制内存使用docker run -dit -m 1024m --memory-reservation 512m ...不过限制内存只能缓解如果容器实际使用量超过限制脚本执行时一样会被杀掉最稳妥的方案还是给服务器加内存。启动脚本报错的话用docker logs qinglong查看日志。常见的是配置文件格式错误、数据库初始化失败通常日志里会明确提示哪一行出错按提示检查对应文件即可。6.2 面板能打开但退出登录后进不去青龙面板登录页有个设置叫“登录双重验证”或“两步验证”具体名称以你实际安装版本为准一旦开启登录时除了密码还要填一个动态验证码。很多人第一次登录时开了这个功能后来退出再登录发现验证码怎么都不对进不去了。解决办法有两个一是检查面板绑定邮件是否正确用忘记密码功能重置二是直接进入容器删除面板的验证配置docker exec -it qinglong bash cd /ql/data/config cat auth.json找到两步验证相关的配置项去掉后重启容器。这个操作对小白来说有点硬核所以我更建议在初始化时先不开两步验证熟悉面板之后再按需开启。6.3 数据备份与迁移换服务器怎么办换服务器时很多人的第一反应是把旧服务器的青龙面板容器导出成镜像再导入新服务器。我试过这种方式镜像文件动辄几个 GB而且导出导入过程经常碰到层损坏的问题非常不可靠。我推荐的方式反而是最朴素的“拷数据目录重建容器”在旧服务器上压缩/opt/ql/data目录。把备份包下载到新服务器解压到/opt/ql/data。在新服务器上跑一遍相同的docker run命令。容器启动后面板会读取挂载目录里的数据自动恢复所有配置、脚本和定时任务连登录账号和密码都在。这种方式数据量小通常几十 MB迁移速度快还不会出现版本不一致的问题前提是镜像版本相同。6.4 面板升级的正确姿势与回滚方案青龙面板升级很简单拉取新镜像删除旧容器用同一个数据目录重新创建容器即可。docker pull whyour/qinglong:latest docker stop qinglong docker rm qinglong docker run -dit -v /opt/ql/data:/ql/data -p 5700:5700 --name qinglong --restart unless-stopped whyour/qinglong:latest但升级前务必做好两件事备份数据目录、确认新版镜像的挂载路径与当前版本一致。我遇到过一次从 2.15 升到 2.17 的情况虽然数据目录结构没变但新版启动时自动迁移了数据库迁移过程旧版数据目录里的文件被改写了。好在提前打了备份包后来迁移出现问题解压回去才恢复。回滚的操作和升级一模一样只是把docker run里的镜像 tag 改成旧版本号即可。容器数据目录不变旧版本启动后能直接使用原有数据。写在最后给新手的最终建议整趟部署下来我自己最大的体会是青龙面板装起来不难难的往往是对环境的管理意识。很多人装完后就不管了直到任务挂了才去翻日志那是比较被动的状态。依赖管理、数据备份、防火墙放行这些事情花十分钟提前做好后续运维能省数小时。最后分享一个小技巧部署完成并验收无误后建议把整个安装过程的命令整理成一个 shell 脚本存起来这样无论是重建环境还是迁移服务器都能一键恢复。我自己的服务器上至今留着这份脚本也是因为踩过太多次“当初怎么装的我忘了”的坑。希望这篇记录能帮你顺利跑起来。