LLM 网关 · LightAIP · frontend-intro-v5

1. 页面概览

LLM 网关页（路由 /admin/llm-gateway）是 AIP 管理后台面向管理员的大模型网关控制台，把平台 LLM 网关的运行态与配置态集中在一页：Provider 状态只读总览（可用性/模型/成本/熔断/健康）、LLM 路由规则与预算限额管理（成本管控，含新增/编辑/删除）、Provider 持久化配置（新增/更新，API Key 加密写入）、用量统计面板（summary 指标 + 最近调用记录）以及网关试调。所有请求走 aipClient（/aip-api/v1 → AIP 18080）。

一句话总结：本页是 LLM 网关的「状态台 + 配置台 + 试调台」，管理员在此查看 Provider 健康、调整路由与预算、维护密钥并实时验证调用。

2. 访问入口

路由与菜单：path /admin/llm-gateway、name AdminLlmGateway、路由 title「LLM 网关」，位于 AIP 管理后台侧边栏（菜单项「LLM 网关」）；源码 action/web/src/views/LlmGatewayPage.vue。
认证与权限：父路由 /admin 配置 requiresAuth + requiresAdmin，需登录且 aip_is_admin === '1'；请求经 aipClient 附带 aip_token，401 清 token 跳 /login。
端口与 API 前缀：AIP 后端 18080，前端 baseURL /aip-api/v1（Vite 将 /aip-api 重写为 /api）。

3. 界面布局

+--------------------------------------------------------------+
| LLM 网关                                  [刷新]               |
| Provider 状态：名称|类型|可用|模型|成本(每1k)|熔断|健康           |
| LLM 路由规则（成本管控）：预算开关/用户限额/应用限额 [+新增路由][刷新]|
|   表格：ID|任务类型|模型别名|候选Provider|降级链|限额(分)|启用|编辑|删除|
| Provider 配置（新增/更新，API Key 加密写入）：[新增 Provider][更新既有]|
|   ID*(更新态)/名称/服务地址/默认模型/每千token成本/权重/API Key/优先级/说明+启用开关|
|    [创建 Provider / 保存 Provider] [清空]                      |
| 用量概览：指标卡 + 最近调用记录表                                |
| 网关试调：任务类型+消息 [发送试调][清空结果] → 结果+usage          |
+--------------------------------------------------------------+

各板块职责：

Provider 状态：只读展示各 Provider 运行态，空数据显示「暂无 Provider 数据（后端可能未就绪）。」。
LLM 路由规则（成本管控）：预算信息条 + 路由规则表格；「+ 新增路由」打开新建弹窗（填 task_type/model_alias 与预算、候选、降级链），行内「编辑」弹窗改预算/启用/候选/降级链，行内「删除」二次确认后删行。
Provider 配置（新增/更新）：模式切换「新增 Provider」（POST /llm/providers，name 唯一）与「更新既有 Provider」（按 llm_providers 表主键 ID，PUT /llm/providers/:id）；api_key 加密写入，响应不回传密文。
用量概览：summary 指标卡（总调用次数/总 Tokens/平均延迟/成功率/总成本/降级次数）+ 最近调用记录表。

4. 交互元素

控件	位置	含义与作用
刷新	页面头部	并行刷新 providers / routes / usage，加载中禁用
+ 新增路由	路由卡片工具栏	打开新建路由弹窗（task_type 必填、model_alias 留空默认同 task_type、预算、候选、降级链、说明、启用）；提交 `POST /llm/routes` 并热同步
编辑	路由表格操作列	打开「编辑路由 #ID」弹窗：预算限额（分，0=不限）、启用开关、候选 Provider（provider_order）、降级链（fallback_order）、说明；保存 `PUT /llm/routes/:id` 并热同步
删除	路由表格操作列	`window.confirm` 二次确认后 `DELETE /llm/routes/:id`，删除成功刷新列表并热同步（该任务回落默认降级链）
新增/更新既有 Provider	Provider 卡片模式开关	切换表单模式：「新增 Provider」（隐藏 ID 字段，提交 `POST /llm/providers`，name 必填且唯一）与「更新既有 Provider」（按主键 ID 提交 `PUT /llm/providers/:id`）
创建/保存 Provider	Provider 表单	新增模式校验 name 后 POST；更新模式校验 Provider ID 后 PUT，成功后刷新状态表
清空	Provider 表单	重置表单为初始空值并保留当前模式
发送试调	网关试调卡片	`POST /llm/chat`，结果展示 Provider/模型/延迟/成本/降级 + 返回内容 + usage

次要控件：预算 chip、试调「清空结果」、alert「关闭」、is_active 开关；任务类型下拉为 chat/nlq/generate_sql/summarize/esg_report/deep_report。

新增/删除能力已接线（Provider 删除除外）：后端 admin 组已补 POST /llm/routes、DELETE /llm/routes/:id、POST /llm/providers（platform/llm/handler.go 的 RegisterRoutes，分别接线仓储 UpsertRoute/DeleteRouteByID/CreateProvider），前端据此提供真实入口：路由可新增（按 task_type + model_alias 唯一键 Upsert）与删除（二次确认），Provider 可新增（name 唯一，重名 409）。删除 Provider 仍未开放：仓储层无删除方法，且网关 SyncFromDB 只做 Provider 的更新/新增同步、无移除语义（删行会让内存 Provider 池残留幽灵条目），故留待后端补齐后再开放，Provider 卡片内保留一条简短说明。

5. 后端关联

5.1 端点表

方法	路径	用途
GET	/llm/providers	Provider 运行态（name/kind/available/model/cost_per_1k/circuit_state/health），登录组
GET	/llm/usage?limit=100	用量 summary + 最近 records，登录组
POST	/llm/chat	网关试调，登录组
GET	/llm/routes	路由列表 + 预算（enabled/user_limit_cents/app_limit_cents），admin 组
POST	/llm/routes	新增路由（按 task_type+model_alias 唯一键 Upsert；新建 201、命中既有行 200），admin 组
PUT	/llm/routes/:id	部分更新路由，保存后热同步，admin 组
DELETE	/llm/routes/:id	删除路由（不存在 404 `LLM_ROUTE_NOT_FOUND`），删除后热同步，admin 组
POST	/llm/providers	新增 Provider（name 必填且唯一，重名 409 `LLM_PROVIDER_NAME_CONFLICT`；api_key 加密存储），admin 组
PUT	/llm/providers/:id	更新 Provider 配置，api_key 加密存储，admin 组

5.2 关键机制

DB 优先同步与热同步：网关启动/种子默认路由后调 SyncFromDB 从 llm_routes/llm_providers 表同步路由与 Provider；管理端点落库后再同步网关内存。
密钥加密存储：api_key 明文经前端提交，后端用 SECRET_KEY 派生的 AES-256-GCM 主密钥加密落库，响应不回传密文；API Key 留空表示不修改。
成本管控口径：cost_limit_cents 为单次调用预算（0=不限）；路由 enabled=false 时该任务走默认链；预算分用户级与应用级。
错误码：如 LLM_INVALID_REQUEST（400）、LLM_ROUTE_NOT_FOUND（404）、LLM_ROUTE_MGMT_UNAVAILABLE（503）；前端统一取 error/message 展示。
管理端点已覆盖增删改查（Provider 删除除外）：路由为列表 + 新增（CreateRouteRequest：task_type/model_alias/provider_order/fallback_order/cost_limit_cents/enabled/description，走 UpsertRoute 幂等写）+ 更新（UpdateRouteRequest）+ 删除（DeleteRouteByID）；Provider 为新增（CreateProviderRequest：name 必填，kind/base_url/api_key/default_model/cost_per_1k/weight/is_active/priority/description 可选，走 CreateProvider）+ 更新（UpdateProviderRequest）。Provider 删除端点缺失：仓储无对应删除方法，且 SyncFromDB 无 Provider 移除语义，删除会残留内存 Provider，故未提供（见第 8 章）。

6. 权限与安全

页面挂在 /admin 管理组（requiresAdmin），非管理员被前端守卫拦到智能查询页。
Provider 列表/用量/chat 属 protected 登录组（普通用户可测）；路由与 Provider 写接口仅 admin 组可调。
API Key 不回显、AES-256-GCM 加密存储；AIP 内部 LLM 消费默认经 PIIGuard 脱敏，/llm/chat 直接转发端点不脱敏。

7. 常见问题与排错

现象：提示「加载 Provider 列表失败：...」。原因：后端未启动、Token 失效或 Vite 代理未指向 18080。处理：确认 AIP 服务存活、重新登录、检查 /aip-api 代理。
现象：路由表显示「暂无路由规则（后端可能未就绪，或未初始化路由表）」。原因：后端 repo 未配置或 llm_routes 未种子。处理：查看后端日志 SeedDefaultRoutes 是否成功，必要时重启后端种子。
现象：试调或用量报 401 跳登录页。原因：aip_token 过期，拦截器自动清 token。处理：重新登录后重试。
现象：保存 Provider 报 503「路由管理未配置」。原因：网关 repo/db 未注入。处理：检查后端配置，非页面可解决。

8. 已知缺陷与边界

项	说明
Provider 状态只读	状态表为运行时只读，修改需走下方「Provider 配置更新」表单
~~路由增删不可用~~（已修复）	后端 `RegisterRoutes` 已补 `POST /llm/routes`（接线 `UpsertRoute`）与 `DELETE /llm/routes/:id`（接线 `DeleteRouteByID`），前端路由卡片提供「+ 新增路由」与行内「删除」（二次确认）
Provider 删除不可用（后端缺口）	后端已补 `POST /llm/providers`（接线 `CreateProvider`），前端可新增 Provider；但仓储层无删除 Provider 方法，且网关 `SyncFromDB` 无 Provider 移除语义（删除后内存 Provider 池会残留幽灵条目），故 `DELETE /llm/providers/:id` 未提供，Provider 卡片刻有简短说明
路由新增为 Upsert 语义	`POST /llm/routes` 以 `task_type + model_alias` 为唯一键：同名同别名重复提交即更新既有行（返回 200 `created:false`），而非报冲突，前端提示按「已创建/已更新」区分
密钥不回显	编辑 Provider 时 API Key 留空表示不修改，无法查看已有密钥
用量口径依赖后端	summary 指标按后端 recorder 口径聚合，历史窗口与保留策略由后端决定