docs(api): add apikey-stats time range and internal alerts report endpoints

Document two new API endpoints:
- GET /admin/apikey-stats/summary with optional since/until params
  for querying statistics within a specific time range
- POST /internal/alerts/report for Data Plane to report alerts
  with fingerprint-based deduplication mechanism
This commit is contained in:
zenfun
2025-12-31 14:25:55 +08:00
parent 57797f38cb
commit dab07caca2

View File

@@ -456,6 +456,72 @@ curl http://localhost:8080/admin/alerts/stats \
}
```
### 6.4 APIKey 成功率统计时间范围
`GET /admin/apikey-stats/summary?since=<unix>&until=<unix>`
**新增时间范围参数**:可选的 `since` 和 `until` 参数,用于获取特定时间段内的上游凭证统计。
```bash
# 获取今天的统计
curl "http://localhost:8080/admin/apikey-stats/summary?since=1704067200&until=1704153600" \
-H "Authorization: Bearer <admin_token>"
# 获取全量统计(不传时间参数)
curl "http://localhost:8080/admin/apikey-stats/summary" \
-H "Authorization: Bearer <admin_token>"
```
**响应示例**
```json
{
"total_requests": 50000,
"success_requests": 48000,
"failure_requests": 2000,
"success_rate": 0.96,
"failure_rate": 0.04
}
```
### 6.5 DP 告警上报 (内部接口)
`POST /internal/alerts/report`
**内部端点**:供 Data Plane 上报异常事件给 Control Plane需要 `X-Internal-Token` 认证。
**去重机制**
- 每个告警可携带 `fingerprint` 字段(如 `rate_limit:master:5`
- 若 5 分钟内存在相同 fingerprint 的活跃告警,新告警将被去重
```bash
curl -X POST http://localhost:8080/internal/alerts/report \
-H "X-Internal-Token: <internal_token>" \
-H "Content-Type: application/json" \
-d '{
"alerts": [
{
"type": "rate_limit",
"severity": "warning",
"title": "速率限制触发",
"message": "Master production 在1分钟内触发50次限流",
"related_id": 5,
"related_type": "master",
"related_name": "production",
"fingerprint": "rate_limit:master:5"
}
]
}'
```
**响应示例**
```json
{
"accepted": 1,
"deduplicated": 0,
"errors": []
}
```
---
## 7. 备注