8.6 KiB
8.6 KiB
API 网关 Web 前端 —— 设计文档
版本 v0.1(待审)|2026-09-11 对象:
https://127.0.0.1:8808(网关,端口 8808,已开鉴权,127.0.0.1 反代对外)
1. 背景与目标
网关是一个 OpenAI 兼容的多供应商 LLM 统一接入层(Agnes / 火山方舟),已具备完整 REST 能力(对话/图像/视频/批量/模型/指标/日志/健康)。当前只能通过 curl / 二次开发调用,没有可视化界面。
本前端目标是给这台网关做一个单页管理台(SPA):
- 「用」—— 对话、图像、视频、批量,测试各种模型与降级行为;
- 「看」—— 实时指标、熔断状态、日志、模型/供应商拓扑;
- 「管」—— 连接配置、密钥登录、参数默认值。
定位:面向使用者的管理台,不做开源网关那样复杂的租户/计费/审计。
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. 需要你拍板的点
- 鉴权模式:直接 MVP(key 存浏览器)先上,还是先加网关
/auth/login(更安全,前端不持 key)?(影响 M1 成本) - 前端是否由网关托管(推荐,同源省 CORS)还是独立静态站?
- 页面范围:上面 P0–P9 全要,还是先砍掉部分(如批量/视频)?
- 技术栈:确认 Vue 3 + Vite + TS + Element Plus + ECharts OK?