simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
4bd4a9068b193ec835c70215c32e7b1be57636f2
wecom_it_smart_desk/docs/09-部署运维/12-IT服务台业务监控与自愈方案.md
T

447 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# IT服务台业务监控与自愈方案
> **版本**: v1.0 | **日期**: 2026-07-09 | **维护人**: 宋献
> **定位**: 业务层监控告警 + 自动化修复方案
---
## 1. 方案概述
### 1.1 背景
IT智能服务台上线后，业务异常（如坐席列表获取失败、消息发送失败）直接影响用户体验。当前依赖人工发现和处理，响应慢。
### 1.2 目标
| 目标 | 指标 |
|-----|------|
| 业务问题早发现 | 5分钟内检测到异常 |
| 自愈能力 | 低级别问题自动修复 |
| 减少人工干预 | 70%业务问题自动化处理 |
| 问题可追溯 | 所有异常都有记录 |
### 1.3 分层监控架构
```
┌──────────────────────────────────────────────────────────────┐
│ 基础设施层（数据中心兜底） │
│ - CPU/内存/磁盘/网络/物理服务器 │
│ - 监控告警：基础设施团队处理 │
│ - 本系统：仅展示状态 + 记录 │
└──────────────────────────────────────────────────────────────┘
↓ 告知
┌──────────────────────────────────────────────────────────────┐
│ 业务应用层（本系统自主维护）⭐ │
│ - 坐席管理 / 消息通讯 / AI服务 / 会话管理 │
│ - 检测 → 诊断 → 修复 → 验证 → 记录 │
└──────────────────────────────────────────────────────────────┘
```
---
## 2. 监控接口设计
### 2.1 业务健康检查接口
**接口**: `GET /api/admin/health-check`
**响应示例**:
```json
{
"code": 0,
"data": {
"timestamp": "2026-07-09T16:00:00Z",
"overall_status": "healthy",
"infrastructure": {
"nginx": "healthy",
"backend": "healthy",
"redis": "healthy",
"postgres": "healthy"
},
"business": {
"agents_api": { "status": "healthy", "latency_ms": 45 },
"message_send": { "status": "healthy", "latency_ms": 120 },
"wecom_callback": { "status": "healthy", "latency_ms": 30 },
"ai_rag": { "status": "healthy", "latency_ms": 850 },
"websocket": { "status": "healthy", "connections": 12 }
},
"errors": []
}
}
```
### 2.2 监控点清单
| 监控点 | 检测方式 | 超时阈值 | 影响级别 |
|-------|---------|---------|---------|
| **nginx** | curl localhost:80 | 2s | 高 |
| **backend** | curl /health | 2s | 高 |
| **redis** | redis-cli ping | 1s | 高 |
| **postgres** | pg_isready | 2s | 高 |
| **agents_api** | GET /api/agents/ | 5s | 高 |
| **message_send** | POST 发送测试消息 | 10s | 高 |
| **wecom_callback** | 企微API ping | 5s | 中 |
| **ai_rag** | POST /api/ai/query | 15s | 中 |
| **websocket** | WS连接数监控 | — | 中 |
### 2.3 基础设施监控（轻量）
| 监控项 | 命令 | 告警阈值 |
|-------|------|---------|
| 容器健康 | `docker inspect --format='{{.State.Health.Status}}'` | unhealthy |
| 磁盘使用率 | `docker system df` | > 85% |
| 内存使用 | `docker stats --no-stream` | > 90% |
| 日志大小 | `du -sh /app/logs` | > 1GB |
> **说明**: 基础设施问题仅告警+记录，解决依赖数据中心团队。
---
## 3. 规则引擎设计
### 3.1 影响级别定义
| 级别 | 定义 | 处理方式 |
|-----|------|---------|
| **P0 - 紧急** | 核心业务完全不可用 | 自动修复 + 立即通知 |
| **P1 - 高** | 部分功能受损 | 自动修复 + 通知 |
| **P2 - 中** | 非核心功能异常 | 自动修复 + 记录 |
| **P3 - 低** | 轻微异常，不影响使用 | 记录，择机处理 |
### 3.2 修复规则库
| 规则ID | 触发条件 | 影响级别 | 自动修复 | 通知 |
|--------|---------|---------|---------|------|
| **R001** | agents_api 失败 | P0 | 重启backend容器 | 是 |
| **R002** | message_send 失败 | P0 | 检查企微token/刷新 | 是 |
| **R003** | AI/RAG 超时 | P1 | 重启RAGFlow容器 | 是 |
| **R004** | WebSocket断开 | P1 | 重置连接池 | 是 |
| **R005** | redis 连接超时 | P0 | 重启backend | 是 |
| **R006** | postgres 连接失败 | P0 | 重启backend | 是 |
| **R007** | 磁盘空间不足 | P2 | 清理7天前日志 | 是 |
| **R008** | 容器不健康 | P1 | 重启对应容器 | 是 |
### 3.3 规则匹配逻辑
```python
# 伪代码
def match_rule(check_result):
for rule in rules:
if rule.trigger == check_result.type and rule.condition(check_result):
return rule
return None
def process_rule(rule, check_result):
# 评估影响级别
severity = evaluate_impact(check_result)
if rule.auto_fix and severity in [P2, P3]:
# 自动修复
execute_fix(rule.fix_command)
record_audit("AUTO_FIX", rule.id, "success")
elif severity in [P0, P1]:
# 需要通知
notify_admin(severity, check_result)
record_audit("MANUAL_NEEDED", rule.id, "pending")
```
---
## 4. 修复脚本库
### 4.1 脚本目录结构
```
deploy-scripts/
├── health-check/
│ ├── check_all.sh # 全量检查
│ └── check_business.sh # 业务检查
├── fixes/
│ ├── restart_backend.sh # 重启后端
│ ├── restart_nginx.sh # 重启Nginx
│ ├── restart_redis.sh # 重启Redis
│ ├── clear_logs.sh # 清理日志
│ ├── refresh_wecom_token.sh # 刷新企微Token
│ └── restart_ragflow.sh # 重启RAGFlow
└── notify/
└── notify.sh # 企微通知
```
### 4.2 修复脚本示例
```bash
# restart_backend.sh - 重启后端容器
#!/bin/bash
CONTAINER_NAME="wecom_it_backend"
echo "[$(date)] 重启后端容器: $CONTAINER_NAME"
docker compose restart $CONTAINER_NAME
# 等待健康检查通过
for i in {1..30}; do
STATUS=$(docker inspect --format='{{.State.Health.Status}}' $CONTAINER_NAME 2>/dev/null || echo "unknown")
if [ "$STATUS" = "healthy" ]; then
echo "[$(date)] 容器已就绪"
exit 0
fi
sleep 2
done
echo "[$(date)] 容器健康检查超时"
exit 1
```
### 4.3 调用方式（复用 jumpserver-ops）
```python
# 通过 jumpserver-ops 执行远程修复脚本
import subprocess
def execute_fix_script(script_name, server="10.90.5.110"):
"""执行远程修复脚本"""
cmd = [
"python", "jms_ops.py",
"exec", "-c",
f"bash /opt/wecom-it-desk/deploy-scripts/fixes/{script_name}",
"--reuse"
]
result = subprocess.run(cmd, capture_output=True, text=True)
return result.returncode == 0
```
---
## 5. 通知机制
### 5.1 企微机器人通知
**WebHook 地址**: 通过管理后台配置（已有集成能力）
**消息模板**:
```json
{
"msgtype": "markdown",
"markdown": {
"content": "## 🔴 IT服务台告警\n\n" +
"> **级别**: P0-紧急\n" +
"> **问题**: 坐席列表API获取失败\n" +
"> **时间**: 2026-07-09 16:05:00\n" +
"> **自动修复**: 已执行（重启backend容器）\n\n" +
"> **状态**: 修复中...\n\n" +
"> [查看监控面板](https://itsupport.servyou.com.cn/itadmin/)"
}
}
```
### 5.2 通知级别
| 级别 | 通知方式 | 通知对象 |
|-----|---------|---------|
| P0 | 企微机器人 + 电话 | 管理员 + 值班人员 |
| P1 | 企微机器人 | 管理员 |
| P2 | 企微机器人 | 管理员 |
| P3 | 仅记录 | — |
---
## 6. 巡检任务计划
### 6.1 巡检频率
| 任务 | 频率 | 执行方式 |
|-----|------|---------|
| 业务健康检查 | 每5分钟 | 后台定时任务 |
| 基础设施检查 | 每5分钟 | 后台定时任务 |
| 日志清理 | 每天凌晨3点 | Cron |
| 巡检报告 | 每天早上9点 | 定时任务 |
### 6.2 巡检流程
```
┌─────────────────────────────────────────────────────────────┐
│ 定时任务触发（每5分钟） │
└─────────────────────┬───────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. 执行 /api/admin/health-check │
│ 2. 分析最近5分钟错误日志 │
│ 3. 匹配规则库 │
└─────────────────────┬───────────────────────────────────────┘
▼
┌────────────┴────────────┐
▼ ▼
┌─────────────┐ ┌─────────────┐
│ 有异常 │ │ 全部正常 │
└──────┬──────┘ └──────┬──────┘
▼ ▼
┌─────────────┐ ┌─────────────┐
│ 匹配规则 │ │ 更新最后 │
│ → 执行修复 │ │ 正常时间 │
│ → 通知 │ │ → 结束 │
└─────────────┘ └─────────────┘
```
### 6.3 审计记录
所有巡检和修复动作记录到审计日志：
| 字段 | 说明 |
|-----|------|
| id | 记录ID |
| timestamp | 时间 |
| type | AUTO_FIX / MANUAL_NEEDED / NOTIFY |
| rule_id | 匹配的规则ID |
| check_result | 检测结果 |
| fix_result | 修复结果 |
| notified | 是否通知 |
---
## 7. 管理后台集成
### 7.1 监控看板
在管理后台新增"系统健康"模块：
- **实时状态**: 整体健康度指示器（绿/黄/红）
- **各服务状态**: nginx/backend/redis/postgres/AI
- **最近告警**: 最近10条告警记录
- **巡检历史**: 最近7天巡检结果
### 7.2 规则配置
管理后台可配置：
- 启用/禁用某条规则
- 调整阈值
- 开启/关闭自动修复
- 通知人员配置
---
## 8. 实施计划
### 阶段一：基础监控（1-2天）
- [ ] 实现 `/api/admin/health-check` 接口
- [ ] 集成 nginx/backend/redis/postgres 检查
- [ ] 管理后台展示健康状态
### 阶段二：业务监控（1-2天）
- [ ] 坐席列表API监控
- [ ] 消息发送监控
- [ ] AI/RAG服务监控
### 阶段三：自愈能力（2-3天）
- [ ] 规则引擎实现
- [ ] 修复脚本库
- [ ] 自动执行 + 记录
### 阶段四：通知集成（1天）
- [ ] 企微机器人通知
- [ ] 告警模板
- [ ] 通知人员配置
### 阶段五：巡检任务（1天）
- [ ] 定时任务配置
- [ ] 巡检报告
- [ ] 审计日志
---
## 9. 实施记录
### 阶段一：基础监控 ✅ (2026-07-09)
- [x] 实现 `/api/admin/health-check` 接口
- [x] 集成 nginx/backend/redis/postgres 检查
**产出**：
- `backend/app/services/health_check_service.py` - 健康检查服务
- `backend/app/api/admin_api.py` - 健康检查端点
### 阶段二：业务监控 ✅ (2026-07-09)
- [x] 坐席列表API监控
- [x] 消息发送监控
- [x] AI/RAG服务监控
- [x] WebSocket连接监控
### 阶段三：自愈能力 ✅ (2026-07-09)
- [x] 规则引擎实现（8条规则）
- [x] 修复脚本库
- [x] 自动执行 + 记录
**产出**：
- `deploy-scripts/fixes/` - 修复脚本目录
- `restart_backend.sh` - 重启后端
- `restart_redis.sh` - 重启Redis
- `restart_nginx.sh` - 重启Nginx
- `restart_ragflow.sh` - 重启RAGFlow
- `clear_logs.sh` - 清理日志
- `deploy-scripts/health-check/check_all.sh` - 巡检脚本
- `deploy-scripts/rules/auto_healer.py` - 规则引擎
### 阶段四：通知集成 ✅ (2026-07-09)
- [x] 企微机器人通知模块
- [x] 分级通知（P0电话/P1机器人/P2记录）
- [x] 告警模板
**产出**：
- `deploy-scripts/notify/wecom_notifier.py` - 企微通知模块
### 阶段五：定时任务 ✅ (2026-07-09)
- [x] 定时巡检任务（每5分钟）
- [x] 每日报告（早上9点）
- [x] 日志清理（凌晨3点）
- [x] Crontab配置
**产出**：
- `deploy-scripts/health-check/scheduled_check.py` - 定时巡检脚本
- `deploy-scripts/health-check/crontab.example` - Crontab配置示例
### 文件清单
| 文件 | 说明 |
|------|------|
| `backend/app/services/health_check_service.py` | 健康检查核心服务 |
| `backend/app/api/admin_api.py` | 健康检查API端点 |
| `deploy-scripts/fixes/*.sh` | 修复脚本集 |
| `deploy-scripts/health-check/check_all.sh` | 巡检脚本 |
| `deploy-scripts/health-check/scheduled_check.py` | 定时巡检脚本 |
| `deploy-scripts/health-check/crontab.example` | Crontab配置 |
| `deploy-scripts/rules/auto_healer.py` | 规则引擎 |
| `deploy-scripts/notify/wecom_notifier.py` | 企微通知模块 |
---
## 10. 附录
### 10.1 相关文档
- [00-标准故障排查手册](./00-标准故障排查手册.md)
- [11-堡垒机运维工具](./11-堡垒机运维工具.md)
- [蓝绿部署指南](./蓝绿部署指南.md)
### 9.2 参考资源
- jumpserver-ops 工具: `C:\Users\simon\.workbuddy\skills\jumpserver-ops`
- 故障排查手册 CASE 库
---
**维护记录**
| 版本 | 日期 | 变更 |
|------|------|------|
| v1.0 | 2026-07-09 | 初始版本 + 阶段1-5全部实施完成 + 生产部署完成 (10.90.5.110) |
Reference in New Issue View Git Blame Copy Permalink