网关面板功能设计 v2

在现有 panel.html 基础上扩展。延续玻璃拟态设计（navpage 的 design.md tokens）。参考 litellm 面板的分模块思路，适配"个人自用 → 多用户"的场景。

1. 定位与原则

• 定位：自建 Go 网关的控制台，一个页面承载"看用量、管密钥、看日志、管模型、改设置"。
• 受众：自己 + 未来分发的用户（只读自己的用量）。
• 设计原则：玻璃拟态延续、瑞士排版、单页应用（侧边栏导航）、零 CDN、原生 SVG 图表。
• 分层：当前单文件 panel.html 会撑爆，改为「单 HTML 内联 CSS/JS，JS 里按模块组织」，仍无构建步骤。

2. 布局

┌────────────┬──────────────────────────────┐
│  侧边栏     │  主内容区                     │
│  (毛玻璃)   │  (各模块卡片)                 │
│            │                              │
│  ▤ 概览     │  ┌──────────────────────┐   │
│  ▤ 用量     │  │ 模块标题 + 操作区      │   │
│  ▤ 密钥     │  └──────────────────────┘   │
│  ▤ 模型     │  ┌──────────────────────┐   │
│  ▤ 日志     │  │ 内容卡片/表格/图表     │   │
│  ▤ 设置     │  │                      │   │
│            │  └──────────────────────┘   │
└────────────┴──────────────────────────────┘

侧边栏毛玻璃 + 图标 + 文字，选中态用 --accent 高亮。移动端侧边栏收成顶部横条。

3. 模块设计

3.1 概览 Dashboard

目的：一眼看清"花了多少、用了多少、健康不健康"。

功能	说明	数据来源
汇总卡片 ×4	今日成本、今日 token、今日请求、成功率	GET /api/dashboard
成本趋势图	近 7 天每日成本折线（SVG）	/api/usage/timeseries
模型分布	各模型成本占比（横向条形）	/api/usage/grouped?by=model
最近请求	最新 5 条（key/模型/状态/成本）	/api/logs?limit=5
快捷入口	"创建 key"、"看日志"按钮	—

3.2 用量 Usage

目的：多维度分析用量，回答"谁用了什么、花了多少"。

功能	说明
时间范围	今日 / 7 天 / 30 天 / 全部（下拉）
分组维度	按模型 / 按 key / 按用户(owner) / 按协议（切换 tab）
趋势图	所选范围内成本+token 双轴折线
分布图	当前维度各分组成本柱状图
明细表	分组列 + 成本/token/请求/成功率，可排序
导出 CSV	明细表一键导出（纯前端生成）

3.3 密钥 Keys

目的：管理虚拟 key 的完整生命周期。

功能	说明
key 列表	名称、归属(owner)、agent、额度(已用/上限+进度条)、状态、请求数、创建时间
创建 key	表单：名称/归属/agent 类型/额度；提交后明文一次性弹窗
吊销	确认后 enabled=false（保留历史）
轮换	生成新 key、旧 key 失效
编辑额度	调整 quota_limit
key 明细	点进单个 key：它的用量汇总 + 最近请求
筛选	按归属、状态、名称搜索

3.4 模型 Models

目的：查看模型路由与价格（config.yaml 的可视化）。

功能	说明
模型列表	模型名、供应商、协议数、input/output 单价
路由详情	展开看每个协议的 upstream URL + 上游 model 名
价格说明	显示缓存计价规则（读×0.1、写×1.25）
在线编辑	（可选/后期）改 config.yaml + 热加载，需后端 POST /api/models + 校验

3.5 日志 Logs

目的：追踪请求、排查失败。

功能	说明
日志列表	时间、key、模型、协议、状态(绿/红)、token、成本、延迟、request_id
筛选	按状态(成功/失败)、key、模型、协议
分页	前/后翻页
错误详情	失败请求展开看 error 原因
单条详情	完整 usage（input/output/cache 明细）

3.6 设置 Settings

目的：管理面板自身的安全与配置。

功能	说明
修改面板口令	改 PANEL_PASSWORD（改后立即生效）
上游 key 管理	查看 DeepSeek/MiniMax key 是否已配置（只显示状态，不显示明文），可重新录入
系统信息	版本、数据库连接状态、启动时间、进程内存

4. 后端 API 扩展清单

现有：/api/keys(GET/POST)、/api/keys/revoke、/api/usage。需新增：

端点	用途	对应模块
GET /api/dashboard	概览聚合（今日汇总+最近请求）	概览
GET /api/usage/timeseries?days=7	按天聚合（趋势图）	概览/用量
GET /api/usage/grouped?by=model|key|owner|protocol&from=&to=	多维度聚合	用量
GET /api/logs?key=&model=&status=&limit=&offset=	请求日志查询+筛选	日志/概览
GET /api/logs/{id}	单条日志详情	日志
GET /api/models	模型路由+价格（读 config）	模型
POST /api/keys/{hash}/rotate	轮换 key	密钥
POST /api/keys/{hash}/quota	编辑额度	密钥
GET /api/keys/{hash}	单 key 明细（用量+最近请求）	密钥
POST /api/settings/password	修改面板口令	设置
GET /api/settings/upstream	上游 key 状态	设置

5. 数据模型补充

现有 3 张表够用，日志查询依赖 usage_logs 的 status/error/request_id/created_at 索引。需补一个索引：

CREATE INDEX idx_usage_created ON usage_logs (created_at DESC);
CREATE INDEX idx_usage_status ON usage_logs (status);

（key_id、model 的查询也可建索引，量大后再加。）

6. 优先级建议

阶段	内容	理由
P0（先做）	布局改造（侧边栏）+ 用量多维 + 日志列表	价值最高：能看到"谁花了多少"+ 排查失败
P1	概览 dashboard + key 明细/轮换/额度编辑	补齐管理闭环
P2	模型可视化 + 设置 + 导出 CSV	锦上添花

7. 反模式（延续 design.md）

• ❌ 引入 React/Vue 框架（保持单文件零构建）
• ❌ 引入 Chart.js/ECharts（用原生 SVG）
• ❌ 深色为主、多彩配色（延续浅色玻璃拟态）
• ❌ 功能堆一页不分组（必须侧边栏分模块）

8. 实际落地状态（2026-08-15）

设计稿全部落地，部分超出设计稿。关键变化：

密钥（§3.3）→ 落地 + 增强：

• 卡片式列表（替代表格）：状态点 + 名称 + 归属 + 额度进度条（>80% 橙 / >100% 红）+ 允许模型摘要 + 请求数
• 操作收敛到「···」菜单（查看用量/编辑/轮换/吊销，危险标红），点空白关闭
• 创建密钥独立弹窗（「+ 创建密钥」主按钮）
• 可访问模型权限（allowed_models，多选勾选，非手打逗号）
• key 前缀脱敏展示（sk-9865c****）
• 编辑密钥用结构化表单 modal（非 prompt）

模型（§3.4）→ 升级为渠道管理（超出设计稿）：

• 配置进 PG（channels/models 表），面板增删改 + 热更新，config.yaml 退化为种子
• 渠道：增删改 + key 录入 + 测试（余额连通 + 模型真实调用）+ 余额 + 拉取模型 + 启用禁用
• 模型：完整表单（客户端名 + 上游模型名 + 多协议勾选 + 端点自动填 + 价格）
• 拉取模型自动配协议/端点/价格（前端 PROVIDER_BASE + PROVIDER_PRICING 映射）
• 一个模型多协议 = 纯透传多路由（无损，区别于中转站的格式转换）

通用交互：

• 余额/余量两种展示（balance 金额 / quota 百分比），按渠道 balance_type 动态
• 时间显示转本地时区（toLocaleString）
• 错误不再静默（fetch 失败弹 toast）

未做的（P2 遗留）：日志单条详情页、用量时间范围切换、结构化表格排序、移动端响应式。