# 权限系统监控仪表板 ## 概述 权限系统监控仪表板提供了权限系统运行状态的实时可视化，包括权限检查性能、缓存效率、告警信息和系统健康状态。 --- ## 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