Files
xiaoyin-gateway/docs/frontend-design.md
T
Jidekin 5f452e10d6 feat!: 项目改名「小银网关」并上线官网 xywg.wangjinding.com
老板要求:AI 网关改名为小银网关,做一个类似小银 Markdown 的官网,
域名 xywg.wangjinding.com,所有内容都改名。

一、改名(只动展示名,不动技术标识)
  · app/main.py:FastAPI title、根接口 name、启动/关闭日志 → 小银网关
  · frontend:index.html + dist/index.html 标题、i18n 的中英文标题
  · README / docs / data/gateway.yaml 注释里的「AI 网关」「API 网关」→ 小银网关
  · 保留 api-gateway 作为目录名 / supervisor 服务名 / python 包名 / 仓库名 ——
    改这些会破坏 import、服务托管和 git 远端,收益为零风险不小

二、官网
  · 复用小银 Markdown 官网的整套 CSS 与版式(同一套视觉语言)
  · 内容按网关重写:首屏(一个网关,接住所有模型)、三大场景、数据块、
    功能九宫格、接口一览(9 个端点)、部署示例、关于
  · 数字都取自实际配置:4 家供应商 / 81 个模型 / 2 万行 Python / v2.9.16
  · 首屏用终端示例代替应用截图(网关没有界面截图,终端最直观)

三、基础设施
  · 1Panel 静态站 + Let's Encrypt 证书(acme.sh 自动续期)
  · EdgeOne 加速域名(回源 HTTPS/8443,Host=加速域名)
  · DNS:xywg CNAME → xywg.wangjinding.com.eo.dnse2.com
2026-11-20 15:37:53 +08:00

8.9 KiB
Raw Blame History

小银网关 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 / OpenCode Go / Dots AI),已具备完整 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?