173 lines
8.9 KiB
Markdown
173 lines
8.9 KiB
Markdown
# API 网关 Web 前端 —— 设计文档
|
||
|
||
> 版本 v0.1(待审)|2026-09-11
|
||
> 对象:`https://127.0.0.1:8808`(网关,端口 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) ──同源──> 127.0.0.1:8808
|
||
├─ /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? |