老运维都知道定时脚本这活儿一旦多起来cron 就是个灾难。任务零散在系统各个角落依赖环境互相打架升级一次面板可能连带跑崩三四个脚本。我之前的方案是裸机部署加 systemd 托管虽然也能跑但每次换机器、迁移环境都得从头折腾一遍真心不轻松。后来我把青龙面板qinglong挪进了 Docker再用宝塔面板统一管理整个流程清爽了不少容器隔离了运行环境宝塔管好了宿主机资源和端口青龙管着所有定时任务和脚本依赖三者各司其职。这篇文章我会按自己的实战顺序从宝塔面板安装 Docker 开始一路讲到青龙面板初始化、依赖补全、生产环境加固最后把遇到的坑和排查思路一并列出来。不管你是第一次接触青龙面板还是已经在裸机上跑过一版想迁移到 Docker这篇文章的每一步都能照着抄。1. 安装前先搞清楚宝塔、Docker、青龙三者怎么配合很多人一上来就急着复制部署命令结果容器起来了面板进不去依赖装不上日志刷屏整个人都是懵的。先花五分钟理清这三者的关系后面出问题你才知道去哪里查。1.1 为什么推荐 Docker 版青龙面板本质上是一个带 Web 界面的定时任务管理平台核心组件是 Node.js 运行时和内置的 SQLite 数据库。裸机部署时Node 版本、npm 全局依赖、系统库版本、cron 服务的权限任何一个环节和你服务器上已有环境冲突排查起来都是无底洞。我见过一台服务器上同时跑着三四个业务项目每个项目要求不同 Node 版本最后青龙面板一装直接把其中一个项目的依赖搞崩了。Docker 版的核心价值是把青龙面板及其依赖一次性封装进容器。用生活化类比说裸机部署像在公租房里自己装修墙不能乱拆管道不能乱改Docker 部署像租了个集装箱你想在里面搭什么就搭什么搬走时把门一锁整个箱子搬走就行。容器与宿主机共享内核但文件系统、进程空间、网络端口都是隔离的互不干扰。具体到青龙面板Docker 版还带来几个实打实的好处升级回滚方便旧版容器还在只需要重新拉一个新镜像再启一个容器数据目录通过卷映射保留随时能切回旧版本。依赖环境可控Node、Python、Linux 依赖都在容器里单独维护不会污染宿主机。迁移成本极低只需要把容器数据目录打包带走新机器上重新跑一遍部署命令数据原样恢复。资源隔离可以限制容器内存和 CPU避免定时任务高峰时段把服务器拖垮。1.2 环境准备清单在动手之前对照下面的清单确认服务器和宝塔面板的状态服务器建议 1 核 2G 起步青龙面板容器本身占用内存约 300-500MB加上脚本并发执行时的开销2G 内存会比较从容。系统版本CentOS 7.x、Ubuntu 20.04/22.04、Debian 11/12 都可以宝塔面板对这几类系统支持最完善。宝塔面板版本建议升级到最新稳定版我写这篇文章时用的是 9.x 系列。新版本对 Docker 管理器的支持更完善软件商店里可以直接安装。端口规划青龙面板默认端口 5700先确认服务器上没被占用防火墙和安全组要提前放行。注意如果你用的宝塔面板是旧版本软件商店里可能找不到 Docker 管理器或者装上了但界面功能不全。建议先到宝塔官网把面板升级到最新版再继续不要拿着旧面板硬装后面排查问题会很别扭。2. 第一步在宝塔面板上把 Docker 装到位宝塔面板现在内置了 Docker 管理器插件这是最省事的路子不需要手动去折腾 yum 源或 apt 源。但装完之后有几个细节容易忽略我一个个说。2.1 通过软件商店安装 Docker 管理器登录宝塔面板后台左侧菜单找到“软件商店”搜索“Docker”会看到 Docker 管理器这个插件。点击安装等待完成。安装过程本质上是调用系统的包管理器安装 Docker Engine 和 Docker Compose 插件。宝塔处理了源配置的问题所以这里省了不少事。但注意Docker 管理器插件只负责安装和基础管理它不会自动配置镜像加速这一步需要手动做。装完后宝塔左侧菜单会出现 Docker 入口里面有容器、镜像、网络、编排等几个子页面。你可以在图形界面里创建容器也可以在终端里用命令操作。结合我自己的经验部署阶段用命令更高效运维阶段用宝塔图形界面更直观两者结合最好。2.2 配置镜像加速国内服务器拉取 Docker Hub 镜像的速度正常的时候看运气高峰期就让人抓狂。下拉一个几百 MB 的镜像等半天最后还可能超时失败。解决方式是配置镜像加速器。修改/etc/docker/daemon.json内容如下{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com, https://docker.nju.edu.cn ] }填几个不同来源的加速地址万一某个挂了还有其他可用。这里说明一下原理Docker 拉镜像时会优先请求 daemon.json 里配置的 registry-mirrors镜像加速器会帮你从 Docker Hub 缓存一份然后再传给你。这样比直连 Docker Hub 快得多。改完文件后执行下面的命令让配置生效systemctl daemon-reload systemctl restart docker2.3 验证 Docker 状态配置完成后在宝塔终端里跑几个命令验证docker version docker ps docker infodocker version能正常显示 Client 和 Server 版本号说明 Docker 服务在运行docker ps能显示出空列表而不是报连接错误说明命令行能正常连上 Docker daemondocker info里可以确认镜像加速器是否生效看 Registry Mirrors 一栏是否有刚才填的地址。注意如果你看到的是Cannot connect to the Docker daemon的报错大概率是 docker 服务没启动。先执行systemctl start docker如果启动失败去看/var/log/messages或journalctl -u docker的日志常见的坑是磁盘空间不足、SELinux 拦截、或者内核版本过低。3. 第二步用 Docker 拉取并运行青龙面板环境就绪后进入正题。3.1 镜像选择青龙面板的 Docker 镜像是whyour/qinglong在 Docker Hub 上可以找到。版本方面latest标签是最新稳定版develop标签是开发版不建议生产环境用。拉镜像之前先确认架构。绝大多数服务器是 x86_64 架构直接用默认标签即可。如果你是 ARM 架构的机器比如部分国产服务器、树莓派镜像同样支持Docker 会按架构自动拉取对应版本。docker pull whyour/qinglong:latest提示拉镜像时如果速度还是很慢除了检查加速器配置还可以直接指定具体版本号比如whyour/qinglong:2.15.x。有些加速器对最新标签的缓存命中率不高指定版本号有时反而更快。3.2 创建数据目录与运行容器青龙面板的数据必须持久化也就是存到宿主机上否则容器一删配置和任务全没了。我的目录规划如下mkdir -p /opt/ql/{config,log,db,scripts,deps}这几个目录分别对应青龙面板内部的关键数据config配置文件包括 config.sh、crontab.list 等青龙面板所有核心配置都在这里。log脚本运行日志按任务名和时间分文件存放。dbSQLite 数据库文件面板的账号、任务、环境变量等结构化数据都在这。scripts脚本文件默认存放目录拉取的仓库代码也会落到这里。deps依赖管理相关的数据。目录建好后运行容器docker run -dit \ -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/deps:/ql/deps \ -p 5700:5700 \ --name qinglong \ --hostname qinglong \ --restart unless-stopped \ whyour/qinglong:latest逐条解释一下-dit后台运行分配一个伪终端并保持 stdin 开启。相当于容器在后台默默跑不占用你的终端窗口。-v把宿主机目录映射到容器内部目录。容器内部路径不能乱改这是青龙面板镜像约定的路径结构。-p 5700:5700宿主机 5700 端口转发到容器内 5700 端口。外部访问用宿主机 IP 加 5700。--name qinglong给容器起个名字后续管理用名字比用容器 ID 方便。--restart unless-stopped容器意外退出或服务器重启时自动拉起。除非你手动 stop 它否则它会一直在。--hostname qinglong设置容器主机名主要用于日志区分不设置也没问题。运行完以后执行docker ps看到qinglong容器的 STATUS 是Up说明启动成功了。如果 STATUS 一直显示Restarting说明容器内部启动失败在反复重启这时候用docker logs qinglong看日志排查。3.3 第一次启动与初始化容器起来后访问http://你的服务器IP:5700会进入安装向导。安装向导第一步是设置通知方式这里可以选择跳过。通知方式后面在面板里随时能改不着急。第二步会创建管理员账号和密码。这里强调一下账号密码默认是不需要重复确认的填完就直接创建。很多人习惯性地在密码框里填两遍结果第二遍的输入实际是登录密码的一部分导致登录失败。确认密码框只有一个细心一点。创建完账号后系统会自动跳到登录页。用刚才设置的账号密码登录就进入了青龙面板的主界面。到这里一个最简版的青龙面板就已经跑起来了。但离正常使用还差一步——配置依赖环境。4. 第三步面板基础配置与依赖补全青龙面板的 Web 界面主要分为几个区域侧边栏有定时任务、订阅管理、环境变量、依赖管理、脚本管理、系统设置、日志等。每个功能的用途我在用的过程中总结如下。4.1 账号安全与系统设置登录后第一件事去“系统设置”里看看基础配置通知设置支持多种推送渠道包括 Server 酱、Telegram、钉钉、企业微信、Bark 等。我建议至少配置一种特别是用 BarkiOS或 Server 酱微信的脚本跑挂了你第一时间能知道。是否开启“登录失败次数限制”建议开启防止面板暴露在公网后被暴力破解。代理配置如果你需要访问国际网络资源可以在系统设置里配置 HTTP 代理青龙面板运行时拉取订阅或脚本时会走代理。另外可以顺手把登录页的公告信息改一下写上服务器负责人和联系方式方便团队协作时识别。注意青龙面板默认的管理端口就是 5700实际使用中建议不要直接把 5700 暴露到公网。要么用防火墙限制来源 IP要么通过反向代理加 HTTPS 访问后面第 5 节我会详细展开。4.2 依赖管理最容易被忽视的环节青龙面板跑脚本绝大多数失败都不是脚本本身的问题而是容器里缺少运行环境。这一点我踩过太多次了。青龙面板内置的依赖管理可以安装三类依赖Node.js 依赖脚本使用 JavaScript 写的就需要 npm 包。比如axios、crypto-js、date-fns、tslib这类在依赖管理里添加即可。Python 依赖脚本用 Python 写的需要 pip 包。比如requests、beautifulsoup4、pycryptodome、pandas等。Linux 依赖脚本需要调用系统命令时需要安装对应的二进制工具。比如wget、curl、unzip、vim、gcc、musl-dev等。每种依赖我都遇到过头疼的情况分别记录一下。Node.js 依赖的安装速度通常很慢因为 npm 默认源访问国外。遇到这种情况可以把 npm 源切换到国内镜像。进入容器执行下面的命令docker exec -it qinglong bash npm config set registry https://registry.npmmirror.com npm install -g pnpm pnpm config set registry https://registry.npmmirror.com注意青龙面板内部对依赖的安装有些很奇怪的路径问题我遇到过明明加了依赖但脚本仍报找不到模块的情况。这时候需要进入容器手动看依赖装到了哪里。在 Docker 部署模式下建议先查一下pnpm的 store 目录路径经常需要把pnpm config set store-dir /root/.local/share/pnpm/store才能在青龙的依赖管理中正确链接。Python 依赖的坑主要在版本。青龙面板的容器内置 Python 3.10大部分pip install都能顺利通过。少数依赖库需要编译比如cryptography、bcrypt这种会报缺少gcc或者python3-dev。解决办法是先装 Linux 依赖里的gcc、g、python3-dev再重装 Python 依赖。Linux 依赖是最容易漏的。比如有的脚本要用sqlite3命令有的要用ffmpeg有的要用perl。如果你发现某条命令在日志里出现command not found先确认是哪个二进制缺失然后去依赖管理里找对应的 Linux 包名装上。给你们一个我常用的依赖清单参考并不是所有都必需按你的脚本需求来类型包名Node.jsaxios, crypto-js, date-fns, tough-cookie, ts-md5, lodash, jsdom, pinyin-proPythonrequests, beautifulsoup4, pycryptodome, python-dateutil, pillow, pymongo, redisLinuxwget, curl, unzip, tar, gcc, g, make, python3-dev, musl-dev, sqlite, vim, ffmpeg, perl这里给个经验每次新增脚本前先把脚本 README 里声明的依赖一次性装齐而不是等跑挂了再一个个补。后者会让你在“加依赖 - 等安装 - 再跑 - 又报错 - 再加依赖”的循环里浪费大量时间。4.3 订阅管理与定时任务青龙面板的定时任务和 cron 表达式直接对应熟练之后会觉得很顺手。“订阅管理”功能可以添加远程仓库的订阅面板会自动拉取仓库内容并同步任务和脚本。添加订阅时提供仓库地址选择需要拉取的分支、文件或目录并配置定时拉取频率。拉取频率建议每天或两天一次太频繁会浪费服务器资源也没有必要。“定时任务”支持手动创建。填写任务名称、脚本路径或命令、运行规则cron 表达式即可。cron 表达式如果记不熟面板里带了一个推导工具可以按固定时间、时间间隔等模式自动生成不需要死记硬背。我在使用中还发现一个细节任务的超时时间。青龙面板默认任务超时时间是 60 秒很多长时间运行的脚本跑到一半直接被判定超时杀掉了。如果你的脚本耗时较长创建任务时在“超时时间”里填一个合理的值比如 600 秒。4.4 环境变量配置环境变量是脚本的灵魂比如登录 Cookie、推送 token、API 密钥都属于环境变量。青龙面板的环境变量管理支持添加、禁用、修改和排序。环境变量按脚本的需求分散定义。关键的一点是变量是怎么被脚本读取的。青龙面板会在执行任务时把环境变量注入到脚本的进程环境中所以脚本内部通过process.env.变量名Node或os.environ.get()Python就能取到。这跟你直接在系统里export是一样的效果不会污染宿主机。如果你先删掉了某个变量后面的任务执行就会取不到值日志里会有对应的报错提示。这个靠排查设置的时候尽量规范命名给每个变量加备注说明用途半年后你会感谢自己当初的习惯。5. 第四步生产环境增强与安全加固青龙面板跑起来简单但要让它长期稳定运行还需要做几件事。我按重要程度排个序。5.1 给容器设置资源限制不限制容器的资源使用可能会出现两种情况一是脚本并发跑起来内存和 CPU 被占满其他服务跟着遭殃二是内存耗尽触发 OOM容器的进程直接被内核杀掉表现为面板突然无法访问。给已创建的容器设置资源限制docker update --memory 1g --cpus 1 qinglong这条命令把容器的内存上限设置为 1GBCPU 上限为 1 核。如果你脚本比较重可以适当调高比如--memory 1.5g --cpus 1.5。设置完之后用docker stats qinglong观察实际占用再根据脚本的运行周期调整。注意这里的资源限制是软硬结合内存是硬限制超过后容器进程会被 OOM Killer 处理。所以设置值时务必留出余量不要卡得太死。5.2 日志清理与磁盘监控青龙面板的日志按任务和日期存放跑得越多磁盘占用越大。尤其是那些每天执行多次、输出几十 MB 日志的任务几个月下来磁盘空间会非常难看。面板里日志管理页面可以对日志进行清理。系统设置里也可以打开“自动清理日志”功能定期清除超过指定天数的日志。推荐设置保留 7 天足够排查问题也不至于占用太多空间。同时建议在宝塔面板里开启磁盘监控告警达到阈值时推送通知。我自己的做法是加了一个额外的 cron 任务每天轮询一下/opt/ql/log目录的大小超过 1GB 自动压缩前一天的日志。细节不多说方向上很有效。5.3 防火墙与反向代理青龙面板的 5700 端口默认是 HTTP 明文传输且没有任何访问控制。如果你的服务器有公网 IP任何人都能扫描到这个端口进而尝试登录你的面板。所以安全这块必须重视起来。先启用宝塔面板的防火墙把 5700 端口限制为只允许特定 IP 访问或者直接不放行公网访问改为通过 Nginx 反向代理访问。反向代理方案有几个好处可以用域名加 HTTPS 访问数据加密传输。可以在 Nginx 层加 Basic Auth 或 IP 白名单多一层防护。可以隐藏后端端口和面板服务指纹。在宝塔面板里“网站” - “添加站点” - “反向代理”路径把域名指向http://127.0.0.1:5700然后为站点配置 SSL 证书即可。申请证书可以用宝塔自带的 Let’s Encrypt 免费证书非常方便。5.4 定时备份与恢复演练容器的数据目录在/opt/ql备份方式最简单直接的就是压缩这个目录tar -czf /backup/ql-$(date %Y%m%d).tar.gz /opt/ql恢复同样很简单cd / tar -xzf /backup/ql-20240101.tar.gz把备份文件同步到另一台机器或对象存储防止服务器硬盘故障导致数据全丢。恢复演练建议每次大版本升级前做一次确保备份文件可解压、可恢复。青龙面板自身的数据库在/opt/ql/db下如果只是做容器迁移重点保留config和db两个目录即可脚本可以从订阅重新拉取。5.5 青龙面板的版本升级与回滚青龙面板发布新版本后升级操作并不复杂docker pull whyour/qinglong:latest docker stop qinglong docker rm qinglong docker run -dit \ -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/deps:/ql/deps \ -p 5700:5700 \ --name qinglong \ --hostname qinglong \ --restart unless-stopped \ whyour/qinglong:latest核心思路是保留数据目录删除旧容器用新镜像重新创建容器。数据都挂载在宿主机上所以不会丢失。升级前先备份/opt/ql目录万一新版本有兼容性问题还可以用旧版镜像和备份数据快速回滚。升级完成后打开面板的“系统设置 - 版本更新”确认当前版本号是否符合预期。查看日志确认启动没有异常。6. 常见问题与排查实录这一节把我实际使用中遇到的问题集中整理一下每个问题都给出排查路径和解决方案。遇到问题别慌按顺序排查基本都能定位。6.1 镜像拉取失败或极慢现象docker pull whyour/qinglong:latest卡住不动或多次尝试后报EOF、request canceled while waiting for connection。排查顺序确认daemon.json里配置了镜像加速器且加速器地址能访问。执行curl -I https://docker.m.daocloud.io看返回码是否正常。如果加速器不可用换其他加速地址或者尝试直接从 Docker Hub 拉取有些网络环境直连反而比加速器快。拉取中途失败可以重新执行docker pullDocker 会从断点处继续不用删除已下载的层。6.2 容器反复重启现象docker ps里 STATUS 一直是Restarting或者容器起来了但几秒后退出。排查docker logs qinglong如果日志里出现Cant open file for writing多半是宿主机目录权限问题。青龙面板容器默认以 root 运行但目录如果权限不足写入会失败。解决方法chmod -R 755 /opt/ql如果日志里出现port already in use说明 5700 端口被占用。用ss -lntp | grep 5700查一下是哪个进程占用的。如果日志里出现 SQL 相关的报错大概率是db目录里已有损坏的数据库文件。删掉/opt/ql/db下的数据库文件再重启容器即可——注意先备份。6.3 脚本运行时报依赖缺失现象脚本日志里出现Cannot find module xxx或ModuleNotFoundError: No module named xxx。排查步骤去“依赖管理”页面确认对应依赖是否已安装。如果已经装了但报错进入容器手动执行node -e require(xxx)或python3 -c import xxx看是否真的可用。检查是否装错了类型。比如 Node 依赖用 Python 脚本不可能加载反之亦然。检查依赖安装是否因为网络问题失败。日志里有npm ERR!或pip install超时的话需要先换源再重装。6.4 安装依赖时 npm 报 SSL 错误现象npm install时报证书相关错误或UNABLE_TO_GET_ISSUER_CERT_LOCALLY。解决方法npm config set strict-ssl false这会影响连接安全但青龙面板容器内要安装的依赖都来自可信仓库在容器环境内风险可控。或者按之前说的把 registry 换成 npmmirror证书问题也会缓解。6.5 面板能打开但登录报错现象输入账号密码后提示“密码错误次数过多”或直接登录失败。排查方向确认是否触发了登录失败次数限制等冷却时间过后再试。确认初始密码没填错。如果实在进不去可以直接重置密码。方式是在宿主机上修改/opt/ql/config/auth.json里的账号和密码字段然后重启容器。修改前先备份auth.json 里的密码是明文存储的改的时候注意别手滑。6.6 容器时间与宿主机不一致青龙面板内的定时任务依赖容器系统时间。如果容器时间不对任务会在错误的时间触发。青龙面板官方镜像默认使用 UTC 时区国内服务器建议在启动容器时加上时区设置。在docker run命令中追加-e TZAsia/Shanghai \如果容器已经创建了进入容器内修改docker exec -it qinglong ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime docker restart qinglong6.7 排查问题时的完整命令集把常用命令整理成速查表方便关键时刻快速使用场景命令查看容器状态docker ps -a查看容器日志docker logs -f qinglong进入容器交互docker exec -it qinglong bash查看资源占用docker stats qinglong重启容器docker restart qinglong停止容器docker stop qinglong删除容器docker rm qinglong检查端口占用ss -lntp | grep 5700查看挂载是否生效docker inspect qinglong | grep -A5 Mounts7. 个人实操心得与几点建议最后聊点实话。青龙面板用 Docker 部署最大的价值不是省掉了那几行安装命令而是给了你一个可以随手重建、随时回滚、不污染宿主机环境的工作流。我经历过裸机部署时因为系统 Python 版本升级导致所有定时任务罢工的事情也经历过脚本依赖互相冲突导致整个环境没法用的场景换了 Docker 之后这些问题再没出现过。几个建议供参考第一目录规划一定要从一开始就固定下来。/opt/ql这个路径用熟了就别换来换去迁移和备份都方便。如果服务器上有多个项目建议用/opt/ql这种目录级命名而不是随意散落在根目录下。第二依赖管理遵循“够用就行不要贪多”。有人为了省事把所有依赖一口气全装了结果容器体积膨胀拉取和启动都变慢。按实际脚本需求装缺什么补什么反而更可控。第三养成看日志的习惯。青龙面板的每个任务都有完整运行日志脚本跑挂了不要第一时间怀疑面板问题先看任务日志最后几行的报错信息。大多数情况下问题出在脚本本身而不是面板或容器。第四升级前一定要备份。我自己的流程是备份/opt/ql目录 - 拉新镜像 - 重建容器 - 观察半天运行状态 - 确认没有问题后再把旧镜像清理掉。这套流程走下来几乎没有翻过车。这篇文章里涉及的部署路径和命令都是我自己在真实环境中反复验证过的。照着做大概率能顺利跑起来。如果你在实际部署中遇到这篇文章没覆盖的问题把容器日志里的关键报错拿出来对比排查方向对了问题就解决了一半。