# 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 表 - 通知通道配置 ```python 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 字段示例**: ```json { "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 表 - 发送历史 ```python 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 表 - 消息模板 (可选) ```python 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 发送通知到指定通道（支持批量发送）。 **请求体**: ```json { "channels": ["告警群", "运维群"], // 通道名称列表（与 tags 二选一） "tags": ["alerts", "production"], // 标签列表，发送到所有匹配的通道 "title": "服务器告警", // 可选 "body": "CPU 使用率超过 90%", "priority": "high" // 可选，默认 normal } ``` **说明**: - `channels` 和 `tags` 二选一，不能同时为空 - 使用 `channels`: 精确指定通道名称列表 - 使用 `tags`: 发送到包含任一标签的所有通道 **响应**: ```json { "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. 后续优化方向 1. **模板系统**: 支持变量替换的模板功能 2. **批量发送**: 支持一次发送到多个通道 3. **重试机制**: 失败自动重试 4. **通知队列**: 使用 Celery/RQ 处理大量通知 5. **用户认证**: 添加登录和权限管理 6. **Webhook 回调**: 支持外部系统接收通知状态 --- ## 9. 参考资源 - [apprise 文档](https://github.com/caronc/apprise) - [FastAPI 文档](https://fastapi.tiangolo.com/) - [SQLAlchemy 文档](https://docs.sqlalchemy.org/)