青龙面板从部署到脚本配置：Docker定时任务管理实战指南

1. 青龙面板到底解决了什么问题以及它适合谁来折腾如果你手里有一台常年开机的设备——不管是家里的旧笔记本、树莓派、NAS还是一台便宜的云服务器——那么青龙面板大概率是你把定时跑脚本这件事做得最省心的方案之一。它的本质是一个带 Web 界面的定时任务管理平台把脚本文件、环境变量、依赖安装、日志查看、通知推送这几件事整合到了一个浏览器页面里。你不用再登录服务器敲 crontab也不用为了改一个参数去翻半天配置文件。很多人第一次接触青龙面板是因为想跑一些电商平台的日常任务脚本比如签到、领豆、做任务领积分这类重复性操作。这些脚本本身并不复杂但麻烦的地方在于脚本需要 Node.js 或 Python 运行环境、需要一堆第三方依赖库、需要定期更新、需要把账号凭证安全地存起来、还需要在跑完之后知道结果。青龙面板把这些环节全部收拢了你只需要在网页上点几下就能完成过去要折腾半天的配置。这篇文章适合三类人看第一类是刚拿到一台设备、想从零把青龙面板搭起来的新手第二类是已经装好了面板但脚本跑不起来、依赖装不上、通知收不到的半吊子用户第三类是想把面板用得更稳、更安全、更省心的老用户。我会从环境准备讲到脚本配置再讲到依赖管理和通知推送中间穿插我自己踩过的坑和实测有效的做法。整个过程不涉及任何敏感内容纯粹是技术层面的经验分享。需要提前说明的是脚本的具体功能取决于脚本本身不同脚本对环境和依赖的要求差异很大。我下面讲的是通用的配置思路和排查方法你拿到任何脚本都可以套用这套逻辑去处理。2. 部署前的环境准备系统选择、依赖安装与网络细节2.1 系统选择为什么 Ubuntu 和 Debian 是首选青龙面板官方推荐在 Linux 环境下运行Windows 虽然也能通过 Docker 跑但长期稳定性和资源占用都不如原生 Linux。我实测下来Ubuntu 22.04 LTS 和 Debian 12 是最省心的两个选择。原因有三点一是这两个系统的软件源里 Docker 和 Node.js 的版本都比较新装依赖不容易出问题二是社区里绝大多数教程都是基于这两个系统写的遇到问题好搜三是它们的长期支持周期长不用频繁升级系统。如果你用的是群晖、威联通这类 NAS或者飞牛 OS 这类国产 NAS 系统它们底层也是 Linux可以直接在 Docker 里跑青龙面板。手机端想访问面板只要面板所在设备和手机在同一个网络里用浏览器打开http://设备IP:5700就能进。如果手机打不开九成是防火墙没放行端口或者面板绑定的是127.0.0.1而不是0.0.0.0。2.2 Docker 安装一行命令背后的逻辑我强烈建议用 Docker 方式部署青龙面板而不是直接装在系统里。原因很简单Docker 把面板和它的依赖隔离在一个容器里你系统里的 Node.js 版本、Python 版本怎么变都不会影响面板运行。哪天面板跑崩了删掉容器重新拉一个就行不会污染系统环境。在 Ubuntu/Debian 上装 Docker 的标准流程是这样的# 更新软件源 sudo apt update sudo apt upgrade -y # 安装必要工具 sudo apt install -y ca-certificates curl gnupg lsb-release # 添加 Docker 官方 GPG 密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 添加 Docker 软件源 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 Docker sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin装完之后用sudo docker run hello-world验证一下能正常输出就说明 Docker 没问题了。这里有个细节如果你在国内网络环境下拉取镜像很慢可以配置镜像加速器。具体做法是编辑/etc/docker/daemon.json加入加速地址然后重启 Docker 服务。这一步不是必须的但能显著提升拉取速度。2.3 青龙面板容器启动端口、挂载与重启策略拉取并启动青龙面板的命令如下docker run -dit \ -v /root/ql/data:/ql/data \ -p 5700:5700 \ --name qinglong \ --hostname qinglong \ --restart unless-stopped \ whyour/qinglong:latest这条命令里每个参数都有讲究。-v /root/ql/data:/ql/data是把容器内的数据目录挂载到宿主机这样你删掉容器重建时脚本、配置、日志都还在。-p 5700:5700是端口映射左边是宿主机端口右边是容器端口如果你 5700 被占用了可以改成-p 5701:5700。--restart unless-stopped是重启策略意思是除非你手动停止否则设备重启后容器会自动起来这对长期挂机很重要。启动后等十几秒浏览器访问http://你的设备IP:5700第一次会让你设置管理员账号和密码。设置完之后进入面板你会看到几个主要菜单定时任务、环境变量、脚本管理、依赖管理、日志、系统设置。接下来所有的操作都围绕这几个菜单展开。提示如果你在云服务器上部署记得在安全组里放行 5700 端口否则外网访问不了。但我不建议把面板直接暴露在公网后面会讲更安全的做法。3. 脚本从哪来、怎么放、怎么让它按你的节奏跑3.1 脚本的获取渠道与筛选原则青龙面板本身不带脚本它只是个执行器。脚本的来源主要有两种一是从代码托管平台拉取别人维护的脚本仓库二是自己写或者改。对于大多数用户来说用现成的仓库是最实际的。拉取方式是在面板的定时任务页面点新建任务在命令栏里填入拉取命令比如ql repo https://github.com/xxx/xxx.git 脚本文件名关键词 依赖库关键词 排除关键词这个ql repo命令是青龙自带的仓库管理命令它会自动把仓库里的脚本下载到/ql/data/scripts目录并且按照你给的关键词过滤。第一个参数是仓库地址第二个是你要拉取的脚本文件名匹配规则第三个是依赖文件匹配规则第四个是排除规则。如果你不填后面三个它会拉取仓库里所有脚本。筛选脚本有几个原则。第一看仓库的更新频率长期不更新的仓库脚本大概率已经失效了。第二看 issue 区如果一堆人反馈跑不通你就别浪费时间了。第三优先选那些把依赖写清楚的仓库因为依赖装不上是新手遇到最多的问题。第四不要贪多同时跑几十个脚本不仅拖慢设备还容易因为某个脚本报错导致整个面板卡顿。3.2 环境变量的配置逻辑账号凭证怎么存才安全脚本要跑起来通常需要你的账号凭证比如 Cookie、Token、手机号之类的。这些东西在青龙里是通过环境变量来管理的。你可以在环境变量页面手动添加也可以批量导入。变量名一般是脚本作者规定好的比如JD_COOKIE、JD_BEAN_SIGN_START这种。这里有个非常重要的经验不要把账号密码明文写在脚本文件里。脚本文件是会被仓库更新覆盖的你改了半天一拉取新版本就全没了。正确做法是把凭证放在环境变量里脚本运行时从环境变量读取。这样脚本更新不影响你的配置而且环境变量在面板里是加密显示的相对安全。批量导入环境变量的格式通常是每行一个比如JD_COOKIEpt_keyxxx;pt_pinxxx; JD_COOKIEpt_keyyyy;pt_pinyyy;注意同一个变量名可以有多行脚本会自动遍历所有值。如果你有多个账号就写多行。导入之后记得点保存然后可以在脚本里测试一下能不能读到。3.3 定时任务的 cron 表达式与执行策略每个脚本在青龙里都是一个定时任务你需要给它设置执行时间。青龙用的是标准的 cron 表达式五个字段分别代表分、时、日、月、周。比如0 8 * * *表示每天早上 8 点执行30 7,12,18 * * *表示每天 7:30、12:30、18:30 各执行一次。设置时间有几个讲究。第一不要把所有脚本都设在同一个时间点否则设备瞬间负载飙升容易卡死。我一般把脚本分散在一天的不同时段间隔至少 10 分钟。第二电商类脚本的执行时间要参考活动规律比如有些任务在凌晨刷新那你就设在凌晨跑。第三对于失败率高的脚本可以设置重试青龙支持在任务里配置重试次数。还有一个容易被忽略的点任务超时时间。默认情况下如果一个脚本卡住了它会一直占着资源。你可以在任务设置里配置超时时间比如 300 秒超过就自动终止。这个对防止某个脚本拖垮整个面板非常有用。4. 依赖管理为什么脚本总是报模块找不到4.1 Node.js 依赖与 Python 依赖的区别青龙面板支持 Node.js、Python、Shell 三种类型的脚本。不同脚本用不同语言写的需要的依赖也不一样。Node.js 脚本报错通常是Cannot find module xxxPython 脚本报错通常是ModuleNotFoundError: No module named xxx。这两种依赖要分别在依赖管理页面的对应标签下安装。Node.js 依赖的安装命令是npm install xxxPython 依赖的安装命令是pip3 install xxx但青龙面板提供了更简便的方式在依赖管理页面直接输入包名点安装就行。它会在后台帮你执行安装命令。不过这里有个坑有些依赖需要编译而容器里可能缺少编译工具。比如某些包依赖node-gyp需要 Python 和 make 工具。如果安装失败你可以进容器手动装docker exec -it qinglong bash apt update apt install -y python3 make g装完编译工具再重新安装依赖成功率会高很多。4.2 依赖安装失败的排查链路依赖装不上是新手最头疼的问题我把我自己的排查顺序分享出来你按这个链路走基本能定位到原因。第一步看错误日志。依赖管理页面安装失败后会有日志输出重点看最后几行。如果是404 Not Found说明包名写错了或者源里没有这个包。如果是ETIMEDOUT说明网络问题需要换源。如果是gyp ERR!说明缺编译工具。第二步检查包名。Node.js 的包名和 Python 的包名经常不一样比如 Python 里叫requestsNode.js 里叫axios。你要确认脚本作者写的是哪个语言的包。第三步换源。Node.js 可以换成国内镜像源npm config set registry https://registry.npmmirror.comPython 可以换成pip3 config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple第四步手动进容器安装。有时候面板的依赖管理界面会抽风直接进容器用命令行装反而更靠谱。装完之后重启容器让依赖生效。4.3 依赖版本冲突的处理经验有些脚本对依赖版本有要求比如必须用axios0.21.1而不能用最新版。如果你装了最新版脚本可能报错。这种情况下你需要在安装时指定版本npm install axios0.21.1但更麻烦的是多个脚本依赖同一个包的不同版本。Node.js 的依赖是装在项目目录下的理论上可以共存但青龙的依赖是全局装的就会冲突。我的做法是优先满足报错的那个脚本如果实在冲突严重就把冲突的脚本单独放到一个子目录里用独立的package.json管理。不过这属于进阶操作新手可以先忽略遇到再说。5. 通知推送怎么让脚本跑完主动告诉你结果5.1 为什么需要通知推送脚本是后台自动跑的你不可能一直盯着面板看。如果脚本失败了你不看日志根本不知道。通知推送就是让脚本在跑完之后把结果发到你常用的通讯工具上比如微信、钉钉、飞书、Telegram 等。这样你每天花一分钟看一眼推送就知道哪些脚本正常、哪些需要处理。青龙面板支持多种通知方式配置入口在系统设置里的通知设置。你需要填的是 webhook 地址或者 API key具体取决于你用哪个平台。以企业微信机器人为例你需要在企业微信里创建一个群机器人拿到 webhook 地址然后填到青龙的通知设置里。5.2 常见通知渠道的配置要点不同渠道的配置方式差异挺大我列一个对比表方便你选渠道配置难度到达率是否需要额外账号备注企业微信机器人低高需要企业微信免费稳定推荐钉钉机器人低高需要钉钉免费有频率限制飞书机器人低高需要飞书免费格式丰富Server 酱中中需要关注公众号有免费额度WxPusher中高需要注册免费支持微信Telegram Bot中高需要 Telegram需要网络条件配置的时候有几个细节要注意。第一webhook 地址要完整复制不要漏掉参数。第二有些平台对消息格式有要求比如钉钉需要加签你需要在青龙里填对应的密钥。第三测试的时候先用发送测试消息按钮验证通了再挂到脚本上。5.3 通知内容的自定义与降噪默认的通知内容可能很啰嗦每个脚本都发一条一天下来几十条消息你根本不想看。我的做法是只让失败的脚本发通知成功的脚本静默。青龙支持在任务级别配置通知策略你可以在任务设置里选择只在失败时通知。另外你可以在脚本里自定义通知内容把关键信息提取出来。比如签到脚本你可以让它只推送签到成功获得 X 个豆而不是把整个日志都发出来。这样推送既简洁又有用。6. 面板安全与长期稳定运行的关键设置6.1 不要裸奔在公网访问控制的基本做法很多人图方便直接把青龙面板的 5700 端口暴露在公网这是非常危险的。面板里存着你的账号凭证一旦被扫到后果很严重。正确的做法是面板只监听内网外网访问通过其他方式。如果你必须外网访问至少要做两件事一是改掉默认端口二是设置强密码三是开启面板的二次验证如果版本支持。更稳妥的方案是在面板前面加一层反向代理配置 HTTPS 和访问认证。比如用 Nginx 做反代加上 Basic Auth这样即使有人扫到你的域名没有密码也进不来。具体配置这里不展开但思路你要有面板本身不做公网暴露所有外网访问都经过一层认证。6.2 日志清理与磁盘空间管理青龙面板跑久了日志会占满磁盘。我见过有人跑了半年日志占了 20 多个 G最后面板卡死。解决办法有两个一是设置日志保留天数在系统设置里可以配置比如只保留 7 天二是定期手动清理在日志页面有清理按钮。另外脚本拉取的仓库也会占空间尤其是那些包含大量历史文件的仓库。你可以在脚本管理里删除不用的脚本目录。还有 Docker 的镜像和容器日志也可以用docker system prune定期清理。6.3 设备重启后面板不启动的排查设备重启后面板没起来最常见的原因是 Docker 服务没设成开机自启。你可以用systemctl enable docker来设置。如果 Docker 起来了但容器没起来检查容器的重启策略是不是unless-stopped或always。如果都设了还是不行可能是挂载目录权限问题检查/ql/data目录的属主是不是 root。还有一种情况是设备本身资源不足比如内存太小Docker 启动时被 OOM killer 杀掉了。这种情况下你需要加内存或者减少同时运行的脚本数量。7. 我踩过的几个坑和对应的解决办法第一个坑是依赖装了但脚本还是报找不到模块。后来发现是因为脚本用的是 Python 虚拟环境而我在全局装的依赖。解决办法是在脚本开头指定用系统 Python或者把依赖装到虚拟环境里。这个坑花了我一个晚上才搞明白。第二个坑是环境变量改了但脚本没生效。原因是青龙会缓存环境变量改完之后需要重启容器或者手动触发一次刷新。我现在的习惯是改完环境变量就重启一次容器虽然麻烦但不会出错。第三个坑是多个脚本同时跑导致设备卡死。我一开始把所有脚本都设在凌晨 0 点结果设备直接无响应。后来把脚本分散到不同时段并且给每个任务设了超时时间就再也没出现过。第四个坑是通知推送被平台限流。有些平台对消息频率有限制你短时间发太多会被封。解决办法是合并通知把多个脚本的结果汇总成一条消息发出去。青龙支持这种聚合通知你可以在通知设置里开启。第五个坑是脚本更新后配置丢失。这是因为有些脚本把配置写在脚本文件里更新时被覆盖了。解决办法是把所有配置都放到环境变量里脚本文件只读环境变量不存任何个性化配置。8. 关于收益和脚本选择的几句实在话最后聊几句实在的。很多人问青龙面板跑什么收益高我的回答是别指望靠这个发财。脚本能帮你省时间、薅点小羊毛但收益上限很低而且平台规则随时会变今天能跑的脚本明天可能就失效了。把它当成一个自动化工具帮你处理重复性操作这个定位是合理的把它当成赚钱工具你会失望。脚本选择上我的建议是少而精。选三五个稳定维护的仓库把依赖和环境变量配好让它们安安静静地跑。不要今天看到一个新脚本就加明天看到另一个又加最后面板里几十个任务一半是报错的你连看日志的欲望都没有了。设备方面如果你只是跑几个脚本一台 1 核 1G 的云服务器或者家里的旧设备就够了。没必要为了这个专门买高配机器。稳定性比性能重要得多一个常年开机、网络稳定的低配设备比一个经常重启的高配设备好用。青龙面板这个工具本身是成熟的社区也活跃遇到问题基本都能搜到答案。关键是你要理解它的运行逻辑脚本是执行单元环境变量是配置来源依赖是运行基础通知是反馈渠道。把这四件事理顺了剩下的就是耐心调试。我到现在还在用的几个脚本都是调通之后就没再动过每天自动跑偶尔看一眼推送省心得很。