ctms/backend/MONITORING_DASHBOARD.md

权限系统监控仪表板

概述

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

---

API 端点

1. 获取权限系统指标

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

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

响应示例:

{
  "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

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

响应示例:

{
  "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

响应示例:

{
  "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

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

响应示例:

{
  "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

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

响应示例:

{
  "message": "指标已重置"
}

---

6. 清除告警

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

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

响应示例:

{
  "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. 定期检查健康状态

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

2. 监控缓存命中率

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

目标: 缓存命中率 > 80%

3. 监控权限检查性能

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

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

4. 监控告警

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

5. 定期重置指标

# 每天重置一次指标，用于日报
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 客户端

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 客户端

// 获取权限系统健康状态
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