青龙面板Docker部署全攻略：从定时任务到依赖管理一步到位

青龙面板这个词这两年只要是折腾过服务器或者NAS的朋友多半都听过。它本质上是个开源的定时任务管理面板把脚本调度、运行日志、依赖管理、通知推送这些东西集中到一个网页上你不用再去服务器里手敲 crontab也不用在脚本崩了之后一头雾水地翻日志。这篇教程我会直接按实际部署顺序来写把每个步骤背后的原因也一并说清楚目标是让一个刚接触 Linux 的小白也能照着把青龙面板跑起来并且知道下一步该做什么。在正式动手之前先把青龙面板的能力边界捋清楚。它做的是“定时调度 可视化管理”不适合用来当在线编辑器写复杂业务也不是数据平台。但你只要有一些现成脚本想按天、按小时、按自定义规则去执行并且把每次运行的结果存下来慢慢看那它就是目前最顺手的方案之一。我下面所有操作都基于 Docker 部署这是最省心、最不容易污染系统环境的方式也最方便以后升级和删除。1. 先搞清楚青龙面板是什么再谈安装1.1 一个定时任务工具为什么被这么多人单独部署我第一次接触青龙面板时也觉得奇怪定时任务用系统自带的 crontab 不就行了吗为什么还要专门搭一个面板实际用下来之后我发现核心差别在于“可视化”和“可维护性”。原生 crontab 的缺点很明显你只能通过命令行查看任务列表脚本报错得自己手动去翻日志文件根本没有历史运行记录、成功失败统计这种东西。更麻烦的是如果你的脚本依赖 Node.js、Python、Shell 等不同运行环境光环境配置就能折腾一晚上换一台机器又要重新配一遍。青龙面板解决的问题正是这些。它把任务统一纳入管理每次执行都有完整日志成功失败一目了然内置了依赖管理功能可以在网页上直接安装 Node.js 和 Python 的第三方库不用在服务器上反复折腾环境变量还支持配置通知推送脚本执行完可以把结果推到你的微信、钉钉、企业微信这类工具里。对个人来说它最大的价值是“降低维护成本”。你只管把脚本丢进去定时跑完看结果就行。1.2 版本怎么选青龙2.x、3.x、4.0到底差在哪青龙面板的版本演进比较快社区里能看到的版本五花八门2.x、3.x、4.0 都有人用。很多第一次接触的朋友直接卡在这一步到底该装哪个版本如果你去搜旧教程会看到很多基于 2.10、2.15 之类的部署命令这些版本在当时确实很流行但整体界面和底层依赖管理方式已经比较陈旧。3.0 版本开始界面变好看了一些依赖管理做得更细。到了 4.0配置项集中到了“系统设置”和“依赖管理”两个大模块里脚本类型分成 bash、python3、nodejs 三种还内置了配置文件编辑器整体思路清晰很多。我的建议很简单新用户无脑选官方当前最新稳定版也就是 4.0 系列。网上搜到的历史教程如果写的是 2.x 专属命令比如单独创建config.sh文件那种方案该跳过的部分就直接跳过不要为了照搬老教程而刻意装旧版本。老版本虽然稳定但新版本修复了不少问题而且社区现在的脚本大多默认适配新版本。部署时直接用latest标签或者指定4.x版本号即可。2. 部署前的准备一台Linux环境和一个好习惯2.1 服务器或NAS的最低要求青龙面板本身非常轻量不像那些吃内存的中间件它对硬件的要求低到有点超出直觉。我自己在一台 1 核 1G 的云服务器上跑过面板加日常任务完全没有压力。如果你只是跑几个低频率脚本1 核 512M 内存理论上也能带得动但为了日志存储和依赖安装时不会卡死还是建议内存不低于 1G。系统方面最省心的选择是 Debian 或 Ubuntu 这类 Debian 系系统CentOS 也能用但命令上有些区别。如果你用的是 NAS比如群晖、威联通、绿联这些一般自带 Docker 套件也可以直接部署青龙面板原理和服务器上一样。在正式安装前最好先登进服务器确认网络和基础环境。用curl -I https://www.baidu.com这种命令检查外网连通性如果连基础外网都不通后面拉取镜像和安装依赖都会失败。2.2 Docker 安装与基础环境检查青龙面板官方推荐用 Docker 部署这不仅仅是为了省事更重要的是隔离运行环境。就算你以后把整个容器删掉也不影响宿主机的系统环境反过来也是一样。先检查服务器上有没有装过 Docker执行docker -v。如果提示找不到命令就需要先安装。Debian/Ubuntu 系统可以执行sudo apt update sudo apt install docker.io -y sudo systemctl enable docker sudo systemctl start docker装完后再执行docker --version确认一下。之后还有一件很容易被忽略的事检查一下磁盘剩余空间执行df -h看看根分区还剩多少。Docker 镜像、容器日志、脚本运行日志都会占用磁盘建议至少留 10G 以上的空闲空间否则跑一阵子之后可能会出现日志撑爆磁盘的情况。注意很多云服务器默认登录的是普通用户安装 Docker 需要使用 sudo 获取管理员权限。如果后续所有命令都提示权限不足先检查自己是不是漏了 sudo。我见过不少新手把权限问题当成部署问题排查半天结果只是命令没加 sudo。2.3 目录规划比命令本身更重要部署命令看似简单但没有规划好数据目录后面升级、备份、清日志都会很痛苦。青龙面板的所有数据都会写入挂载的目录里包括数据库、配置文件、依赖库、日志所以一开始就要想好这个目录放在哪里。我习惯用/opt/qinglong作为数据根目录你也可以换成任意你顺手的路径但一旦定下来就不要随便改。在这个目录下青龙面板会自动生成config、log、scripts、db等子目录。其中config存放面板配置包括登录账号和密钥信息db是 SQLite 数据库文件目录scripts是脚本目录log是所有任务日志。理解这个目录结构对后面做备份特别重要整个/opt/qinglong目录拷走就等于做了一次完整备份。在部署之前可以先把目录创建好sudo mkdir -p /opt/qinglong这个空目录会作为 Docker 数据卷挂载进容器后面部署命令直接指定它就行。3. 使用Docker部署青龙面板的完整步骤3.1 镜像选择官方镜像和第三方集成镜像关于镜像网上能搜到很多第三方集成镜像有的号称“内置几十个脚本”“一键运行”这种听着很爽但我不建议新手使用。第三方镜像的问题在于你无法完全确认镜像里面装了什么存在安全风险而且一旦脚本更新换代集成镜像维护不及时问题会非常多。用官方镜像最稳。Docker Hub 上的官方镜像名为whyour/qinglong这条路是社区公认的默认选择。安装时可以通过指定标签来控制版本最简单的做法是用latest拉取当前最新版docker pull whyour/qinglong:latest如果你愿意更保守一点可以先docker pull whyour/qinglong看下默认标签或者直接用固定的版本号标签。我不建议在生产场景中使用latest但青龙面板这种个人工具场景用latest反而能保证功能不过时。3.2 docker run核心参数逐项拆解拉取完镜像后直接执行下面的命令启动一个容器。这是最基础但也是最完整的 Docker 启动命令每一段都可以拆开理解docker run -dit \ --name qinglong \ --hostname qinglong \ --restart unless-stopped \ -p 5700:5700 \ -v /opt/qinglong:/ql/data \ -e TZAsia/Shanghai \ whyour/qinglong:latest逐项解释一下-dit-d表示后台运行-i保持交互模式-t分配一个伪终端。加不加-it会影响少数场景下的进程行为加了更保险。--name qinglong给容器起个名字方便用docker logs qinglong之类命令操作。名字可以随便改。--hostname qinglong设置容器的主机名。默认情况下容器主机名是一串随机字符串设置成固定名称会让面板内部的运行标识更清晰。--restart unless-stopped容器退出后自动重启除非你手动 stop。这是保证服务器重启之后青龙面板能自动恢复的关键参数。-p 5700:5700把宿主机 5700 端口映射到容器内 5700 端口。冒号左边是宿主机端口右边是容器端口正常情况下不需要改。如果宿主机 5700 端口被占用可以把左边改成其他值比如-p 5701:5700之后访问的时候就是http://服务器IP:5701。-v /opt/qinglong:/ql/data把宿主机/opt/qinglong目录挂载到容器内/ql/data。这个目录是面板的数据目录所有配置、日志、脚本都在里面。目录映射关系必须正确这是数据不丢的关键。-e TZAsia/Shanghai设置容器时区为中国时区。如果不设置容器默认可能是 UTC 时间比你本地时间慢 8 小时定时任务会全部错乱。关于端口再补充一句如果服务器有防火墙光映射端口还不够还得在云控制台和系统防火墙里放行对应端口否则外网还是访问不了。我碰到过很多次部署成功但访问不了的情况最后发现都是云安全组没放行 5700 端口。3.3 部署后的初始化设置容器启动后打开浏览器访问http://服务器IP:5700第一次访问会进入安装向导界面。这个过程没有太多坑按提示设置登录邮箱或者用户名、密码即可但有两个细节值得注意。第一初始安装时面板会让你配置通知方式。这一步我建议先跳过等面板完全跑起来之后再在“系统设置”里慢慢配不然填错通知参数会影响初始化流程。第二安装完成后建议立刻在“系统设置”里修改一下密钥和令牌相关的安全选项。默认情况下面板会生成一个长期有效的 token如果后续通过 API 访问这个 token 很重要要妥善保存不要泄露给陌生人。我见过有人把面板暴露在公网后token 又被脚本扒走导致面板里的脚本被人偷偷改掉。初始化完成之后可以用docker ps查看容器状态如果显示Up说明容器在正常运行。再用docker logs qinglong --tail 100看启动日志确认没有异常报错。4. 面板首次使用必做的3件事依赖、脚本、定时4.1 依赖管理面板里最容易被忽视的核心功能面板装好之后很多人急着往里面丢脚本结果脚本一运行就报“找不到 xxx 模块”这就是依赖没装好的典型表现。青龙面板把依赖管理单独做成了一个模块你可以在网页上选中“依赖管理”然后分别对Node.js、Python3、Linux三类依赖进行安装。这里说的“依赖”本质上是脚本运行时需要的第三方库熟悉编程的朋友可以把它理解成pip install和npm install在做的事。比如很多基于 Node.js 的脚本会用到axios发网络请求用到png-js处理图片验证码Python 脚本会用到requests或pandas。这些库不会凭空存在必须在面板面板里安装好。在“依赖管理”里创建依赖时你需要选择类型、填写依赖名称、选择拉取方式然后点击安装。常见的 Node.js 依赖有axios、crypto-js、png-js、ts-md5、typescript、jsdom、moment这类Python 依赖有requests、urllib3、pycryptodome、prettytable、pyOpenSSL这些Linux 依赖一般装的是系统命令比如vim、wget、curl、gcc、python3-dev等。有一点非常重要依赖的版本号不要随意指定太高的不兼容版本。青龙面板的依赖管理支持填写具体版本号比如axios0.21.1。按我的经验直接装最新版有时候会遇到某个库刚升级导致的不兼容问题反而不如装一个社区脚本普遍在用的版本稳定。等你对整个环境很熟之后再按需调整版本。安装完成的依赖并不会永久生效如果你的容器是从老版本升级上来的可能需要重新安装一遍。这部分没有办法完美避免只能在一开始就养成记录依赖清单的好习惯。最好的办法是在面板里把所有依赖名称记下来写进部署文档下次重建容器时直接照着装。4.2 脚本从哪里来手动创建、订阅仓库、单脚本拉取青龙面板的脚本管理逻辑非常清晰分为几种方式适合不同场景。第一种是手动创建脚本。在“脚本管理”里新建文件把代码粘贴进去保存后到“定时任务”里订阅或新建任务即可。适合你手里已经有现成代码文件的情况也适合调试一个刚写好的小脚本。第二种是从代码仓库拉取也就是“订阅管理”。青龙面板支持配置脚本仓库 URL定时拉取整个仓库到本地。这种方式适合你长期跟踪某个开源脚本项目项目更新后可以同步拉取最新内容。订阅管理里需要填仓库地址、分支、拉取间隔等参数还可以在白名单和黑名单里过滤不想拉取的文件。拉取完成后脚本会进入到scripts目录你可以到定时任务列表中直接添加为新任务。第三种是单脚本拉取也叫“拉取单个脚本”。如果你只需要某个仓库里的一个文件不用整个仓库拉下来在定时任务或脚本管理里填上脚本的直链即可。这种方式更加轻量但前提是你知道脚本的可靠直链。在实际使用中我很不建议无视来源一梭子拉取一堆脚本。有些仓库为了“方便”会在拉取后自动执行部署脚本这类操作存在很高风险轻则脚本跑不了重则可能造成信息泄露。只拉取你确实需要并且看过的脚本这个原则怎么强调都不过分。新拉取的脚本默认不会自动执行需要去“定时任务”里手动创建一条任务选择对应的脚本文件和执行命令再配上 Cron 表达式才会按照规则定时跑起来。4.3 定时规则怎么填Cron表达式从入门到不踩坑青龙面板的定时任务依赖 Cron 表达式格式一共 5 个字段分别表示分、时、日、月、周。习惯看中文教程的同学可能会被这几个空格搞晕实际上规则很简单。第 1 位分钟取值范围 0-59。第 2 位小时取值范围 0-23。第 3 位一个月中的第几天取值范围 1-31。第 4 位月份取值范围 1-12。第 5 位星期几取值范围 0-7其中 0 和 7 都表示周日。举例来说15 8 * * *表示每天 8 点 15 分执行。*/30 * * * *表示每 30 分钟执行一次。0 2 * * 1表示每周一凌晨 2 点执行。0 0 1,15 * *表示每月 1 日和 15 日的 0 点执行。这里“踩坑重灾区”有两个第一不要忘记青龙面板的时区设置。你设置了TZAsia/Shanghai之后面板会按照本地时间解释 Cron 表达式否则定时任务会整体慢 8 小时。第二填写任务时如果你不确定时间规则可以先点一下“运行”看任务能不能正常跑起来再配 Cron 规则避免配好了但任务一直不执行。5. 从部署到运行最常见的6个问题与排查方式5.1 一直提示“密码错误”到底卡在哪“青龙一直报密码错”这句话我在各个社区里看过无数次。遇到这种情况先别急着怀疑自己密码不对按顺序排查下面几步先确认你访问的是不是面板配置后的初始化页面。如果初始化没有完成你输入的“账号”可能只是临时信息跟后续登录用的账号不一致。解决办法是删掉容器数据目录后重新初始化或者用命令行查看数据库里实际记录的账号。再检查浏览器缓存和本地存储。青龙面板会把登录凭证存储在本地有时候旧的 token 跟当前面板状态不匹配就会一直提示密码错误。试一下无痕模式或者换个浏览器把缓存清干净再登录。还有一个容易被忽略的问题如果你用了反向代理并且代理没有正确转发 WebSocket 请求面板可能表现为登录失败或页面一直转圈。这一点在 Nginx 反代时尤其明显需要在反代配置里加上对 WebSocket 的支持。如果以上都不行那就是账号密码本身记错了。青龙面板支持通过数据目录下的文件重置密码你可以直接查看config目录下的配置文件或者在容器内执行命令重置登录信息。具体命令以当前版本官方文档为准但原理都是定位到数据库文件把密码字段清掉后重新走初始化流程。5.2 浏览器进不去面板或页面一直转圈能执行docker run成功不代表一定能通过浏览器访问。先看宿主机端口是否正常执行ss -tlnp | grep 5700如果看不到 5700 监听要么容器启动了但内部服务没起来要么端口映射参数写错了。执行docker logs qinglong --tail 200看下日志如果能正常显示“服务已启动”之类的信息问题多半出在防火墙和安全组。云服务器有个经典坑系统防火墙ufw/firewalld和云控制台的安全组是两层独立的规则必须都放行 5700 端口才行。你可以先在服务器本机执行curl http://127.0.0.1:5700能通就说明面板本身没毛病接着检查安全组和防火墙即可。如果是从外部访问域名访问还有一种情况是 DNS 解析没生效或者 CDN 缓存了旧响应。本地临时用curl -I http://IP:5700直接访问可以快速区分问题出在面板还是出在链路中间。5.3 依赖安装失败或脚本一跑就报错依赖安装失败最常见的是网络问题尤其是默认npm和pip使用的官方源在部分地区拉取慢甚至拉不动。青龙面板在“依赖管理”里可以设置自定义镜像源。npm 可以换成国内镜像地址pip 也可以换成国内 PyPI 镜像地址。这个操作能解决 80% 的依赖安装失败问题。当然换源本身只是让网络请求更顺畅如果脚本本身有语法错误或者脚本需要特定版本的依赖安装成功也照样会运行报错。遇到脚本报错千万不要只看“失败了”三个字点开运行日志找到具体堆栈信息。截一段日志下来搜索关键词基本都能找到原因。还有一个容易被忽略的坑是青龙面板的脚本执行环境与宿主机隔离。如果脚本依赖某个系统命令比如ffmpeg你不能直接在宿主机上apt install ffmpeg就完事因为容器内部用的是另一套环境。这时候必须在面板的“依赖管理”里通过 Linux 依赖安装或者在 Dockerfile 层面处理。你在宿主机上安装的软件对容器内部一点影响都没有。5.4 时区、日志、容器重启这些细节时区问题我已经提过服务启动时如果不加TZAsia/Shanghai后续所有定时任务都会出现 8 小时偏移。如果你容器已经起来了可以通过在面板“系统设置”里修改时区或者把容器删掉重建重新加上环境变量。注意只是重启容器并不会补上环境变量必须重新创建容器。日志文件膨胀是长期运行的另一个隐患。青龙面板的日志会按天累积短时间还好跑上几个月之后log目录可能占用好几个 G。建议定期看看/opt/qinglong/log目录大小如果发现某个脚本日志特别大就在面板“日志管理”里清理一下。想省事的话也可以设置定时任务定期压缩或清理旧的日志文件。容器升级方面我习惯的做法是先docker stop qinglong再用新的镜像docker run启动一个新的容器并且挂载同一个/opt/qinglong数据目录。因为数据都在宿主机上容器本身重置并没有影响。升级前务必手动备份config和db两个目录这份习惯能在版本升级出幺蛾子的时候救你一命。5.5 安全加固不要让面板裸奔在公网青龙面板本身没有内置完善的账号锁定和多因素认证机制如果直接暴露在公网很容易被扫描器盯上然后尝试弱口令登录。面板里保存的脚本可能包含各种密钥和 API 凭据一旦被拿走影响面很大。最稳妥的办法就是不要把 5700 端口直接暴露到公网。如果只有你自己用就让它只在内网或本机可访问配合内网穿透或者虚拟局域网工具访问。如果实在需要公网访问至少要设置一个复杂的随机密码并且定期更换。有条件的话加一层反向代理并配置访问认证会更放心一些。还有一个小习惯值得培养所有从网上下载的脚本第一次运行前都应该读一遍代码。青龙面板的脚本管理上手门槛很低导致很多人习惯“拉来就跑”。但脚本的本质是命令它会以你服务器的权限执行里面的行为只有你亲眼见过才敢信任。这不是劝你因噎废食而是让你掌握基本的代码审阅能力至少看到明显可疑的下载和执行外部命令逻辑时知道避开。写在最后的一点经验青龙面板真正让人省心的地方不是它有多炫酷而是它把部署和运维的门槛降到了相当低的水平让我可以把更多精力放在脚本本身和业务流程上。我实际用了这么久最大的体会就是一开始多花十分钟把目录规划好、依赖清单记好、安全策略想好后面能省出来的是几十倍的时间。如果你刚把面板跑起来别急着堆脚本先把一个最简单的任务跑通比如定时输出一行日志感受一下整个流程。再把依赖管理、通知推送、日志查看这些基础功能摸清楚。慢慢你就能理解为什么一个定时工具会被这么多人反复讨论也自然知道后续该怎么扩展自己的脚本了。