Files
xiaoyin-gateway/docs/frontend-design.md
T

173 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API 网关 Web 前端 —— 设计文档
> 版本 v0.1(待审)|2026-09-11
> 对象:`https://api.wangjinding.com`(网关,端口 8808,已开鉴权,127.0.0.1 反代对外)
---
> ⚠️ **第二十七轮(2026-09-18)**:路由别名 `wjd` / 多模型 fallback 已**整体删除**。
> 本文里凡是提到「路由别名」「降级链」「fallback_used」的地方,都是当时的设计记录,
> 现状请以 `README.md` 的「三线直传」章节为准。
## 1. 背景与目标
网关是一个 OpenAI 兼容的多供应商 LLM 统一接入层(Agnes / 火山方舟),已具备完整 REST 能力(对话/图像/视频/批量/模型/指标/日志/健康)。当前**只能通过 curl / 二次开发调用,没有可视化界面**。
本前端目标是给这台网关做一个**单页管理台(SPA)**:
1. 「用」—— 对话、图像、视频、批量,测试各种模型与降级行为;
2. 「看」—— 实时指标、熔断状态、日志、模型/供应商拓扑;
3. 「管」—— 连接配置、密钥登录、参数默认值。
> 定位:**面向使用者的管理台**,不做开源网关那样复杂的租户/计费/审计。
---
## 2. 技术选型
| 方案 | 优点 | 缺点 | 结论 |
|---|---|---|---|
| **Vue 3 + Vite + TS** | 轻量、上手快、生态成熟(Element Plus / ECharts / Pinia)、构建快 | 单文件组件学习曲线 | ✅ **推荐** |
| React + Vite + TS | 生态最大、函数式 | 对内部工具偏重、样板代码多 | 备选 |
| Next.js / Nuxt(SSR) | SEO / 首屏好 | 对纯内部工具过度设计 | 不用 |
| 零构建(Alpine.js / 原生) | 无构建链 | 流式/图表/多页难维护 | 不用 |
**选定**:**Vue 3(Composition API)+ Vite + TypeScript**(中重度用于图表、SSE 流式、状态管理)
配套选型:
- **UI 组件库**:Element Plus(表格/表单/弹窗/主题)
- **状态管理**:Pinia(网关连接信息、密钥、全局指标)
- **路由**:Vue Router 4(Hash 模式,方便静态部署不依赖 history 回退)
- **图表**:ECharts(指标时间线、供应商分布、熔断状态)
- **SSE 流式**:原生 `fetch` + `ReadableStream`(聊天流是 POST,不走 EventSource)
- **Markdown 渲染**:`marked` + `highlight.js`(助手消息代码高亮)
**部署形态**:Vue 构建产物(纯静态)由**网关自身挂载托管**(FastAPI 加一个 StaticFiles 挂载,如 `/web` 或 `/`),与网关**同源**:
- 消除跨域、CORS 配置归零;
- 登录密钥走**短时 session 接口**(见 §3),密钥不落浏览器 localStorage;
- 反代 `/web` 与 `/v1/*` 共用同一入口,链路简单。
> 若不想给网关加托管,可退化为"Nginx 单独 serve 静态 + 直连网关"(代价是重新处理 CORS 与密钥暴露),文档按推荐方案展开。
---
## 3. 总体架构与鉴权
```
浏览器 SPA (Vue3) ──同源──> api.wangjinding.com
├─ /web/... 静态资源(Vue 构建产物)
├─ POST /auth/login 登录(验 key → 发短时 Cookie/会话 token)
├─ POST /v1/* 业务调用(带会话凭证)
├─ GET /health /metrics /logs ...
```
**鉴权两种模式(建议渐进)**:
| 模式 | 做法 | 密钥位置 | 说明 |
|---|---|---|---|
| MVP(先上) | 登录页输入网关 `wjd-` key → 存 localStorage/Bearer | 浏览器 | 实现最快;个人工具可接受,但 key 会留在浏览器 |
| 正式(推荐) | 网关新增 `POST /auth/login`:校验 key → 签发**仅本机来源、短时效**的 session(Cookie/内存 token) | 只存网关内存 | 前端不再持有原始 key;需网关加一个轻量登录端点 |
> 设计文档按**正式模式**规划登录交互,MVP 模式仅作回退实现(差异只在"key 存哪里"一层,不影响页面)。
---
## 4. 页面结构与导航
顶部导航(+ 明暗主题切换 + 连接状态指示灯):
```
仪表盘 │ 对话 │ 图像 │ 视频 │ 批量 │ 模型与供应商 │ 指标 │ 日志 │ 设置
```
未登录时强制到「登录页」。以下按页面列功能点。
### P0 登录页
- 输入 API Key(`wjd-...`)+「记住我」;连接成功后显示网关版本
- 错误提示(机构 401/受限 429/连不上)
- 主题(明/暗)记忆
### P1 仪表盘 Dashboard
| 区块 | 展示数据 | 数据源 |
|---|---|---|
| 顶部指标卡 | uptime、版本、请求总数、失败数、失败率、P95 延迟、当前并发 in-flight | `/health`(带 key) |
| 供应商熔断看板 | 每家供应商 CLOSED / HALF_OPEN / OPEN + 失败率 + 限流桶占用 | `/health`(circuit) |
| 请求时间线图 | 请求量/错误量/成功率(ECharts 面积图,近 N 分钟) | `/metrics` |
| 延迟分布 | P50 / P95 趋势折线 | `/metrics` |
| 降级统计 | `fallback` 成功降级次数 | `/metrics` |
| 快捷入口 | 一键跳「对话 / 图像 / 视频」 | — |
### P2 对话 Playground(核心)
- **左栏**:模型/路由选择(下拉:列出各模型 + 路由别名 `wjd` 标徽章)、参数面板:
`temperature`、`max_tokens`、`top_p`、`stream` 开关、`n/seed/user`(高级折叠)
- **主区**:流式对话气泡;助手消息 markdown + 代码高亮;**推理模型显示 `reasoning_content`**(学 DeepSeek 折叠"已深度思考")
- 每条消息脚标:`served_model`、是否 `fallback`、耗时、`total_tokens`、估算 cost
- 多轮 function calling 结果可视化(工具调用卡片)
- 工具栏:清空 / 复制对话 / 「强诊降级」按钮(演示 wjd 从 6 模型逐个降级)
- 流式中断可停止;网络断显示重试
### P3 图像 Playground
- 选模型(图像类)、`prompt`、`size`、`n`(几张)、参考图(URL 或上传)
- 生成中 loading;结果网格大图 + 点击放大(lightbox)
- 显示耗时 / tokens / cost
### P4 视频 Playground
- 选模型、`prompt`、`seconds`、`mode`、`size`、参考帧
- **等待方式**:`wait=true` 轮询进度条,或 `callback_url`(可选填公网回调)
- 任务列表:历史视频 + 状态 + 播放器预览;下载/重试
### P5 批量 Batch
- 文本区一次粘贴多条(每行一个 prompt)或上传 JSON;`max_concurrency` / `items` 上限提示(网关 16/64)
- 结果表:每条 ok / 耗时 / 输出 / 错误;导出 CSV/JSON
- 进度条(已完成/总数)
### P6 模型与供应商
- `/v1/models` 全量列表:按供应商分组、类型徽章(对话/图像/视频/路由)
- 路由别名详情:`wjd` 的优先级链 + 每模型 `retry`/`timeout` + 熔断状态
- 供应商健康:`/health/{provider}` 一键探活,显示远端模型数/可达性
- (只读展示,不改配置)
### P7 指标 Metrics
- ECharts 图表:请求量、错误率、延迟(P50/P95)、并发、上游选路分布
- 原始 Prometheus 文本查看 / 复制(`/metrics/prometheus`)
### P8 日志 Logs
- `/logs?n=` 滚动日志流;按级别(WARN/ERROR)、`rid`、模型过滤;跟随/暂停;复制
- 异常时间点自动高亮
### P9 设置 Settings
- 网关连接信息(Base URL、版本、服务器时间)
- 密钥「重新登录 / 登出」
- 参数默认值(temperature / max_tokens / stream)、主题、会话清理
- 关于(版本、上游供应商)
---
## 5. 关键交互 / 技术要点
- **流式**:`fetch POST /v1/chat/completions` + `ReadableStream` 逐帧解析 SSE,边到边渲染;控制台显示 `[DONE]`。
- **分页/刷新策略**:Dashboard 指标每 5s 轮询;日志「跟随」模式节流轮询。
- **错误统一**:401→回到登录;429→面板提示"已触发限流";502→提示"该模型已全部降级失败"。
- **响应式**:桌面为主,平板可用;宽屏三栏(模型|对话|详情)折叠为抽屉。
- **安全**:正式模式下 key 只存网关内存;前端不含任何密钥/上游 token;无第三方 CDN(自托管静态,防供应链)。
---
## 6. 里程碑(分期交付)
| 阶段 | 内容 | 验收 |
|---|---|---|
| M1 骨架 | 脚手架 + 登录 + 布局 + 路由 + 连接 & 鉴权打通 | 能登录、能拉 `/health`/`/models` |
| M2 对话 | 流式对话 + 参数 + 降级可视化 + markdown | 核心可用 |
| M3 媒体 | 图像/视频/批量三页 | 三类调用可完成 |
| M4 运维 | 仪表盘 + 指标 + 日志(图表/过滤) | 运维视图可用 |
| M5 打磨 | 设置、主题、导出、响应式、错误处理 | 可交付 |
预计 M1-M4 为周期主体,M5 为打磨收尾。
---
## 7. 需要你拍板的点
1. **鉴权模式**:直接 MVP(key 存浏览器)先上,还是先加网关 `/auth/login`(更安全,前端不持 key)?(影响 M1 成本)
2. **前端是否由网关托管**(推荐,同源省 CORS)还是独立静态站?
3. **页面范围**:上面 P0–P9 全要,还是先砍掉部分(如批量/视频)?
4. **技术栈**:确认 Vue 3 + Vite + TS + Element Plus + ECharts OK?