XiaM-Admin
dedc872f1b
- 增加了通过外部 HTTP API 向 QQ 群组发送消息的核心功能。 - 实现了对长文本消息的图片渲染，以避免被认定为垃圾信息。 - 支持在消息中提及特定的 QQ 用户。 - 创建了用于 API 令牌和图片渲染设置的配置选项。 - 开发了一个测试脚本以验证 API 功能。 - 对现有代码进行了重构，以提高组织性和可维护性。
220 lines
4.7 KiB
Markdown
220 lines
4.7 KiB
Markdown
# 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. 确保依赖已安装
|
||
|
||
```bash
|
||
pip install pillow
|
||
```
|
||
|
||
### 2. 配置 Token
|
||
|
||
在 `.env` 文件或 NoneBot 配置文件中添加：
|
||
|
||
```env
|
||
DANDING_QQPUSH_TOKEN = "your-custom-token-here"
|
||
```
|
||
|
||
如果不配置，默认使用 `danding-8HkL9xQ2`。
|
||
|
||
### 3. 启动 NoneBot
|
||
|
||
```bash
|
||
nb run
|
||
```
|
||
|
||
插件会自动加载，并在日志中显示注册的 API 路径。
|
||
|
||
## API 使用说明
|
||
|
||
### 接口信息
|
||
|
||
- **方法**: `POST`
|
||
- **路径**: `/danding/qqpush/{token}`
|
||
- **Content-Type**: `application/json`
|
||
|
||
### 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| -------- | ------ | ---- | ------------------------ |
|
||
| token | path | 是 | 配置的 Token |
|
||
| group_id | int | 是 | 接收消息的 QQ 群号 |
|
||
| qq | int | 是 | 被 @ 的 QQ 号 |
|
||
| text | string | 是 | 通知文本（`#` 表示换行） |
|
||
|
||
### 请求示例
|
||
|
||
```bash
|
||
curl -X POST "http://localhost:8080/danding/qqpush/danding-8HkL9xQ2" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"group_id": 123456789,
|
||
"qq": 987654321,
|
||
"text": "系统告警#数据库连接失败#请立即处理"
|
||
}'
|
||
```
|
||
|
||
### Python 请求示例
|
||
|
||
```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):
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "推送成功",
|
||
"data": {
|
||
"group_id": 123456789,
|
||
"qq": 987654321,
|
||
"message_id": 12345
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应** (400):
|
||
|
||
```json
|
||
{
|
||
"detail": "group_id 不能为空"
|
||
}
|
||
```
|
||
|
||
**错误响应** (403):
|
||
|
||
```json
|
||
{
|
||
"detail": "Token 验证失败"
|
||
}
|
||
```
|
||
|
||
**错误响应** (500):
|
||
|
||
```json
|
||
{
|
||
"detail": "Bot 未连接，请检查机器人状态"
|
||
}
|
||
```
|
||
|
||
## 配置选项
|
||
|
||
可以在配置文件中自定义以下选项：
|
||
|
||
```python
|
||
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 是否有发送消息的权限
|
||
- 查看日志中的详细错误信息
|
||
|
||
## 测试
|
||
|
||
使用提供的测试脚本进行测试：
|
||
|
||
```bash
|
||
python test_qqpush.py
|
||
```
|
||
|
||
修改脚本中的 `group_id` 和 `qq` 为实际值。
|