1. 页面概览
LLM 网关页（路由 /admin/llm-gateway）是 AIP 管理后台面向管理员的大模型网关控制台，把平台 LLM 网关的运行态与配置态集中在一页：Provider 状态只读总览（可用性/模型/成本/熔断/健康）、LLM 路由规则与预算限额管理（成本管控，含新增/编辑/删除）、Provider 持久化配置（llm_providers 表列表/编辑/删除，与新增/更新表单，API Key 加密写入）、用量统计面板（summary 指标 + 最近调用记录）以及网关试调。所有请求走 aipClient（/aip-api/v1 → AIP 18080）。
一句话总结：本页是 LLM 网关的「状态台 + 配置台 + 试调台」，管理员在此查看 Provider 健康、调整路由与预算、维护密钥并实时验证调用。
2. 访问入口
- 路由与菜单：path
/admin/llm-gateway、nameAdminLlmGateway、路由 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 持久化配置（llm_providers 表）：[刷新配置列表] |
| 表格：ID|名称|类型|服务地址|默认模型|成本(每1k)|权重|状态|编辑|删除 |
| Provider 配置（新增/更新，API Key 加密写入）：[新增 Provider][更新既有]|
| ID*(更新态)/名称/服务地址/默认模型/每千token成本/权重/API Key/优先级/说明+启用开关|
| [创建 Provider / 保存 Provider] [清空] |
| 用量概览：指标卡 + 最近调用记录表 |
| 网关试调：任务类型+消息 [发送试调][清空结果] → 结果+usage |
+--------------------------------------------------------------+各板块职责：
- Provider 状态：只读展示各 Provider 运行态，空数据显示「暂无 Provider 数据（后端可能未就绪）。」。
- LLM 路由规则（成本管控）：预算信息条 + 路由规则表格；「+ 新增路由」打开新建弹窗（填 task_type/model_alias 与预算、候选、降级链），行内「编辑」弹窗改预算/启用/候选/降级链，行内「删除」二次确认后删行。
- Provider 持久化配置（llm_providers 表）：列表
GET /llm/provider-configs（admin）展示持久化行，行内「编辑」把该行带入下方表单、行内「删除」二次确认后DELETE /llm/providers/:id——删除后 DB 行与运行时池双向收敛；被启用中路由引用或属 config/env 装配的内置 Provider 时后端 409 拒绝，页面如实展示原因。 - 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，删除成功刷新列表并热同步（该任务回落默认降级链） |
| 刷新配置列表 | 持久化配置卡片工具栏 | 重拉 GET /llm/provider-configs（llm_providers 行） |
| 编辑 | 持久化配置表格操作列 | 把该行字段带入下方「更新既有 Provider」表单（免手填主键 ID） |
| 删除 | 持久化配置表格操作列 | window.confirm 二次确认（提示不可撤销、被引用/内置会被拒）后 DELETE /llm/providers/:id；成功刷新配置列表 + 运行时 Provider 状态并提示「已删除并热同步」；409 时展示后端中文原因（列出引用它的任务） |
| 新增/更新既有 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、DELETE /llm/providers/:id、GET /llm/provider-configs（platform/llm/handler.go 的 RegisterRoutes，分别接线仓储 UpsertRoute/DeleteRouteByID/CreateProvider/DeleteProviderByID/ListProviders），前端据此提供真实入口：路由可新增（按 task_type + model_alias 唯一键 Upsert）与删除（二次确认），Provider 可新增（name 唯一，重名 409）、可列表、可删除（二次确认）。Provider 删除的拒绝语义：① 被启用中路由引用 → 409 LLM_PROVIDER_IN_USE（报文列出引用它的 task_type，不产生半删除）；② 内置 Provider（config/env 装配的 deepseek-v4-flash/qwen/local_rule）→ 409 LLM_PROVIDER_BUILTIN（删 DB 影子行不改变运行时池、重启即恢复，停用请改 is_active=false）。删除成功后网关 SyncFromDB 双向收敛（DB 行消失 → 运行时池同步摘除，无幽灵 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 组 |
| DELETE | /llm/providers/:id | 删除 Provider（404 LLM_PROVIDER_NOT_FOUND；被启用中路由引用 409 LLM_PROVIDER_IN_USE；内置 Provider 409 LLM_PROVIDER_BUILTIN），删除后热同步收敛，admin 组 |
| GET | /llm/provider-configs | llm_providers 持久化配置列表（不含密钥密文），供逐行删除，admin 组 |
5.2 关键机制
- DB 优先同步与热同步（双向收敛）：网关启动/种子默认路由后调
SyncFromDB从llm_routes/llm_providers表同步路由与 Provider；管理端点落库后再同步网关内存。该同步为双向收敛——DB 行被删除时，由 DB 装配进运行时池的 Provider 会被移除、DB 行消失的任务路由覆盖会被清除（回落默认链），不留幽灵条目；config/env 装配的内置 Provider 不受 DB 行增删影响。 - 密钥加密存储：
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展示。 - 管理端点已覆盖增删改查：路由为列表 + 新增（
CreateRouteRequest：task_type/model_alias/provider_order/fallback_order/cost_limit_cents/enabled/description，走UpsertRoute幂等写）+ 更新（UpdateRouteRequest）+ 删除（DeleteRouteByID）；Provider 为列表（走ListProviders）+ 新增（CreateProviderRequest：name必填，kind/base_url/api_key/default_model/cost_per_1k/weight/is_active/priority/description可选，走CreateProvider）+ 更新（UpdateProviderRequest）+ 删除（走DeleteProviderByID，含IsConfigProvider内置保护与路由引用检查）。
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），前端路由卡片提供「+ 新增路由」与行内「删除」（二次确认） | |
后端已补 DELETE /llm/providers/:id（接线 DeleteProviderByID）与 GET /llm/provider-configs，网关 SyncFromDB 升级为双向收敛；前端新增「Provider 持久化配置」表提供行内删除（二次确认）。被启用中路由引用（409 LLM_PROVIDER_IN_USE）或内置 Provider（409 LLM_PROVIDER_BUILTIN）时拒绝删除，页面如实展示后端原因 | |
| 内置 Provider 不可删除 | deepseek-v4-flash/qwen/local_rule 由 config/env 装配并登记为内置，DELETE 一律 409；如需停用请用「更新既有 Provider」把 is_active 置 false |
| 路由新增为 Upsert 语义 | POST /llm/routes 以 task_type + model_alias 为唯一键：同名同别名重复提交即更新既有行（返回 200 created:false），而非报冲突，前端提示按「已创建/已更新」区分 |
| 密钥不回显 | 编辑 Provider 时 API Key 留空表示不修改，无法查看已有密钥 |
| 用量口径依赖后端 | summary 指标按后端 recorder 口径聚合，历史窗口与保留策略由后端决定 |