diff --git a/REDM.txt b/REDM.txt new file mode 100644 index 0000000..44a130e --- /dev/null +++ b/REDM.txt @@ -0,0 +1,218 @@ +# 运维告警监控平台项目完整部署文档 +## 文档说明 +本文档完整记录告警监控平台**目录结构、数据库表、前后端脚本、接口逻辑、部署配置、导出功能**全栈信息，用于运维存档、交接、故障排查。 + +# 一、项目整体架构 +## 1. 架构分层 +1. **数据采集层**：Alertmanager Webhook（909端口Python入库脚本） +2. **数据存储层**：MariaDB/MySQL `alert_mail_stat` 库 +3. **服务接口层**：Nginx容器 + PHP（api接口，统计/图表/明细/CSV导出） +4. **可视化展示层**：HTML前端监控看板（实时刷新、图表、导出） + +## 2. 端口与服务说明 +| 服务 | 端口 | 部署位置 | 作用 | +|------|------|----------|------| +| Alertmanager | 9093 | 宿主机 | 接收Prometheus告警，转发给webhook | +| Prometheus | 9090 | 宿主机 | 生成告警规则 | +| Python Webhook | 909 | 宿主机 | 接收AM告警，入库MySQL | +| Nginx+PHP | 8080 | Docker容器 | 提供api接口、静态页面访问 | +| MySQL/MariaDB | 3306 | 宿主机 | 告警数据持久存储 | + +# 二、项目目录层级结构 +## 宿主机目录（宿主机实体文件） +``` +/root +├─ webhook.py # Alertmanager告警入库脚本（909端口服务） +├─ alert_report.py # 旧CSV导出Python脚本（已废弃，改用纯PHP导出） +├─ alert.rules.yml # Prometheus告警规则 +├─ am.yml # Alertmanager配置文件 +/var/www/html # Nginx容器挂载目录（前端+PHP接口） +├─ index.html # 企业级告警监控看板前端页面 +├─ api.php # PHP后端接口文件（统计/top10/明细/导出） +/tmp # 临时文件目录（CSV临时文件，现已不用） +``` + +## Docker容器目录（Nginx+PHP容器内） +``` +/usr/share/nginx/html +├─ index.html +├─ api.php +``` + +# 三、数据库设计 +## 1. 数据库库名 +`alert_mail_stat` + +## 2. 数据表：`alert_log` 告警明细表 +### 建表语句 +```sql +CREATE TABLE `alert_log` ( + `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '自增主键', + `mail_uid` varchar(255) NOT NULL COMMENT '告警唯一指纹fingerprint', + `alert_type` tinyint(1) NOT NULL COMMENT '1=触发故障 2=恢复告警', + `alert_name` varchar(200) NOT NULL COMMENT '告警规则名称', + `instance` varchar(200) NOT NULL COMMENT '告警实例IP/主机名', + `severity` varchar(50) NOT NULL DEFAULT 'warning' COMMENT '告警级别 critical/warning/info', + `starts_at` datetime DEFAULT NULL COMMENT '原始UTC告警触发时间', + `ends_at` datetime DEFAULT NULL COMMENT '原始UTC恢复时间', + `content` text COMMENT '告警完整原始JSON内容', + `receive_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '入库东八区服务器时间', + PRIMARY KEY (`id`), + KEY idx_receive_time (`receive_time`), + KEY idx_instance (`instance`), + KEY idx_alert_type (`alert_type`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='告警全量明细记录表'; +``` + +### 字段详细说明 +| 字段 | 类型 | 说明 | +|------|------|------| +| id | int | 自增主键 | +| mail_uid | varchar | Alertmanager告警唯一指纹，区分同一条告警 | +| alert_type | tinyint | 1=故障触发 2=告警恢复 | +| alert_name | varchar | Prometheus告警名称 | +| instance | varchar | 告警目标实例地址 | +| severity | varchar | 告警等级：critical严重 / warning警告 / info信息 | +| starts_at | datetime | UTC零时区告警开始时间，前端/CSV导出自动转东八区 | +| ends_at | datetime | UTC零时区告警恢复时间，现前端不再展示该字段 | +| content | text | 完整原始告警JSON报文 | +| receive_time | datetime | 脚本入库时服务器本地东八区时间，前端统一展示此字段为「故障发生时间」 | + +### 索引说明 +1. `idx_receive_time`：按日期查询今日告警核心索引 +2. `idx_instance`：实例过滤、TOP统计加速 +3. `idx_alert_type`：区分故障/恢复统计 + +# 四、核心脚本完整说明 +## 脚本1：/root/webhook.py 告警入库服务（909端口） +### 功能 +1. 开启HTTP 909端口接收Alertmanager POST告警推送 +2. 区分告警状态firing/resolved，赋值alert_type=1/2 +3. 解析fingerprint作为唯一标识存入mail_uid +4. 自动写入starts_at/ends_at UTC时间 +5. 使用数据库NOW()写入本地东八区receive_time +6. 支持同实例多次故障重复入库（已删除唯一索引uk_mail_uid） + +### 关键逻辑 +- firing告警：直接INSERT新增一条故障记录 +- resolved恢复告警：INSERT新增一条恢复记录，故障记录保留不覆盖 +- 无重复限制，全天多次启停告警全部留存明细 + +### 启动方式 +```bash +# 后台常驻运行 +nohup python3 /root/webhook.py & +# 查看日志 +tail -f nohup.out +``` + +## 脚本2：/var/www/html/api.php PHP后端接口（核心业务接口） +### 四大接口（通过GET参数act区分） +地址前缀：`http://10.150.117.190:8080/api.php` +1. `?act=day_total` 今日统计卡片数据 + - 输出：今日故障总数、恢复总数、独立实例数、恢复率 +2. `?act=top_alert` 今日告警TOP10图表数据 + - 输出：按告警名称分组计数，降序取前10 +3. `?act=log_list` 告警明细表格数据 + - 输出今日所有告警明细，提供前端表格渲染 +4. `?act=export_csv` 纯PHP生成CSV导出（无python依赖，解决容器找不到python问题） + - 自动转换UTC starts_at为东八区北京时间 + - 告警数字1/2自动转为中文「触发/恢复」 + - UTF8-BOM，Windows Excel不乱码 + - 不生成临时文件，流式直接下载 + +### 数据库连接配置 +```php +$host = "10.150.117.190"; +$user = "root"; +$pass = "hp93000"; +$dbname = "alert_mail_stat"; +``` + +## 脚本3：/var/www/html/index.html 前端监控看板页面 +### 页面模块划分 +1. 顶部导航栏 + - 平台标题、实时系统时钟（每秒刷新） + - 手动刷新按钮、CSV导出按钮、导出加载遮罩 +2. 四大统计卡片 + - 今日触发告警、今日恢复告警、故障实例总数、恢复率 +3. ECharts柱状图：今日告警频次TOP10 +4. 告警明细表格 + - 字段：告警状态、告警名称、实例地址、告警级别、故障发生时间（receive_time） + - 已移除原UTC starts_at列，消除时区混淆 + - 状态标签、级别标签带颜色区分，配套FontAwesome图标 + +### 前端核心能力 +1. 每60秒自动全量刷新统计、图表、表格 +2. 右上角实时时钟每秒更新 +3. 导出按钮触发CSV下载，5秒遮罩等待 +4. 自适应PC/平板/手机响应式布局 +5. 企业深蓝高级UI，全页面运维图标 + +### 接口请求地址统一常量 +```js +const api = "http://10.150.117.190:8080/api.php"; +``` + +## 废弃脚本说明 +`/root/alert_report.py`：早期CSV导出脚本 +- 问题：Nginx容器内无Python环境，exec调用失败，返回码127 +- 解决方案：完全移除Python调用逻辑，改用纯PHP流式导出CSV + +# 五、配置文件说明 +## 1. Prometheus告警规则 /root/alert.rules.yml +作用：定义各类业务告警，设置`severity`标签（critical/warning/info），标签会透传给webhook入库。 + +## 2. Alertmanager配置 /root/am.yml +核心路由配置：所有告警转发至宿主机909端口webhook地址 +```yaml +receivers: +- name: webhook-receiver + webhook_configs: + - url: http://127.0.0.1:909 +``` + +## 3. Nginx容器挂载配置 +容器启动挂载参数：将宿主机静态页面与PHP接口挂载至容器web根目录 +``` +-v /var/www/html:/usr/share/nginx/html +``` + +# 六、数据流转完整流程 +1. Prometheus触发告警 → 推送至Alertmanager +2. Alertmanager根据路由配置POST JSON告警报文到 `127.0.0.1:909` +3. webhook.py接收报文，解析字段，写入MySQL `alert_log` +4. 前端页面定时请求api.php三大数据接口拉取入库后的告警数据 +5. 用户点击导出，api.php直接查询数据库生成CSV文件浏览器下载 + +# 七、运维常用操作命令 +## 1. 重启告警入库服务 +```bash +pkill -f webhook.py +nohup python3 /root/webhook.py & +``` + +## 2. 测试接口是否正常 +```bash +# 统计接口 +curl http://10.150.117.190:8080/api.php?act=day_total +# 明细接口 +curl http://10.150.117.190:8080/api.php?act=log_list +# CSV导出（浏览器访问） +http://10.150.117.190:8080/api.php?act=export_csv +``` + +## 3. 数据库查询今日告警 +```sql +SELECT * FROM alert_log WHERE DATE(receive_time) = CURDATE() ORDER BY receive_time DESC; +``` + +# 八、已知优化点与历史问题记录 +1. 历史问题：CSV导出调用宿主机Python，容器内无环境，报错127 + 优化：重写export_csv为纯PHP实现，移除外部脚本依赖 +2. 历史问题：故障恢复UPDATE覆盖原始故障记录，无法同时查看触发+恢复 + 优化：删除mail_uid唯一索引，触发、恢复分别INSERT两条独立记录 +3. 历史问题：表格同时存在UTC starts_at和东八区receive_time，时区混淆 + 优化：前端删除starts_at列，仅展示入库东八区时间，表头命名「故障发生时间」 +4. UI迭代：原始简易配色改为企业深蓝运维后台风格，全量增加FontAwesome图标 +5. 时钟优化：静态页面刷新时间改为每秒更新的系统实时时钟，区分数据刷新与系统时间 \ No newline at end of file