9.6 KiB
9.6 KiB
Apprise Notify Center 设计文档
日期: 2026-02-07
作者: OpenClaw Agent
版本: v1.0
1. 项目目标
构建一个基于 apprise 的多通道通知中心，提供统一的 HTTP API 接口和 Web 管理界面，支持 80+ 种通知服务。
核心需求
- 通过 HTTP POST/GET 请求发送通知
- SQLite 存储配置和历史记录
- Web 管理界面：增删改查通道、查看历史、手动发送
2. 技术架构
2.1 技术栈
| 组件 | 技术选型 | 理由 |
|---|---|---|
| 后端框架 | FastAPI | 异步高性能、自动生成 API 文档、类型提示 |
| 数据库 | SQLite | 轻量、无需额外服务、适合单机部署 |
| ORM | SQLAlchemy | 成熟、支持异步 |
| 通知引擎 | apprise | 支持 80+ 种通知服务 |
| 前端 | Vue3 + TailwindCSS | CDN 引入，无需构建步骤 |
2.2 系统架构图
┌─────────────────────────────────────────────┐
│ Web 管理界面 (Vue3 SPA) │
└──────────────┬──────────────────────────────┘
│ HTTP/REST
┌──────────────▼──────────────────────────────┐
│ FastAPI 后端服务 │
│ ┌─────────────┐ ┌──────────────────────┐ │
│ │ 通道管理 API │ │ 通知发送 API (POST) │ │
│ └─────────────┘ └──────────────────────┘ │
│ ┌─────────────┐ ┌──────────────────────┐ │
│ │ 配置管理 API │ │ 历史记录 / 统计 API │ │
│ └─────────────┘ └──────────────────────┘ │
└──────────────┬──────────────────────────────┘
│
┌──────────┴──────────┐
▼ ▼
┌─────────┐ ┌──────────┐
│ SQLite │ │ apprise │
│ (配置+历史)│ │(发送通知) │
└─────────┘ └──────────┘
3. 数据模型
3.1 channels 表 - 通知通道配置
class Channel(Base):
__tablename__ = "channels"
id = Column(Integer, primary_key=True)
name = Column(String, nullable=False, unique=True) # 通道名称，如 "告警群"
type = Column(String, nullable=False) # apprise 协议，如 "discord"
config = Column(JSON, nullable=False) # 配置参数
tags = Column(JSON, default=list) # 标签，如 ["alerts", "urgent"]
is_active = Column(Boolean, default=True)
created_at = Column(DateTime, default=datetime.utcnow)
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
tags 字段示例: ["production", "alerts", "discord"] - 用于批量选择通道
config 字段示例:
{
"discord": {
"webhook_url": "https://discord.com/api/webhooks/xxx"
},
"telegram": {
"bot_token": "123456:ABC-DEF...",
"chat_id": "-1001234567890"
},
"email": {
"smtp_host": "smtp.gmail.com",
"smtp_port": 587,
"username": "user@gmail.com",
"password": "app_password",
"to_email": "admin@example.com"
}
}
3.2 notifications 表 - 发送历史
class Notification(Base):
__tablename__ = "notifications"
id = Column(Integer, primary_key=True)
channel_id = Column(Integer, ForeignKey("channels.id"))
title = Column(String, nullable=True)
body = Column(Text, nullable=False)
priority = Column(String, default="normal") # low/normal/high/urgent
status = Column(String, default="pending") # pending/sent/failed
error_msg = Column(Text, nullable=True)
sent_at = Column(DateTime, nullable=True)
created_at = Column(DateTime, default=datetime.utcnow)
3.3 templates 表 - 消息模板 (可选)
class Template(Base):
__tablename__ = "templates"
id = Column(Integer, primary_key=True)
name = Column(String, nullable=False, unique=True)
title_template = Column(String, nullable=True)
body_template = Column(Text, nullable=False)
variables = Column(JSON, default=list) # ["server_name", "alert_level"]
created_at = Column(DateTime, default=datetime.utcnow)
updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
4. API 设计
4.1 通知发送 API
POST /api/notify
发送通知到指定通道（支持批量发送）。
请求体:
{
"channels": ["告警群", "运维群"], // 通道名称列表（与 tags 二选一）
"tags": ["alerts", "production"], // 标签列表，发送到所有匹配的通道
"title": "服务器告警", // 可选
"body": "CPU 使用率超过 90%",
"priority": "high" // 可选，默认 normal
}
说明:
channels和tags二选一，不能同时为空- 使用
channels: 精确指定通道名称列表 - 使用
tags: 发送到包含任一标签的所有通道
响应:
{
"success": true,
"results": [
{
"channel": "告警群",
"channel_id": 1,
"status": "sent",
"notification_id": 123
},
{
"channel": "运维群",
"channel_id": 2,
"status": "sent",
"notification_id": 124
}
],
"total": 2,
"sent": 2,
"failed": 0
}
GET /api/notify
通过 URL 参数发送通知（方便脚本调用）。
请求:
GET /api/notify?channels=告警群,运维群&body=测试消息&priority=normal
GET /api/notify?tags=alerts,urgent&body=测试消息&priority=high
4.2 通道管理 API
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | /api/channels | 获取所有通道 |
| GET | /api/channels/{id} | 获取单个通道 |
| POST | /api/channels | 创建通道 |
| PUT | /api/channels/{id} | 更新通道 |
| DELETE | /api/channels/{id} | 删除通道 |
| POST | /api/channels/{id}/test | 测试通道 |
4.3 历史记录 API
| 方法 | 路径 | 描述 |
|---|---|---|
| GET | /api/notifications | 获取历史记录（支持分页、筛选） |
| GET | /api/notifications/{id} | 获取单条记录 |
| GET | /api/stats | 获取统计信息 |
5. Web 管理界面
5.1 页面结构
- 仪表盘: 概览统计（今日发送量、通道数量、成功率）
- 通道管理: 列表视图、添加/编辑通道表单
- 发送历史: 筛选、搜索、分页
- 手动发送: 选择通道、填写内容、预览发送
5.2 UI 布局
┌─────────────────────────────────────────────┐
│ Logo 仪表盘 通道管理 历史记录 手动发送 │
├──────────┬──────────────────────────────────┤
│ │ │
│ 侧边栏 │ 主内容区 │
│ (可选) │ │
│ │ │
└──────────┴──────────────────────────────────┘
6. 项目结构
apprise-notify-center/
├── AGENTS.md # OpenClaw 项目规范
├── README.md # 项目介绍
├── requirements.txt # Python 依赖
├── docs/
│ └── plans/
│ └── 2026-02-07-design.md # 本设计文档
├── backend/
│ ├── main.py # FastAPI 入口
│ ├── config.py # 配置管理
│ ├── database.py # 数据库连接
│ ├── models.py # SQLAlchemy 模型
│ ├── schemas.py # Pydantic 模型
│ └── routers/
│ ├── __init__.py
│ ├── channels.py # 通道管理路由
│ ├── notify.py # 通知发送路由
│ ├── history.py # 历史记录路由
│ └── stats.py # 统计路由
├── frontend/
│ ├── index.html # 主页面
│ ├── css/
│ │ └── style.css # 自定义样式
│ └── js/
│ └── app.js # Vue3 应用
└── tests/
└── test_api.py # API 测试
7. 依赖列表
# requirements.txt
fastapi==0.109.0
uvicorn[standard]==0.27.0
sqlalchemy==2.0.25
apprise==1.7.2
pydantic==2.5.3
python-multipart==0.0.6
aiosqlite==0.19.0
8. 后续优化方向
- 模板系统: 支持变量替换的模板功能
- 批量发送: 支持一次发送到多个通道
- 重试机制: 失败自动重试
- 通知队列: 使用 Celery/RQ 处理大量通知
- 用户认证: 添加登录和权限管理
- Webhook 回调: 支持外部系统接收通知状态