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_COOKIE=pt_key=xxx;pt_pin=xxx; JD_COOKIE=pt_key=yyy;pt_pin=yyy;注意同一个变量名可以有多行，脚本会自动遍历所有值。如果你有多个账号，就写多行。导入之后记得点保存，然后可以在脚本里测试一下能不能读到。
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 'xxx'，Python 脚本报错通常是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 里叫requests，Node.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 依赖版本冲突的处理经验
有些脚本对依赖版本有要求，比如必须用axios@0.21.1而不能用最新版。如果你装了最新版，脚本可能报错。这种情况下，你需要在安装时指定版本：
npm install axios@0.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 的云服务器或者家里的旧设备就够了。没必要为了这个专门买高配机器。稳定性比性能重要得多，一个常年开机、网络稳定的低配设备，比一个经常重启的高配设备好用。
青龙面板这个工具本身是成熟的，社区也活跃，遇到问题基本都能搜到答案。关键是你要理解它的运行逻辑：脚本是执行单元，环境变量是配置来源，依赖是运行基础，通知是反馈渠道。把这四件事理顺了，剩下的就是耐心调试。我到现在还在用的几个脚本，都是调通之后就没再动过，每天自动跑，偶尔看一眼推送，省心得很。
