# 预警模块 **Repository Path**: wu_yunlin/fastapi-alert ## Basic Information - **Project Name**: 预警模块 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-06-18 - **Last Updated**: 2026-02-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 预警系统 (Alert System) ## 📖 项目简介 基于 FastAPI 和任务组的通用预警系统，支持多数据库源、灵活的规则配置、分级通知机制。 **主要特性:** - ✅ 多数据库支持（7个预配置数据源） - ✅ 灵活的规则引擎（SQL查询 + 比较运算符） - ✅ 分级通知机制（钉钉 + 电话语音） - ✅ 定时任务调度（APScheduler） - ✅ 完整的 API 接口（FastAPI） - ✅ 健康检查和监控端点 - ✅ 日志轮转和管理 --- ## 🚀 快速开始 ### 1. 环境要求 **后端:** - Python 3.8+ - MySQL 5.7+ **前端:** - Node.js 14.0+ (可选，仅开发模式需要) - npm 6.0+ (可选，仅开发模式需要) ### 2. 安装依赖 ```bash # 后端依赖 pip install -r requirements.txt # 前端依赖（可选，仅开发模式需要） cd frontend npm install cd .. ``` ### 3. 配置环境变量 ```bash # 复制环境变量模板 cp .env.example .env # 编辑 .env 文件，填写实际的配置信息 # 必须配置的项目: # - DB_PASSWORD: 主数据库密码 # - DINGTALK_WEBHOOK: 钉钉机器人 webhook # - VOICE_APP_CODE: 阿里云语音 API 密钥 # - 其他数据库的密码 ``` ### 4. 启动服务 **方式1: 只启动后端（生产模式）** ```bash python run.py ``` 访问 http://localhost:8000/docs 查看 API 文档 **方式2: 同时启动后端和前端（开发模式，推荐）** ```bash python run.py --with-frontend ``` - 后端: http://localhost:8000 - 前端: http://localhost:3000 **方式3: 开发模式（热重载）** ```bash python run.py --reload --with-frontend ``` ### 5. 访问系统 启动成功后，访问以下地址： - **前端界面**: http://localhost:3000 （开发模式）或 http://localhost:8000 （生产模式） - **API 文档**: http://localhost:8000/docs - **健康检查**: http://localhost:8000/health - **监控指标**: http://localhost:8000/metrics --- ## 📁 项目结构 ``` alert_system/ ├── app/ # 应用主目录 │ ├── __init__.py │ ├── main.py # FastAPI 应用入口 │ ├── schemas.py # Pydantic 数据模型 │ │ │ ├── api/ # API 路由模块 │ │ ├── __init__.py │ │ ├── alert_routes.py # 预警规则 CRUD 接口 │ │ ├── history_routes.py # 历史记录查询接口 │ │ ├── trigger_routes.py # 手动触发接口 │ │ └── task_group_routes.py # 任务组管理接口 │ │ │ ├── core/ # 核心业务逻辑 │ │ ├── __init__.py │ │ ├── checker.py # 规则检查逻辑 │ │ ├── notifier.py # 通知发送模块 │ │ ├── frequency_checker.py # 频率检查逻辑 │ │ └── schedule.py # 定时任务调度管理 │ │ │ ├── db/ # 数据库模块 │ │ ├── __init__.py │ │ ├── models.py # SQLAlchemy 模型 │ │ ├── session.py # 数据库连接管理 │ │ └── init_task_groups.py # 预定义任务组初始化 │ │ │ └── static/ # 静态文件目录（前端构建产物） │ ├── frontend/ # 前端项目目录 │ ├── public/ # 静态资源 │ ├── src/ │ │ ├── api/ # API 接口封装 │ │ ├── router/ # 路由配置 │ │ ├── utils/ # 工具函数 │ │ ├── views/ # 页面组件 │ │ │ ├── Layout.vue # 布局组件 │ │ │ ├── Dashboard.vue # 监控面板 │ │ │ ├── Rules.vue # 预警规则管理 │ │ │ ├── TaskGroups.vue # 任务组管理 │ │ │ └── History.vue # 历史记录 │ │ ├── App.vue # 根组件 │ │ └── main.js # 入口文件 │ ├── package.json # 前端依赖配置 │ ├── vue.config.js # Vue CLI 配置 │ └── README.md # 前端使用指南 │ ├── logs/ # 日志文件目录（自动创建） ├── .env # 环境变量配置（需创建） ├── .env.example # 环境变量模板 ├── .gitignore # Git 忽略文件 ├── config.py # 配置管理 ├── requirements.txt # Python 依赖 ├── run.py # 应用启动脚本 └── README.md # 项目文档 ``` --- ## 🔧 核心功能 ### 后端功能 #### 1. 预警规则管理 **支持的数据库源:** - Bcenter（主库） - Omscenter、Listingcenter、Icenter、Pcenter、Gcenter、Tcenter **支持的比较运算符:** - 数值比较: `>`, `<`, `=`, `>=`, `<=`, `!=` - 字符串比较: `=`, `!=`, `contains`, `in`, `not in` **SQL 参数化变量:** ```sql -- 日期变量 %(today)s -- 今天 %(T-1)s -- 昨天 %(T-2)s -- 前天 %(T-8)s -- 8天前 %(T-30)s -- 30天前 %(T-90)s -- 90天前 -- 时间变量 %(now)s -- 当前时间 %(H-1)s -- 1小时前 %(H-2)s -- 2小时前 %(M-10)s -- 10分钟前 ``` **示例规则 SQL:** ```sql -- 查询今日订单数量 SELECT COUNT(1) FROM orders WHERE create_time >= '%(today)s' -- 查询昨日销售额 SELECT SUM(amount) FROM orders WHERE DATE(create_time) = '%(T-1)s' ``` ### 2. 预警级别和通知方式 | 级别 | 说明 | 通知方式 | |------|------|----------| | NORMAL | 普通预警 | 钉钉消息 | | URGENT | 紧急预警 | 电话语音（失败降级为钉钉） | | CRITICAL | 严重预警 | 电话语音 + 钉钉（并行） | ### 前端功能 系统提供了完整的 Web 管理界面，基于 Vue 3 + Element Plus 开发。 #### 1. 监控面板 (Dashboard) - 📊 实时统计卡片（规则数、触发次数、任务组状态） - ❤️ 系统健康检查（数据库、调度器状态） - 📈 数据库连接池监控 - 📋 最近触发记录列表 - 🔄 自动定时刷新 #### 2. 预警规则管理 (Rules) - ➕ 创建预警规则（支持完整的表单验证） - ✏️ 编辑规则配置 - 🗑️ 删除规则 - ▶️ 手动触发规则检查 - 🔀 启用/禁用规则（一键切换） - 🔍 搜索和分页 - 📝 支持 SQL 参数化变量提示 #### 3. 任务组管理 (Task Groups) - ➕ 创建自定义任务组 - ⏰ 支持 interval（间隔）和 cron（定时）两种调度类型 - ▶️ 手动运行任务组 - 📊 查看运行历史和状态 - 🔀 启用/禁用任务组 #### 4. 历史记录 (History) - 📋 查看所有预警触发历史 - 🔍 多条件筛选（规则ID、时间范围、触发状态） - 📊 分页展示 - 🏷️ 状态标签（已触发/未触发、已发送/未发送） - 📱 通知方式显示 **技术栈:** - Vue 3 (Composition API) - Vue Router 4 (SPA 路由) - Element Plus (UI 组件库) - Axios (HTTP 客户端) - ECharts (图表库，用于后续扩展) - Day.js (日期处理) ### 3. 任务组调度 系统预定义了 5 个任务组： | 任务组名称 | 执行频率 | 适用场景 | |-----------|----------|----------| | every_1m | 每1分钟 | 实时监控 | | hourly | 每小时 | 常规检查 | | daily_01:00 | 每天凌晨1点 | 日报统计 | | daily_09:00 | 每天上午9点 | 业务预警 | | weekly_mon_09:00 | 每周一上午9点 | 周报统计 | 可以通过 API 动态添加自定义任务组。 ### 4. 频率控制 每条规则可以独立设置执行频率： ``` 10m - 每10分钟执行一次 30m - 每30分钟执行一次 1h - 每1小时执行一次 2h - 每2小时执行一次 1d - 每1天执行一次 daily:09:00 - 每天9点执行 ``` **高级选项:** - `skip_weekends`: 跳过周末 - `skip_holidays`: 跳过节假日（支持中国法定节假日） - `timezone`: 时区设置（默认 Asia/Shanghai） --- ## 🔌 API 接口 ### 预警规则接口 ``` POST /alert/rules # 创建预警规则 GET /alert/rules # 获取规则列表（分页） GET /alert/rules/{rule_id} # 获取单个规则 PUT /alert/rules/{rule_id} # 更新规则 DELETE /alert/rules/{rule_id} # 删除规则 ``` ### 手动触发接口 ``` POST /alert/trigger/{rule_id} # 手动触发规则检查 ``` ### 历史记录接口 ``` GET /alert/history # 查询历史记录 ``` ### 任务组管理接口 ``` POST /tasks/groups # 创建任务组 GET /tasks/groups # 获取任务组列表 PUT /tasks/groups/{group_id} # 更新任务组 DELETE /tasks/groups/{group_id} # 删除任务组 POST /tasks/groups/{group_id}/run # 手动执行任务组 ``` ### 监控接口 ``` GET /health # 健康检查 GET /metrics # 监控指标 ``` --- ## 📊 监控和日志 ### 健康检查 访问 `/health` 端点查看系统健康状态： ```json { "status": "healthy", "timestamp": "2025-01-15T10:30:00", "components": { "database": { "status": "up", "message": "数据库连接正常" }, "scheduler": { "status": "up", "message": "任务调度器运行正常", "jobs_count": 5 } } } ``` ### 监控指标 访问 `/metrics` 端点查看系统指标： ```json { "timestamp": "2025-01-15T10:30:00", "rules": { "total": 20, "active": 18, "inactive": 2 }, "alerts": { "last_24h_total": 150, "last_24h_triggered": 12 }, "scheduler": { "running": true, "jobs_count": 5 }, "database_pools": { "Bcenter": { "size": 5, "checked_in": 3, "checked_out": 2 } } } ``` ### 日志管理 日志文件位置: `logs/app.log` **日志配置:** - 自动日志轮转（超过 100MB 自动切分） - 保留最近 10 个日志文件 - 错误日志单独记录到 `logs/app_error.log` - 同时输出到控制台（INFO 级别） **修改日志级别:** ```bash # 在 .env 文件中修改 LOG_LEVEL=DEBUG ``` --- ## ⚙️ 配置说明 ### 环境变量配置 所有配置项都通过 `.env` 文件管理： ```env # 主数据库配置 DB_HOST=mysql.database-test.oigbuy.com DB_PORT=3306 DB_USER=root DB_PASSWORD=your_password_here DB_NAME=fastapi # 钉钉机器人 DINGTALK_WEBHOOK=https://oapi.dingtalk.com/robot/send?access_token=xxx # 阿里云语音预警 VOICE_APP_CODE=your_appcode_here # 系统配置 LOG_LEVEL=INFO PORT=8000 HOST=0.0.0.0 ``` 完整配置项请参考 `.env.example`。 --- ## 🔒 安全优化 本次优化修复了以下安全问题： 1. ✅ **移除硬编码密码** - 所有敏感信息移至 `.env` 文件 2. ✅ **修复数据库连接泄露** - 使用单例模式管理 engine 3. ✅ **改进 SQL 注入防护** - 添加参数验证和清理 4. ✅ **添加 .gitignore** - 防止敏感文件提交到版本控制 --- ## 🚀 性能优化 1. ✅ **数据库连接池优化** - Engine 单例，连接复用 2. ✅ **日志轮转** - 防止日志文件无限增长 3. ✅ **健康检查端点** - 便于监控和负载均衡 4. ✅ **优雅关闭** - 应用关闭时清理所有连接 --- ## 🛠️ 开发指南 ### 添加新的预警规则 1. 通过 API 创建规则（推荐） 2. 或直接在数据库中插入： ```sql INSERT INTO alert_rules ( rule_name, task_group, origin_db, query_sql, operator, standard_type, standard_value, alert_level, owner, is_active, frequency ) VALUES ( '测试规则', 'hourly', 'Bcenter', 'SELECT COUNT(1) FROM orders WHERE create_time >= "%(today)s"', '>', 'FIXED', '100', 'NORMAL', '15051441258', 1, '1h' ); ``` ### 添加新的数据库源 1. 在 `.env` 文件中添加数据库配置 2. 在 `config.py` 中添加配置项 3. 在 `app/db/session.py` 的 `DB_URLS` 字典中添加连接 --- ## 📝 版本历史 ### v1.0.0 (2025-01-15) - 重大优化版本 **安全性改进:** - 移除所有硬编码的敏感信息 - 添加 .env 环境变量管理 - 改进 SQL 参数验证 **性能优化:** - 修复数据库连接泄露问题 - 优化连接池配置 - 添加日志轮转 **功能增强:** - 添加健康检查端点 `/health` - 添加监控指标端点 `/metrics` - 改进启动脚本，支持命令行参数 - 完善依赖管理 **代码质量:** - 添加详细注释和文档 - 改进异常处理 - 修正 T-90 时间变量bug --- ## 🤝 贡献指南 欢迎提交 Issue 和 Pull Request！ --- ## 📄 许可证 内部项目 --- ## 📞 联系方式 如有问题，请联系开发团队。