qinglong内置命令手册：CLI操作与自动化脚本编写
项目地址: https://gitcode.com/GitHub_Trending/qi/qinglong 还在为定时任务管理而烦恼？想要通过命令行高效操作青龙面板？本文将为你全面解析青龙（qinglong）的内置命令系统，从基础CLI操作到高级自动化脚本编写，助你成为青龙面板的运维高手！
🚀 读完本文你将掌握
- 青龙内置命令的完整使用方法
- 任务管理、脚本更新的自动化技巧
- 环境变量配置与通知系统集成
- 高级脚本编写与错误处理策略
- 实战案例：自动化运维工作流搭建
📋 青龙内置命令概览
青龙提供了丰富的命令行工具，主要包含以下几个核心脚本：
| 命令文件 | 功能描述 | 主要用途 |
|---|---|---|
task.sh | 任务执行器 | 运行各种类型的脚本文件 |
update.sh | 系统更新器 | 管理脚本仓库和系统更新 |
api.sh | API接口调用 | 与青龙面板进行RESTful交互 |
share.sh | 环境配置 | 提供共享变量和工具函数 |
env.sh | 环境管理 | 环境变量存储与恢复 |
🔧 核心命令详解
1. 任务执行命令 - task.sh
task.sh 是青龙最核心的命令，负责执行各种类型的脚本文件：
# 基本用法
task <脚本文件路径> [参数]
# 示例：执行JavaScript脚本
task /ql/scripts/example.js
# 示例：执行Python脚本并传递参数
task /ql/scripts/example.py --arg1 value1 --arg2 value2
# 带日志输出
task /ql/scripts/example.js 2>&1 | tee /ql/log/example.log
支持的文件类型识别：
.js/.mjs→ 使用node执行.py/.pyc→ 使用python3执行.sh→ 使用.(source) 执行.ts→ 使用ts-node-transpile-only执行
2. 系统更新命令 - update.sh
update.sh 提供了强大的仓库管理和系统更新功能：
# 更新青龙系统
ql update
# 更新指定仓库
ql repo <仓库URL> <路径> <黑名单> <依赖> <分支> <扩展名>
# 更新单个脚本文件
ql raw <文件URL>
# 运行自定义脚本
ql extra
# 管理日志文件
ql rmlog 7 # 删除7天前的日志
# 启动消息机器人
ql bot
# 系统检测与修复
ql check
3. 环境配置详解
青龙通过 share.sh 定义了丰富的环境变量：
# 主要目录结构
export dir_root=$QL_DIR # 根目录
export dir_data=$dir_root/data # 数据目录
export dir_scripts=$dir_data/scripts # 脚本目录
export dir_config=$dir_data/config # 配置目录
export dir_log=$dir_data/log # 日志目录
# 重要配置文件
export file_config_user=$dir_config/config.sh # 用户配置
export file_auth_user=$dir_config/auth.json # 认证配置
export file_task_before=$dir_config/task_before.sh # 任务前置脚本
export file_task_after=$dir_config/task_after.sh # 任务后置脚本
🎯 自动化脚本编写实战
1. 基础任务脚本示例
JavaScript任务脚本：
// 示例：简单的数据采集任务
const axios = require('axios');
async function main() {
try {
console.log('🚀 开始执行数据采集任务');
const response = await axios.get('https://api.example.com/data');
console.log('📊 数据获取成功:', response.data);
return { success: true, data: response.data };
} catch (error) {
console.error('❌ 任务执行失败:', error.message);
return { success: false, error: error.message };
}
}
main().then(console.log);
Python任务脚本：
#!/usr/bin/env python3
# 示例：数据处理任务
import requests
import json
import time
def main():
print("🐍 Python任务开始执行")
try:
# 执行数据获取
response = requests.get('https://api.example.com/data', timeout=30)
data = response.json()
# 数据处理逻辑
processed_data = process_data(data)
print(f"✅ 任务完成，处理了 {len(processed_data)} 条数据")
return {"status": "success", "count": len(processed_data)}
except Exception as e:
print(f"❌ 任务执行失败: {str(e)}")
return {"status": "error", "message": str(e)}
def process_data(data):
"""数据处理函数"""
# 这里添加具体的数据处理逻辑
return data
if __name__ == "__main__":
result = main()
print(json.dumps(result, ensure_ascii=False, indent=2))
2. 高级自动化工作流
复杂的任务编排脚本：
#!/bin/bash
# 自动化运维工作流脚本
# 1. 环境检查
echo "🔍 检查系统环境..."
if ! command -v node &> /dev/null; then
echo "❌ Node.js未安装"
exit 1
fi
# 2. 前置处理
echo "⚙️ 执行前置任务..."
source /ql/config/task_before.sh
# 3. 主任务执行
echo "🚀 开始执行主任务..."
for script in /ql/scripts/daily/*.js; do
echo "📋 执行脚本: $(basename $script)"
task "$script"
if [ $? -ne 0 ]; then
echo "⚠️ 脚本执行失败: $(basename $script)"
# 发送通知
send_notification "脚本执行警报" "脚本 $(basename $script) 执行失败"
fi
done
# 4. 后置处理
echo "🧹 执行清理任务..."
source /ql/config/task_after.sh
echo "✅ 所有任务执行完成"
3. 错误处理与日志管理
完善的错误处理机制：
// 高级错误处理示例
class TaskRunner {
constructor() {
this.maxRetries = 3;
this.timeout = 30000;
}
async executeWithRetry(taskFunc, taskName) {
let attempt = 1;
while (attempt <= this.maxRetries) {
try {
console.log(`🔄 尝试执行 ${taskName} (第 ${attempt} 次)`);
const result = await Promise.race([
taskFunc(),
this.createTimeoutPromise()
]);
console.log(`✅ ${taskName} 执行成功`);
return result;
} catch (error) {
console.error(`❌ ${taskName} 第 ${attempt} 次尝试失败:`, error.message);
attempt++;
if (attempt > this.maxRetries) {
throw new Error(`任务 ${taskName} 重试 ${this.maxRetries} 次后仍失败`);
}
// 指数退避等待
await this.delay(Math.pow(2, attempt) * 1000);
}
}
}
createTimeoutPromise() {
return new Promise((_, reject) => {
setTimeout(() => reject(new Error('任务执行超时')), this.timeout);
});
}
delay(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
}
// 使用示例
const runner = new TaskRunner();
runner.executeWithRetry(async () => {
// 你的任务逻辑
}, '数据采集任务').catch(console.error);
📊 环境变量配置最佳实践
青龙的环境变量配置非常灵活，以下是一些实用配置示例：
# config.sh 配置示例
## 基本配置
AutoDelCron="true" # 自动删除失效任务
AutoAddCron="true" # 自动添加新任务
DefaultCronRule="0 3 * * *" # 默认定时规则
## 代理配置
ProxyUrl="http://127.0.0.1:7890"
## 超时设置
CommandTimeoutTime="1h" # 任务执行超时时间
## 随机延迟配置
RandomDelay="300" # 最大随机延迟300秒
RandomDelayFileExtensions="js py" # 对JS和PY文件启用随机延迟
## 通知配置 - Server酱
export PUSH_KEY="你的SCKEY"
## 通知配置 - 消息平台
export BOT_TOKEN="你的BotToken"
export USER_ID="你的用户ID"
## 通知配置 - 钉钉
export DD_BOT_TOKEN="你的钉钉Token"
export DD_BOT_SECRET="你的钉钉Secret"
🔄 自动化部署与更新
1. 仓库自动更新脚本
#!/bin/bash
# 自动化仓库更新脚本
REPOS=(
"https://github.com/user/repo1.git:main:scripts:blacklist.txt"
"https://github.com/user/repo2.git:master:daily:exclude.txt"
)
for repo_info in "${REPOS[@]}"; do
IFS=':' read -r url branch path blacklist <<< "$repo_info"
echo "🔄 更新仓库: $(basename $url .git)"
ql repo "$url" "$path" "$blacklist" "" "$branch" "js py"
if [ $? -eq 0 ]; then
echo "✅ 仓库更新成功: $(basename $url .git)"
else
echo "❌ 仓库更新失败: $(basename $url .git)"
send_notification "仓库更新警报" "仓库 $(basename $url .git) 更新失败"
fi
done
2. 系统健康检查脚本
#!/bin/bash
# 系统健康检查脚本
check_disk_usage() {
local usage=$(df /ql | awk 'NR==2 {print $5}' | sed 's/%//')
if [ $usage -gt 90 ]; then
echo "❌ 磁盘使用率过高: ${usage}%"
return 1
fi
echo "✅ 磁盘使用率正常: ${usage}%"
return 0
}
check_memory_usage() {
local usage=$(free | awk '/Mem:/ {printf("%.0f"), $3/$2*100}')
if [ $usage -gt 80 ]; then
echo "❌ 内存使用率过高: ${usage}%"
return 1
fi
echo "✅ 内存使用率正常: ${usage}%"
return 0
}
check_service_status() {
if pm2 status | grep -q online; then
echo "✅ 服务运行正常"
return 0
else
echo "❌ 服务异常"
return 1
fi
}
# 执行检查
echo "🏥 开始系统健康检查..."
check_disk_usage
check_memory_usage
check_service_status
if [ $? -ne 0 ]; then
send_notification "系统健康警报" "系统检测到异常状态，请及时处理"
fi
🎨 高级技巧与最佳实践
1. 任务依赖管理
#!/bin/bash
# 任务依赖管理脚本
declare -A TASK_DEPENDENCIES=(
["data_collection"]=""
["data_processing"]="data_collection"
["report_generation"]="data_processing"
["notification"]="report_generation"
)
run_task_with_dependencies() {
local task_name=$1
local dependencies=${TASK_DEPENDENCIES[$task_name]}
# 检查依赖
if [ -n "$dependencies" ]; then
echo "📋 检查任务依赖: $dependencies"
IFS=' ' read -ra deps <<< "$dependencies"
for dep in "${deps[@]}"; do
if ! check_task_status "$dep"; then
echo "❌ 依赖任务 $dep 未完成，无法执行 $task_name"
return 1
fi
done
fi
# 执行任务
echo "🚀 执行任务: $task_name"
task "/ql/scripts/$task_name.js"
}
check_task_status() {
local task_name=$1
# 这里实现任务状态检查逻辑
return 0
}
2. 性能监控与优化
// 性能监控装饰器
function measurePerformance(target, name, descriptor) {
const original = descriptor.value;
descriptor.value = async function(...args) {
const start = Date.now();
console.log(`⏱️ 开始执行: ${name}`);
try {
const result = await original.apply(this, args);
const duration = Date.now() - start;
console.log(`✅ 执行完成: ${name}, 耗时: ${duration}ms`);
// 记录性能数据
if (duration > 5000) {
console.warn(`⚠️ 任务 ${name} 执行时间较长: ${duration}ms`);
}
return result;
} catch (error) {
const duration = Date.now() - start;
console.error(`❌ 执行失败: ${name}, 耗时: ${duration}ms`, error);
throw error;
}
};
return descriptor;
}
// 使用示例
class DataProcessor {
@measurePerformance
async processLargeDataset(data) {
// 数据处理逻辑
await new Promise(resolve => setTimeout(resolve, 3000));
return { processed: data.length };
}
}
📈 实战案例：电商数据自动化 pipeline
对应的自动化脚本：
#!/bin/bash
# 电商数据自动化pipeline
PIPELINE_STAGES=(
"采集商品数据:product_collection.js"
"清洗数据:data_cleaning.py"
"分析销售趋势:sales_analysis.js"
"生成日报:daily_report.py"
"发送通知:send_notification.js"
)
execute_pipeline() {
local success=true
for stage_info in "${PIPELINE_STAGES[@]}"; do
IFS=':' read -r stage_name script_file <<< "$stage_info"
echo "🎯 开始阶段: $stage_name"
if ! task "/ql/scripts/$script_file"; then
echo "❌ 阶段失败: $stage_name"
send_notification "Pipeline警报" "阶段 $stage_name 执行失败"
success=false
break
fi
echo "✅ 阶段完成: $stage_name"
done
if $success; then
echo "🎉 整个pipeline执行成功"
send_notification "Pipeline完成" "所有阶段执行成功"
else
echo "💥 pipeline执行中断"
fi
}
# 执行pipeline
execute_pipeline
🛠️ 故障排除与调试技巧
1. 日志分析工具
#!/bin/bash
# 日志分析脚本
analyze_logs() {
local log_dir="/ql/log"
local days=${1:-7}
echo "📊 分析最近 ${days} 天的日志..."
# 统计任务执行情况
echo "任务执行统计:"
find "$log_dir" -name "*.log" -mtime -$days -exec grep -l "执行结束" {} \; | wc -l | xargs echo "成功任务数:"
find "$log_dir" -name "*.log" -mtime -$days -exec grep -l "执行失败" {} \; | wc -l | xargs echo "失败任务数:"
# 查找常见错误
echo "常见错误:"
find "$log_dir" -name "*.log" -mtime -$days -exec grep -i "error\|fail\|exception" {} \; | head -10
# 性能分析
echo "执行时间分析:"
find "$log_dir" -name "*.log" -mtime -$days -exec grep "耗时" {} \; | \
awk '{print $NF}' | \
awk '{sum+=$1; count++} END {print "平均耗时:" sum/count "秒"}'
}
# 使用示例
analyze_logs 7
2. 实时监控脚本
// 实时任务监控
const fs = require('fs');
const path = require('path');
class TaskMonitor {
constructor(logDir = '/ql/log') {
this.logDir = logDir;
this.watchers = new Map();
}
startMonitoring() {
console.log('👀 开始监控任务执行...');
// 监控新日志文件
fs.watch(this.logDir, (eventType, filename) => {
if (eventType === 'rename' && filename.endsWith('.log')) {
this.monitorLogFile(path.join(this.logDir, filename));
}
});
// 监控现有日志文件
fs.readdirSync(this.logDir)
.filter(file => file.endsWith('.log'))
.forEach(file => this.monitorLogFile(path.join(this.logDir, file)));
}
monitorLogFile(filePath) {
if (this.watchers.has(filePath)) return;
console.log(`📝 开始监控: ${path.basename(filePath)}`);
const watcher = fs.watchFile(filePath, { interval: 1000 }, (curr,创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
