Linux 本机部署#

支持 Debian、Ubuntu、Alpine。启动过程会安装系统依赖并配置 nginx 等服务，建议使用专用环境。预先安装 Node.js、npm、Python3 和 pip3；运行用户需要管理系统依赖和服务的权限。2.24.0 的 npm 面板包已在 Node.js 20 与 24 上验证，面板及脚本依赖使用 pnpm 8.3.1。独立远程 CLI 需要 Node.js 22.12 或更高版本。默认容器使用 Python 3.11，本机部署需选择与用户脚本兼容的 Python 版本。

安装并设置路径#

安装 2.24.0：

npm install -g @whyour/qinglong@2.24.0

安装完成后，设置路径并启动：

export QL_DIR="$(npm root -g)/@whyour/qinglong"
export QL_DATA_DIR="$HOME/qinglong/data"
mkdir -p "$QL_DATA_DIR"
qinglong

QL_DIR 是面板安装目录，QL_DATA_DIR 是持久化数据目录，必须为绝对路径且以 /data 结尾。使用执行安装的同一用户和 npm 环境；不要把路径设置为空。将两个变量保存到实际启动面板的用户或服务环境中，以便重启后继续使用。

启动后访问 http://localhost:5700，完成初始化并创建第一个任务。

@whyour/qinglong 安装面板；@whyour/qinglong-cli 安装远程客户端，二者都提供 ql。远程管理请按 CLI 使用指南选择独立入口。

升级前备份完整数据，并保持 QL_DATA_DIR 指向原数据目录。需要 Python venv 隔离时，可按原生部署说明配置本机环境。Docker 部署按容器安装指南拉取新镜像并重建。依赖出现加载错误时，在依赖管理中重新安装对应依赖并查看日志。