ctms/backend/MONITORING_DASHBOARD.md

# 权限系统监控仪表板

## 概述

权限系统监控仪表板提供了权限系统运行状态的实时可视化，包括权限检查性能、缓存效率、告警信息和系统健康状态。

---

## API 端点

### 1. 获取权限系统指标

**端点**: `GET /api/v1/permission-monitoring/metrics`

**描述**: 获取权限检查和缓存的运行指标

**响应示例**:
```json
{
  "check_metrics": {
    "total_checks": 1000,
    "allowed_checks": 950,
    "denied_checks": 50,
    "total_time": 5.234,
    "min_time": 0.001,
    "max_time": 0.05,
    "avg_time": 0.005,
    "allow_rate": 95.0,
    "deny_rate": 5.0,
    "error_rate": 0.1,
    "errors": 1
  },
  "cache_metrics": {
    "total_accesses": 1000,
    "cache_hits": 850,
    "cache_misses": 150,
    "cache_invalidations": 5,
    "hit_rate": 85.0,
    "miss_rate": 15.0
  },
  "uptime_seconds": 3600
}
```

**关键指标**:
- `total_checks`: 总权限检查次数
- `allowed_checks`: 允许的检查次数
- `denied_checks`: 拒绝的检查次数
- `avg_time`: 平均权限检查耗时（秒）
- `allow_rate`: 允许率（百分比）
- `cache_hits`: 缓存命中次数
- `hit_rate`: 缓存命中率（百分比）

---

### 2. 获取缓存统计

**端点**: `GET /api/v1/permission-monitoring/cache-stats`

**描述**: 获取缓存的详细统计信息

**响应示例**:
```json
{
  "cache_items": {
    "project_permissions_count": 10,
    "member_role_count": 50,
    "total_count": 60
  },
  "cache_metrics": {
    "total_accesses": 1000,
    "cache_hits": 850,
    "cache_misses": 150,
    "cache_invalidations": 5,
    "hit_rate": 85.0,
    "miss_rate": 15.0
  }
}
```

**关键指标**:
- `project_permissions_count`: 项目权限缓存项目数
- `member_role_count`: 成员角色缓存项目数
- `hit_rate`: 缓存命中率

---

### 3. 获取告警列表

**端点**: `GET /api/v1/permission-monitoring/alerts`

**参数**:
- `level` (可选): 告警级别过滤 (info, warning, error)
- `limit` (可选): 返回的最大告警数，默认 100

**响应示例**:
```json
{
  "total": 5,
  "alerts": [
    {
      "timestamp": 1715692800.123,
      "level": "warning",
      "type": "slow_permission_check",
      "message": "权限检查耗时过长: 52.34ms",
      "data": {
        "elapsed_time": 0.05234
      }
    },
    {
      "timestamp": 1715692799.456,
      "level": "error",
      "type": "permission_check_error",
      "message": "权限检查出错: database connection timeout",
      "data": {
        "error": "database connection timeout"
      }
    }
  ]
}
```

**告警类型**:
- `slow_permission_check`: 权限检查耗时过长（>50ms）
- `permission_check_error`: 权限检查出错

---

### 4. 权限系统健康检查

**端点**: `GET /api/v1/permission-monitoring/health`

**描述**: 获取权限系统的健康状态

**响应示例**:
```json
{
  "status": "healthy",
  "health_score": 95,
  "issues": [],
  "metrics": {
    "check_metrics": { ... },
    "cache_metrics": { ... },
    "uptime_seconds": 3600
  },
  "cache_stats": { ... }
}
```

**健康状态**:
- `healthy`: 健康（分数 >= 80）
- `degraded`: 降级（分数 50-80）
- `unhealthy`: 不健康（分数 < 50）

**健康评分规则**:
- 初始分数: 100
- 错误率 > 1%: -20
- 缓存命中率 < 50%: -10
- 平均响应时间 > 10ms: -10
- 权限拒绝率 > 50%: -5

---

### 5. 重置指标

**端点**: `POST /api/v1/permission-monitoring/reset-metrics`

**描述**: 重置所有累积的指标数据

**响应示例**:
```json
{
  "message": "指标已重置"
}
```

---

### 6. 清除告警

**端点**: `POST /api/v1/permission-monitoring/clear-alerts`

**描述**: 删除所有累积的告警记录

**响应示例**:
```json
{
  "message": "告警已清除"
}
```

---

## 监控指标详解

### 权限检查指标

| 指标 | 说明 | 目标值 |
|------|------|--------|
| `total_checks` | 总权限检查次数 | - |
| `allowed_checks` | 允许的检查次数 | - |
| `denied_checks` | 拒绝的检查次数 | - |
| `allow_rate` | 允许率（百分比） | > 90% |
| `deny_rate` | 拒绝率（百分比） | < 10% |
| `avg_time` | 平均权限检查耗时 | < 10ms |
| `min_time` | 最小权限检查耗时 | - |
| `max_time` | 最大权限检查耗时 | < 100ms |
| `error_rate` | 错误率（百分比） | < 1% |
| `errors` | 错误次数 | 0 |

### 缓存指标

| 指标 | 说明 | 目标值 |
|------|------|--------|
| `total_accesses` | 总缓存访问次数 | - |
| `cache_hits` | 缓存命中次数 | - |
| `cache_misses` | 缓存未命中次数 | - |
| `hit_rate` | 缓存命中率（百分比） | > 80% |
| `miss_rate` | 缓存未命中率（百分比） | < 20% |
| `cache_invalidations` | 缓存失效次数 | - |

---

## 告警规则

### 性能告警

**慢速权限检查**
- 触发条件: 权限检查耗时 > 50ms
- 级别: warning
- 建议: 检查数据库性能或缓存配置

### 错误告警

**权限检查错误**
- 触发条件: 权限检查抛出异常
- 级别: error
- 建议: 检查错误日志，排查问题

---

## 监控最佳实践

### 1. 定期检查健康状态

```bash
# 每5分钟检查一次健康状态
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/permission-monitoring/health
```

### 2. 监控缓存命中率

```bash
# 检查缓存统计
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/permission-monitoring/cache-stats
```

**目标**: 缓存命中率 > 80%

### 3. 监控权限检查性能

```bash
# 获取权限系统指标
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/permission-monitoring/metrics
```

**目标**: 平均响应时间 < 10ms

### 4. 监控告警

```bash
# 获取最近的告警
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/permission-monitoring/alerts?limit=20"
```

### 5. 定期重置指标

```bash
# 每天重置一次指标，用于日报
curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/permission-monitoring/reset-metrics
```

---

## 故障排除

### 问题1: 缓存命中率低（< 50%）

**可能原因**:
1. 缓存 TTL 过短
2. 缓存失效频率过高
3. 权限变更频繁

**解决方案**:
1. 增加缓存 TTL（默认 5 分钟）
2. 检查权限变更频率
3. 优化权限更新逻辑

### 问题2: 权限检查响应时间长（> 50ms）

**可能原因**:
1. 数据库查询慢
2. 缓存未命中
3. 并发请求过多

**解决方案**:
1. 检查数据库性能
2. 增加缓存 TTL
3. 添加数据库索引

### 问题3: 权限检查错误率高（> 1%）

**可能原因**:
1. 数据库连接问题
2. 权限配置错误
3. 并发修改问题

**解决方案**:
1. 检查数据库连接
2. 验证权限配置
3. 检查并发修改逻辑

---

## 集成示例

### Python 客户端

```python
import requests

# 获取权限系统指标
response = requests.get(
    "http://localhost:8000/api/v1/permission-monitoring/metrics",
    headers={"Authorization": f"Bearer {token}"}
)
metrics = response.json()

# 检查缓存命中率
cache_hit_rate = metrics["cache_metrics"]["hit_rate"]
if cache_hit_rate < 80:
    print(f"警告: 缓存命中率低 ({cache_hit_rate}%)")

# 检查平均响应时间
avg_time = metrics["check_metrics"]["avg_time"]
if avg_time > 0.01:  # 10ms
    print(f"警告: 权限检查响应时间长 ({avg_time*1000:.2f}ms)")
```

### JavaScript 客户端

```javascript
// 获取权限系统健康状态
async function checkPermissionHealth() {
  const response = await fetch(
    'http://localhost:8000/api/v1/permission-monitoring/health',
    {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    }
  );
  const health = await response.json();
  
  console.log(`健康状态: ${health.status}`);
  console.log(`健康分数: ${health.health_score}`);
  
  if (health.issues.length > 0) {
    console.warn('发现问题:', health.issues);
  }
}
```

---

## 仪表板建议

### 实时监控仪表板

建议使用 Grafana 或类似的可视化工具创建实时监控仪表板，包括：

1. **权限检查性能**
   - 平均响应时间趋势
   - 允许/拒绝率
   - 错误率

2. **缓存效率**
   - 缓存命中率趋势
   - 缓存项目数
   - 缓存失效频率

3. **系统健康**
   - 健康分数
   - 告警数量
   - 系统状态

4. **告警面板**
   - 最近的告警
   - 告警趋势
   - 告警分布

---

**文档版本**: 1.0  
**最后更新**: 2026-05-14