# 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?