DanDingNoneBot/danding_bot/plugins/danding_qqpush

Danding_QqPush 插件

用于通过外部 HTTP API 向 QQ 群定向推送通知的 NoneBot 插件。

功能特性

• ✅ 通过 HTTP API 推送消息到指定 QQ 群
• ✅ 自动将文本渲染为图片，避免长文本刷屏
• ✅ 支持 @指定 QQ 用户
• ✅ 使用 # 符号表示换行
• ✅ 基于 Token 的简单鉴权机制
• ✅ 支持中文文本渲染

目录结构

danding_qqpush/
├── __init__.py         # 插件初始化模块
├── config.py           # 配置模块
├── api.py              # FastAPI 路由模块
├── text_parser.py      # 文本处理模块
├── image_render.py     # 图片生成模块
├── sender.py           # 消息发送模块
└── utils.py            # 工具函数模块

安装与配置

1. 确保依赖已安装

pip install pillow

2. 配置 Token

在 .env 文件或 NoneBot 配置文件中添加：

DANDING_QQPUSH_TOKEN = "your-custom-token-here"

如果不配置，默认使用 danding-8HkL9xQ2。

3. 启动 NoneBot

nb run

插件会自动加载，并在日志中显示注册的 API 路径。

API 使用说明

接口信息

• 方法: POST
• 路径: /danding/qqpush/{token}
• Content-Type: application/json

请求参数

参数名	类型	必填	说明
token	path	是	配置的 Token
group_id	int	是	接收消息的 QQ 群号
qq	int	是	被 @ 的 QQ 号
text	string	是	通知文本（# 表示换行）

请求示例

curl -X POST "http://localhost:8080/danding/qqpush/danding-8HkL9xQ2" \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": 123456789,
    "qq": 987654321,
    "text": "系统告警#数据库连接失败#请立即处理"
  }'

Python 请求示例

import requests

url = "http://localhost:8080/danding/qqpush/danding-8HkL9xQ2"
data = {
    "group_id": 123456789,
    "qq": 987654321,
    "text": "系统告警#数据库连接失败#请立即处理"
}

response = requests.post(url, json=data)
print(response.json())

响应示例

成功响应 (200):

{
  "success": true,
  "message": "推送成功",
  "data": {
    "group_id": 123456789,
    "qq": 987654321,
    "message_id": 12345
  }
}

错误响应 (400):

{
  "detail": "group_id 不能为空"
}

错误响应 (403):

{
  "detail": "Token 验证失败"
}

错误响应 (500):

{
  "detail": "Bot 未连接，请检查机器人状态"
}

配置选项

可以在配置文件中自定义以下选项：

class Config(BaseModel):
    Token: str = "danding-8HkL9xQ2"
    """API 访问 Token"""
    
    ImageWidth: int = 800
    """图片宽度（像素）"""
    
    ImageFontSize: int = 24
    """字体大小（像素）"""
    
    ImagePadding: int = 30
    """图片内边距（像素）"""
    
    ImageLineSpacing: float = 1.4
    """行距倍数"""
    
    ImageBgColor: tuple = (252, 252, 252)
    """图片背景颜色 (R, G, B)"""
    
    ImageTextColor: tuple = (0, 0, 0)
    """文本颜色 (R, G, B)"""
    
    MaxTextLength: int = 2000
    """最大文本长度（字符数）"""
    
    FontPaths: list = [...]
    """字体文件路径列表"""

文本格式说明

• 使用 # 符号表示换行
• 示例：第一行#第二行#第三行 会被渲染为三行文本
• 超过最大长度的文本会被自动截断

注意事项

1. 安全性: Token 泄露只影响推送能力，无账号风险，但建议定期更换
2. Bot 状态: 确保 Bot 已连接，否则会返回 500 错误
3. 群权限: 确保 Bot 在目标群中有发送消息的权限
4. 字体支持: 插件会自动尝试加载系统中的中文字体

故障排查

问题：启动时显示 "未找到可用的 Bot 实例"

说明: 这是正常现象。插件加载时 Bot 可能还未连接，API 调用时会动态获取 Bot 实例。

问题：返回 "Bot 未连接"

解决方案:

• 检查 NoneBot 是否正常启动
• 检查 OneBot V11 连接状态
• 确认 Bot 已成功连接到 QQ 服务器

问题：图片显示乱码

解决方案:

• 检查系统是否安装了中文字体
• 在 FontPaths 配置中添加正确的字体路径

问题：消息发送失败

解决方案:

• 检查 Bot 是否在目标群中
• 检查 Bot 是否有发送消息的权限
• 查看日志中的详细错误信息

测试

使用提供的测试脚本进行测试：

python test_qqpush.py

修改脚本中的 group_id 和 qq 为实际值。