青龙面板安装部署与系统优化指南

一、 青龙面板安装部署

青龙面板通常建议使用 Docker 或 Podman 进行容器化部署，以便于管理与环境隔离。

1. 配置文件 podman-compose.yml

在你的香橙派上创建一个项目目录（如 ~/qinglong），在该目录下新建 podman-compose.yml：

version: '3'
services:
  qinglong:
    image: docker.io/whyour/qinglong:latest
    container_name: qinglong
    restart: always
    tty: true
    logging:
      driver: none
    ports:
      - "5700:5700"
    environment:
      - QL_DIR=/ql
      - QL_CONTAINER=true
      - TZ=Asia/Shanghai
      # 【新增】降低部分底层工具的日志输出粒度
      - NODE_ENV=production
      # 【可选】禁用青龙自动化调试/监控输出
      - DISABLE_PANEL_LOG=true
    volumes:
      - ./data:/ql/data
    # 【新增】将容器内的临时目录挂载到内存，内存占用极小（上限 64MB/128MB），零磁盘 IO
    tmpfs:
      - /tmp:exec,size=64M
      - /ql/data/tmp:exec,size=128M

注意：由于 Inspect 信息显示新版青龙声明的持久化数据卷路径是 "Volumes": { "/ql/data": {} }，这里直接挂载单个 ./data 目录即可涵盖所有的脚本、日志、数据库和配置，比老版本零散挂载 7 个子目录更干净方便。tty: true（终端模拟）：控制的是容器内部进程的输出行为。它让容器内的脚本和进程以为自己运行在一个真实的 Terminal 中，从而生成带有格式、颜色（ANSI 颜色代码）的日志，并保持主进程不退出。

2. 部署与启动命令

在 podman-compose.yml 所在的目录下执行以下命令：

创建数据挂载目录并赋予权限

避免 Podman（特别是无根模式 Rootless）在初始化时遇到文件写入权限报错：

mkdir -p data && chmod 777 data

2.1. 青龙面板内部设置（最关键：控制脚本日志与保留天数）

进入青龙 Web 面板 -> 对比并修改以下系统设置：

① 缩短日志保留天数（降低磁盘积累）

• 路径：系统设置 -> 系统设置 -> 日志保留天数
• 建议设置：修改为 3 天 或 7 天（默认通常较长）。
• 效果：青龙每日清理任务会自动删掉过期的历史运行日志，避免日志文件无限膨胀挤爆存储。

② 调整日志输出模式（减少写磁盘频率）

• 路径：系统设置 -> 系统设置 -> 日志控制
• 建议设置：
• 关闭/禁用“合并日志”（避免额外的日志拼接和文件复制操作）。
• 清空/关闭不需要的推送通知日志。

2.2. 定时任务配置优化（避免并发 IO 暴顶）

青龙在多个脚本同一秒/同一分钟同时触发时，会瞬间拉高 CPU 负载并产生剧烈的并发磁盘读写。

① 错开 Cron 表达式（分散执行）

• 现象：很多默认脚本的 Cron 表达式都是 0 0 * * *（半夜 12 点整执行）。
• 优化：编辑脚本的定时规则，把分钟和秒数打散。例如：
• 修改前：0 0 * * *（00:00 集中爆发）
• 修改后：23 4 8 * * *（上午 08:04:23 执行，避开整点高峰）

② 限制最大并发执行数

• 路径：系统设置 -> 系统设置 -> 最大并发任务数
• 建议设置：对于香橙派这类低功耗设备，建议将最大并发数限制为 **2 或 3**。
• 效果：当有大量任务同时到期时，青龙会排队执行，而不是同时启动十几个 Node.js/Python 进程把 CPU 和 IO 彻底卡死。

2.3. 挂载内存临时文件系统（Tmpfs 方案：将高频写操作放进内存）

青龙运行脚本时，会在 /ql/data/tmp 和 Linux 的 /tmp 产生大量一次性临时文件。把这些临时目录挂载到内存（RAM）中，写操作将完全不经过 SD 卡/闪存。

二、 初始化配置与运行依赖管理,依赖可装可不装，跑任务时候，报错，再装也行

完成部署后，通过浏览器访问 http://<宿主机IP>:5700 进入初始化引导。

1. 初始化设置

• 通知设置：可在初始化阶段跳过，后续在系统设置中统一配置。
• 账户设置：设置管理员用户名和强密码。

2. 基础依赖安装

多数自动化脚本依赖基础运行环境，需在 依赖管理 中添加对应依赖：

Python3 常用依赖

进入 依赖管理 $\rightarrow$ Python3 $\rightarrow$ 新建依赖，依次安装：

• requests
• pycryptodome
• canvas

Node.js 常用依赖

进入 依赖管理 $\rightarrow$ Node.js $\rightarrow$ 新建依赖，依次安装：

• axios
• crypto-js
• ts-node

三、 系统设置与推送优化

1. 统一通知渠道设置

通过系统级通知设置，可让面板内所有任务共享同一个推送通道，避免在每个脚本的环境变量中重复配置。

• 配置路径：系统设置 $\rightarrow$ 通知设置
• 配置方式：
• Telegram 方案：填入 Bot Token 与 Chat ID。
• 国内直连方案（如 Server酱 / PushDeer / PushPlus）：直接填入对应的 Key 或 Token。
• 环境变量清理：若使用系统统一通知，建议删去环境变量中脚本私有的推送变量（如 TG_BOT_TOKEN），防止脚本自身触发网络请求超时。

2. 网络代理设置（针对 Telegram 国内连接失败问题）

若青龙面板部署在国内网络环境，直连 Telegram API 会出现超时报错。可采取以下优化方案：

方案一：全局网络代理

在青龙面板 环境变量 中添加代理服务器配置，使容器流量通过代理转发：

方案二：使用反向代理 API

在系统通知设置中，将 Telegram 的默认 API 地址 [https://api.telegram.org](https://api.telegram.org) 替换为可用的 Telegram 反代域名。