docs(admin): clarify dashboard key metrics and limitations

Update dashboard summary specification to distinguish between provider
keys (upstream) and internal keys. Change summary metrics to use
`provider_keys` fields for better clarity.

Add section on known limitations regarding time period logic and
missing trend data.
This commit is contained in:
zenfun
2026-01-02 22:07:18 +08:00
parent 0ba94026d4
commit 7b20c35fba

View File

@@ -54,8 +54,8 @@
| 卡片名称 | 端点 | 字段 | 渲染逻辑 |
|----------|------|------|----------|
| Active Keys | `GET /admin/dashboard/summary` | `keys.active` | 整数 |
| Total Keys | `GET /admin/dashboard/summary` | `keys.total` | 整数 |
| Active Provider Keys | `GET /admin/dashboard/summary` | `provider_keys.active` | 整数 (上游凭证) |
| Total Provider Keys | `GET /admin/dashboard/summary` | `provider_keys.total` | 整数 |
| Consumed Tokens | `GET /admin/dashboard/summary` | `tokens.total` | 格式化 (如 892k) |
| Input Tokens | `GET /admin/dashboard/summary` | `tokens.input` | - |
| Output Tokens | `GET /admin/dashboard/summary` | `tokens.output` | - |
@@ -63,6 +63,11 @@
| Total Requests | `GET /admin/dashboard/summary` | `requests.total` | 整数 |
| Failed Requests | `GET /admin/dashboard/summary` | `requests.failed` | 整数 |
> **字段说明**:
> - `provider_keys`: 上游 Provider API 密钥 (model.APIKey)
> - `keys`: Master 生成的子 Token (model.Key),用于内部监控
> - "Active Keys" UI 卡片应使用 `provider_keys.active`
**请求参数**:
| 参数 | 类型 | 说明 |
@@ -71,6 +76,12 @@
| `since` | int | 自定义起始时间 (Unix 秒) |
| `until` | int | 自定义结束时间 (Unix 秒) |
> **已知限制** (待 fix-dashboard-summary-api 实现后解决):
> - `period=week` 使用自然周起点 (周一),非滚动 7 天
> - `period=month` 使用自然月起点 (1号),非滚动 30 天
> - 趋势数据 (delta/trend) 当前不返回,前端需隐藏趋势指示器
> - 建议使用 `since`/`until` 实现精确的滚动时间窗口
### 3.4 告警摘要
**端点**: `GET /admin/alerts?status=active&limit=2&offset=0`