qinglong系统通知集成：20+通知渠道配置与使用指南

还在为定时任务执行结果无法及时获知而烦恼？每次都要手动登录服务器查看日志？qinglong（青龙）强大的通知系统帮你彻底解决这个痛点！本文将全面解析qinglong支持的20+通知渠道，手把手教你配置和使用，让你的定时任务管理更加智能化。

读完本文你能得到什么

• ✅ 全面了解qinglong支持的20+通知渠道
• ✅ 掌握每种通知渠道的详细配置方法
• ✅ 学会在脚本中调用通知功能的实战技巧
• ✅ 了解通知系统的架构设计和实现原理
• ✅ 获得最佳实践和故障排除指南

qinglong通知系统架构概览

graph TB
    A[定时任务执行] --> B[任务执行结果]
    B --> C[NotificationService]
    C --> D[通知渠道分发]
    D --> E[Gotify]
    D --> F[即时通讯Bot]
    D --> G[钉钉机器人]
    D --> H[企业微信]
    D --> I[邮件通知]
    D --> J[Webhook]
    D --> K[...20+渠道]

20+通知渠道全解析

1. 即时通讯类通知

1.1 即时通讯Bot通知

即时通讯Bot是最受欢迎的通知渠道之一，配置简单，推送稳定。

配置参数：

• instantMessagingBotToken: Bot Token（从官方获取）
• instantMessagingBotUserId: 用户或群组ID
• instantMessagingBotApiHost: API地址（可选，默认官方API）
• instantMessagingBotProxyHost: 代理主机（可选）
• instantMessagingBotProxyPort: 代理端口（可选）

环境变量配置：

export IM_BOT_TOKEN="1407203283:AAG9rt-6RDaaX0HBLZQq0laNOh898iFYaRQ"
export IM_USER_ID="1434078534"

1.2 钉钉机器人通知

钉钉机器人适合国内企业用户，支持加签安全验证。

配置参数：

• dingtalkBotToken: Webhook Token
• dingtalkBotSecret: 加签密钥（可选）

环境变量配置：

export DD_BOT_TOKEN="693a91f6-7xxx-4bc4-97a0-0ec2sifa5aaa"
export DD_BOT_SECRET="SECxxxxxxxx"

1.3 企业微信通知

支持两种方式：机器人Webhook和企业微信应用消息。

机器人Webhook配置：

export QYWX_KEY="693a91f6-7xxx-4bc4-97a0-0ec2sifa5aaa"

应用消息配置（更强大）：

export QYWX_AM="corpid,corpsecret,touser,agentid,thumb_media_id"

2. 推送服务类通知

2.1 Bark推送（iOS专属）

Bark是iOS设备专属的推送服务，无需安装额外应用。

配置参数：

• barkPush: Bark服务器地址或设备码
• barkIcon: 推送图标（可选）
• barkSound: 提示音（可选）
• barkGroup: 分组名称（可选）
• barkLevel: 时效性（可选）

环境变量配置：

export BARK_PUSH="https://api.day.app/DxHcxxxxxRxxxxxxcm"
export BARK_GROUP="qinglong"
export BARK_SOUND="minuet"

2.2 Server酱（ServerChan）

老牌推送服务，支持微信通知。

配置参数：

• serverChanKey: SCKEY或SendKey

环境变量配置：

export PUSH_KEY="SCTxxxxxxTxxxxxx"

2.3 PushPlus推送加

功能丰富的推送平台，支持多渠道。

配置参数：

• pushPlusToken: 用户令牌
• pushPlusUser: 群组编码（可选）
• pushPlusTemplate: 模板类型（html/txt/json等）
• pushplusChannel: 发送渠道（wechat/webhook等）

环境变量配置：

export PUSH_PLUS_TOKEN="xxxxxxxxxx"
export PUSH_PLUS_TEMPLATE="html"
export PUSH_PLUS_CHANNEL="wechat"

3. 邮件通知

传统的邮件通知，适合正式场景。

配置参数：

• emailService: 邮件服务商（163、qq、gmail等）
• emailUser: 发件邮箱
• emailPass: 邮箱密码或授权码
• emailTo: 收件邮箱（可选，默认为发件邮箱）

环境变量配置：

export SMTP_SERVICE="163"
export SMTP_EMAIL="[e-mail]"
export SMTP_PASSWORD="your_password"
export SMTP_TO="[e-mail]"

4. 自定义Webhook通知

最灵活的通知方式，可以对接任何系统。

配置参数：

• webhookUrl: Webhook地址（支持$title和$content变量）
• webhookMethod: 请求方法（GET/POST/PUT）
• webhookHeaders: 请求头（JSON格式）
• webhookBody: 请求体（支持变量替换）
• webhookContentType: 内容类型

环境变量配置：

export WEBHOOK_URL="https://your-api.com/notify?title=$title&content=$content"
export WEBHOOK_METHOD="POST"
export WEBHOOK_HEADERS='{"Content-Type":"application/json","Authorization":"Bearer token"}'
export WEBHOOK_BODY='{"msg":"$content","title":"$title"}'

通知渠道对比表

渠道类型	代表服务	推送速度	配置难度	适用场景	免费额度
即时通讯	即时通讯应用	⭐⭐⭐⭐⭐	⭐⭐	个人/小团队	无限
企业IM	钉钉/企业微信	⭐⭐⭐⭐	⭐⭐⭐	企业环境	无限
推送服务	Bark	⭐⭐⭐⭐⭐	⭐	iOS用户	无限
推送服务	Server酱	⭐⭐⭐⭐	⭐⭐	微信用户	有限
邮件	SMTP	⭐⭐⭐	⭐⭐⭐	正式通知	无限
自定义	Webhook	⭐⭐⭐⭐	⭐⭐⭐⭐	系统集成	无限

实战：在脚本中使用通知功能

基础通知调用

在Shell脚本中发送通知：

#!/bin/bash

# 任务逻辑
echo "开始执行数据备份任务..."
# 你的任务代码

if [ $? -eq 0 ]; then
    # 成功通知
    echo "任务执行成功" > /tmp/result.txt
else
    # 失败通知
    echo "任务执行失败，错误码: $?" > /tmp/result.txt
fi

# 发送通知
curl -s "http://127.0.0.1:5700/api/system/notify?title=备份任务&content=$(cat /tmp/result.txt)"

Python脚本中的通知集成

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import requests
import subprocess
import json

def send_qinglong_notify(title, content):
    """发送青龙通知"""
    try:
        url = "http://127.0.0.1:5700/api/system/notify"
        params = {
            "title": title,
            "content": content
        }
        response = requests.get(url, params=params)
        return response.status_code == 200
    except Exception as e:
        print(f"发送通知失败: {e}")
        return False

def main():
    try:
        # 执行你的任务
        result = subprocess.run(["your", "command"], 
                              capture_output=True, text=True, timeout=300)
        
        if result.returncode == 0:
            # 任务成功
            send_qinglong_notify(
                "任务执行成功", 
                f"任务完成\n输出:\n{result.stdout}"
            )
        else:
            # 任务失败
            send_qinglong_notify(
                "任务执行失败", 
                f"错误码: {result.returncode}\n错误输出:\n{result.stderr}"
            )
            
    except subprocess.TimeoutExpired:
        send_qinglong_notify("任务执行超时", "任务超过5分钟未完成")
    except Exception as e:
        send_qinglong_notify("任务执行异常", f"发生异常: {str(e)}")

if __name__ == "__main__":
    main()

JavaScript/Typescript通知示例

// notify.ts
import axios from 'axios';

export interface NotifyParams {
  title: string;
  content: string;
  type?: string; // 可选：指定通知渠道类型
}

export async function sendNotification(params: NotifyParams): Promise<boolean> {
  try {
    const response = await axios.get('http://127.0.0.1:5700/api/system/notify', {
      params
    });
    return response.status === 200;
  } catch (error) {
    console.error('发送通知失败:', error);
    return false;
  }
}

// 使用示例
async function runTask() {
  try {
    // 执行你的任务
    const result = await someAsyncTask();
    
    await sendNotification({
      title: '任务执行成功',
      content: `任务完成时间: ${new Date().toLocaleString()}\n结果: ${JSON.stringify(result)}`
    });
    
  } catch (error) {
    await sendNotification({
      title: '任务执行失败',
      content: `错误信息: ${error.message}\n时间: ${new Date().toLocaleString()}`
    });
  }
}

高级配置技巧

多渠道同时通知

qinglong支持配置多个通知渠道，消息会同时发送到所有已配置的渠道：

1. 在环境变量中配置多个渠道参数
2. 系统会自动选择所有已配置的渠道
3. 支持故障转移，一个渠道失败不影响其他渠道

自定义通知模板

通过Webhook可以实现自定义通知模板：

# 自定义JSON格式通知
export WEBHOOK_URL="https://your-api.com/notify"
export WEBHOOK_METHOD="POST"
export WEBHOOK_HEADERS='{"Content-Type":"application/json"}'
export WEBHOOK_BODY='{
  "platform": "qinglong",
  "level": "info",
  "title": "$title",
  "message": "$content",
  "timestamp": "$(date +%s)",
  "task_id": "$(echo $QL_TASK_ID)"
}'

条件通知配置

在脚本中实现条件通知逻辑：

#!/bin/bash

# 获取任务ID（青龙内置变量）
TASK_ID=$QL_TASK_ID

# 执行任务
LOG_FILE="/tmp/task_${TASK_ID}.log"
your_command > $LOG_FILE 2>&1
EXIT_CODE=$?

# 根据退出码决定通知级别
if [ $EXIT_CODE -eq 0 ]; then
    TITLE="✅ 任务成功 - TASK_${TASK_ID}"
    LEVEL="success"
elif [ $EXIT_CODE -eq 1 ]; then
    TITLE="⚠️  任务警告 - TASK_${TASK_ID}"
    LEVEL="warning"
else
    TITLE="❌ 任务失败 - TASK_${TASK_ID}"
    LEVEL="error"
fi

# 发送通知
CONTENT=$(cat $LOG_FILE | tail -20)  # 只发送最后20行日志
curl -s "http://127.0.0.1:5700/api/system/notify?title=$TITLE&content=$CONTENT"

故障排除指南

常见问题及解决方案

问题现象	可能原因	解决方案
收不到通知	渠道配置错误	检查环境变量名称和值是否正确
通知延迟	网络问题	检查网络连接，考虑使用国内渠道
部分渠道失败	渠道服务异常	启用多渠道配置，实现故障转移
内容截断	消息长度限制	精简通知内容，重要信息前置

调试技巧

1. 检查环境变量

   # 查看所有通知相关环境变量
   env | grep -E '(BARK|IM|DD|QYWX|PUSH|SMTP|WEBHOOK)'
   

2. 测试通知功能

   # 直接调用通知API测试
   curl "http://127.0.0.1:5700/api/system/notify?title=测试通知&content=这是一条测试消息"
   

3. 查看通知日志

   # 查看青龙日志中的通知记录
   docker logs qinglong 2>&1 | grep -i notify
   

最佳实践建议

1. 多渠道冗余配置

建议至少配置2-3个不同渠道，确保通知的可靠性：

• 主渠道：即时通讯应用或钉钉（实时性强）
• 备用渠道：邮件或Webhook（作为备份）
• 紧急渠道：Bark或Server酱（移动端提醒）

2. 通知内容优化

• 标题明确：包含任务名称和执行结果
• 内容精简：只包含关键信息，避免过长
• 格式统一：使用emoji和固定格式提升可读性

3. 安全考虑

• 敏感信息不要通过通知发送
• Webhook使用HTTPS加密
• 定期更换Token和密钥

4. 性能优化

• 高频任务避免频繁发送通知
• 使用批量通知或摘要通知
• 重要任务才配置通知

总结

qinglong的通知系统提供了极其丰富的渠道选择和灵活的配置方式，从传统的邮件到现代的即时通讯，从国内的钉钉到国际的即时通讯应用，几乎覆盖了所有可能的通知场景。通过合理的配置和使用，你可以：

1. 实时掌握任务状态：不再需要手动查看日志
2. 快速响应异常：及时处理任务失败情况
3. 提高运维效率：自动化监控和告警
4. 多端同步通知：无论在哪里都能收到提醒

建议根据实际需求选择2-3个主力通知渠道进行配置，并定期测试通知功能的可靠性。这样就能充分发挥qinglong定时任务管理的优势，真正实现智能化的运维监控。

现在就开始配置你的qinglong通知系统吧，让定时任务管理变得更加轻松高效！