diff --git a/docs/api.md b/docs/api.md
index dda3f66..9e4e834 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -142,6 +142,8 @@ graph TD
 - **上游管理**：ProviderGroup + APIKey 的 CRUD 与批量操作。
 - **模型注册表**：管理全局模型能力，支持从远程 `models.dev` 刷新和回滚。
 - **日志审计**：全站请求日志查询、按条件批量删除日志、配置 Webhook 告警。
+- **Dashboard 统计**：聚合指标摘要、系统级实时 QPS、按小时/分钟统计。
+- **告警管理**：系统告警的查看、确认、解决和统计。
 
 ### 4.2 租户端 (Master API) - 需 Master Key
 - **自服务**：查看租户信息、管理自己的子 Key。
@@ -286,6 +288,176 @@ graph TD
 
 ---
 
-## 6. 备注
+## 6. Dashboard 与告警 API
+
+### 6.1 Dashboard 统计端点
+
+#### 获取 Dashboard 摘要
+`GET /admin/dashboard/summary`
+
+**查询参数**：
+| 参数 | 类型 | 说明 | 默认值 |
+| :--- | :--- | :--- | :--- |
+| `period` | string | 预设周期：`today`, `week`, `month` | `today` |
+| `since` | int | 自定义起始时间 (Unix 秒) | - |
+| `until` | int | 自定义结束时间 (Unix 秒) | - |
+
+**响应示例**：
+```json
+{
+  "period": "today",
+  "requests": {"total": 123456, "success": 120000, "failed": 3456, "error_rate": 0.028},
+  "tokens": {"total": 9876543, "input": 4000000, "output": 5876543},
+  "latency": {"avg_ms": 234.5},
+  "masters": {"total": 10, "active": 8},
+  "keys": {"total": 150, "active": 120},
+  "provider_keys": {"total": 20, "active": 15, "suspended": 3, "auto_disabled": 2},
+  "top_models": [{"model": "gpt-4o", "requests": 50000, "tokens": 2000000}],
+  "updated_at": 1704153600
+}
+```
+
+#### 获取系统级实时统计
+`GET /admin/realtime`
+
+**响应示例**：
+```json
+{
+  "qps": 125,
+  "rpm": 7500,
+  "rate_limited_count": 2,
+  "by_master": [{"master_id": 1, "qps": 50, "rate_limited": false}],
+  "updated_at": 1704153600
+}
+```
+
+#### 日志统计按时间聚合
+`GET /admin/logs/stats?group_by=hour|minute`
+
+**新增 `group_by` 选项**：
+| 值 | 说明 | 时间范围限制 |
+| :--- | :--- | :--- |
+| `hour` | 按小时聚合，返回 `hour` 字段 (ISO 8601) | 无限制 |
+| `minute` | 按分钟聚合，返回 `minute` 字段 (ISO 8601) | **必须提供 `since` 和 `until`，最大跨度 6 小时** |
+
+**示例请求**：
+```bash
+# 按小时统计 (24小时趋势)
+curl "http://localhost:8080/admin/logs/stats?group_by=hour&since=1704067200&until=1704153600" \
+  -H "Authorization: Bearer <admin_token>"
+
+# 按分钟统计 (精细时序，最大6小时)
+curl "http://localhost:8080/admin/logs/stats?group_by=minute&since=1704150000&until=1704153600" \
+  -H "Authorization: Bearer <admin_token>"
+```
+
+**响应示例 (hour)**：
+```json
+{
+  "items": [
+    {"hour": "2025-01-01T10:00:00Z", "count": 1234, "tokens_in": 50000, "tokens_out": 80000, "avg_latency_ms": 234.5}
+  ]
+}
+```
+
+**响应示例 (minute)**：
+```json
+{
+  "items": [
+    {"minute": "2025-01-01T10:30:00Z", "count": 45, "tokens_in": 2000, "tokens_out": 3500, "avg_latency_ms": 180.2}
+  ]
+}
+```
+
+### 6.2 API Key 状态筛选
+
+`GET /admin/api-keys?status=active|suspended|auto_disabled|manual_disabled`
+
+**新增 `status` 参数**：按上游凭证状态过滤，可与 `group_id` 组合使用。
+
+```bash
+# 获取所有激活的上游凭证
+curl "http://localhost:8080/admin/api-keys?status=active" \
+  -H "Authorization: Bearer <admin_token>"
+
+# 获取指定组内已暂停的凭证
+curl "http://localhost:8080/admin/api-keys?group_id=1&status=suspended" \
+  -H "Authorization: Bearer <admin_token>"
+```
+
+### 6.3 告警管理端点
+
+#### 告警类型与严重性
+| 类型 (`type`) | 说明 |
+| :--- | :--- |
+| `rate_limit` | 速率限制触发 |
+| `error_spike` | 错误率飙升 |
+| `quota_exceeded` | 配额超限 |
+| `key_disabled` | Key 被禁用 |
+| `key_expired` | Key 已过期 |
+| `provider_down` | 上游服务不可用 |
+
+| 严重性 (`severity`) | 说明 |
+| :--- | :--- |
+| `info` | 信息通知 |
+| `warning` | 警告 |
+| `critical` | 严重告警 |
+
+| 状态 (`status`) | 说明 |
+| :--- | :--- |
+| `active` | 活动告警 |
+| `acknowledged` | 已确认 |
+| `resolved` | 已解决 |
+| `dismissed` | 已忽略 |
+
+#### 告警端点列表
+| 端点 | 方法 | 说明 |
+| :--- | :--- | :--- |
+| `/admin/alerts` | GET | 列出告警，支持 `status`、`severity`、`type` 筛选 |
+| `/admin/alerts` | POST | 创建告警 |
+| `/admin/alerts/:id` | GET | 获取单个告警详情 |
+| `/admin/alerts/:id/ack` | POST | 确认告警 |
+| `/admin/alerts/:id/resolve` | POST | 解决告警 |
+| `/admin/alerts/:id` | DELETE | 忽略告警 (软删除) |
+| `/admin/alerts/stats` | GET | 获取告警统计 |
+
+#### 创建告警
+```bash
+curl -X POST http://localhost:8080/admin/alerts \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "type": "rate_limit",
+    "severity": "warning",
+    "title": "速率限制触发",
+    "message": "Master research-team 在过去5分钟内触发了100次速率限制",
+    "related_id": 5,
+    "related_type": "master",
+    "related_name": "research-team"
+  }'
+```
+
+#### 获取告警统计
+```bash
+curl http://localhost:8080/admin/alerts/stats \
+  -H "Authorization: Bearer <admin_token>"
+```
+
+**响应示例**：
+```json
+{
+  "total": 100,
+  "active": 5,
+  "acknowledged": 10,
+  "resolved": 85,
+  "critical": 2,
+  "warning": 3,
+  "info": 0
+}
+```
+
+---
+
+## 7. 备注
 - **数据一致性**：控制平面 (CP) 修改配置后，数据平面 (DP) 通过 Redis Pub/Sub 或定期轮询实现最终一致性。
 - **安全性**：请务必妥善保管 `EZ_ADMIN_TOKEN`。Master Key 和子 Key Secret 在数据库中均以哈希形式存储，丢失无法找回，只能重置。