wecom_it_smart_desk/docs/09-部署运维/12-IT服务台业务监控与自愈方案.md

# 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) |