README

青龙

简体中文 | English

支持 Python3、JavaScript、Shell、Typescript 的定时任务管理平台

Timed task management platform supporting Python3, JavaScript, Shell, Typescript

[![npm version][npm-version-image]][npm-version-url] [![docker pulls][docker-pulls-image]][docker-pulls-url] [![docker stars][docker-stars-image]][docker-stars-url] [![docker image size][docker-image-size-image]][docker-image-size-url]

[npm-version-image]: https://img.shields.io/npm/v/@whyour/qinglong?style=flat
[npm-version-url]: https://www.npmjs.com/package/@whyour/qinglong?activeTab=readme
[docker-pulls-image]: https://img.shields.io/docker/pulls/whyour/qinglong?style=flat
[docker-pulls-url]: https://hub.docker.com/r/whyour/qinglong
[docker-stars-image]: https://img.shields.io/docker/stars/whyour/qinglong?style=flat
[docker-stars-url]: https://hub.docker.com/r/whyour/qinglong
[docker-image-size-image]: https://img.shields.io/docker/image-size/whyour/qinglong?style=flat
[docker-image-size-url]: https://hub.docker.com/r/whyour/qinglong

Demo / Issues / Telegram Channel / Buy Me a Coffee

演示 / 反馈 / Telegram 频道 / 打赏开发者


!cover

 功能

- 支持多种脚本语言（python3、javaScript、shell、typescript）
- 支持在线管理脚本、环境变量、配置文件
- 支持在线查看任务日志
- 支持秒级任务设置
- 支持系统级通知
- 支持暗黑模式
- 支持手机端操作
- 支持通过 远程 CLI 与 Agent Skill 管理面板

 版本

 docker

latest 镜像是基于 alpine 构建，debian 镜像是基于 debian-slim 构建。如果需要使用 alpine 不支持的依赖，建议使用 debian 镜像

⚠️ 重要提示: 如果您需要以非 root 用户运行 Docker，请使用 debian 镜像。Alpine 的 crond 需要 root 权限。

bash
docker pull whyour/qinglong:latest
docker pull whyour/qinglong:debian


使用 debian 镜像以非 root 用户运行时，需指定 --user qinglong：

bash
docker run -d \
  -v /path/to/ql/data:/ql/data \
  -p 5700:5700 \
  --user qinglong \
  --name qinglong \
  whyour/qinglong:debian


 npm

npm 版本支持 debian/ubuntu/alpine 系统，需要自行安装 node/npm/python3/pip3/pnpm

bash
npm i @whyour/qinglong


 部署

查看文档

 内置 API

查看文档

 内置命令

查看文档

 远程 CLI 与 Agent Skill

使用独立 npm 包 @whyour/qinglong-cli，可以从本机终端或自动化流程管理远程青龙面板。支持任务与订阅的创建、修改、运行和日志查看，以及应用、环境变量、脚本、配置、依赖等 OpenAPI 资源；JSON 输出便于脚本和 AI Agent 使用。

需要 Node.js =22.12，推荐 Node.js 24。安装后使用 ql 命令：

bash
npm install -g @whyour/qinglong-cli
ql login --url https://ql.example.com
ql auth status --json
ql task list --json
ql subscription list --json
ql --help


在面板「系统设置 → 应用设置」创建应用并授予所需权限，登录时按提示输入 Client ID/Secret；也支持通过 QL_URL 和 QL_ACCESS_TOKEN 使用已有令牌。各命令支持 --help，QL_LANG=en 可切换英文帮助。

npm CLI 用于远程管理。面板内置 ql 同样使用这个命令名，已有面板的机器请使用独立安装目录，避免覆盖内置命令。本机脚本执行和运维见 面板内部工具。

CLI 中文说明 · English guide · 完整命令参考

包内附带 远程管理 Skill，涵盖认证、命令选择和操作结果检查，可供 AI Agent 使用。本机执行与运维另见 内部 Skill。

 开发

bash
git clone https://github.com/whyour/qinglong.git
cd qinglong
cp .env.example .env
 推荐使用 pnpm https://pnpm.io/zh/installation
npm install -g [email protected]
pnpm install
pnpm start


打开你的浏览器，访问 

 链接

- nevinee
- crontab-ui
- Ant Design
- Ant Design Pro
- Umijs
- darkreader
- admin-server

 名称来源

青龙，又名苍龙，在中国传统文化中是四象之一、天之四灵之一，根据五行学说，它是代表东方的灵兽，为青色的龙，五行属木，代表的季节是春季，八卦主震。苍龙与应龙一样，都是身具羽翼。《张果星宗》称“又有辅翼，方为真龙”。

《后汉书·律历志下》记载：日周于天，一寒一暑，四时备成，万物毕改，摄提迁次，青龙移辰，谓之岁。

在中国二十八宿中，青龙是东方七宿（角、亢、氐、房、心、尾