webhook_dashboard/REDM.txt

# 运维告警监控平台项目完整部署文档
## 文档说明
本文档完整记录告警监控平台**目录结构、数据库表、前后端脚本、接口逻辑、部署配置、导出功能**全栈信息，用于运维存档、交接、故障排查。

# 一、项目整体架构
## 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. 时钟优化：静态页面刷新时间改为每秒更新的系统实时时钟，区分数据刷新与系统时间