# API Gateway 统一多供应商 LLM 接入网关,纯后端 FastAPI,配置驱动。支持 **Agnes AI**、**火山方舟 Coding Plan**、**OpenCode Go** 三个供应商,全部走 OpenAI 兼容协议。v2.4 已集成熔断、限流、图像/视频、指标、成本估算、热加载、测试等完整能力。 ## 特性 - ✅ 多供应商统一分发(`model` 决定供应商) - ✅ **三线直传**:`/v1/chat/completions`(OpenAI)· `/v1/messages`(Anthropic)· `/v1/responses`(Responses)三条线各按**自家协议原样转发**,网关不翻译字段; 模型支持哪几条线由 `models[].protocols` 声明,选错线**直接 400**并列出支持的线 - ✅ 同模型重试 + **供应商熔断器**(chat 与媒体各自独立桶) - ✅ 图像 `/v1/images/generations` + 视频 `/v1/videos`(异步 + 等待模式 + Webhook) - ✅ 页面账号体系鉴权(账号密码登录 + 每账号自建 API Key,两级限流**全局/供应商**) - ✅ 用量指标 `/metrics` + **Prometheus** `/metrics/prometheus` + 访问日志 `/logs` - ✅ **Token 成本估算**(响应带 `estimated_cost_cny`) - ✅ **Batch 并发调用** `/v1/chat/completions/batch` - ✅ OpenAI 兼容:`/v1/models` 标准端点 + OpenAI 格式错误 + 标准可选参数全透传 - ✅ 配置热加载、`X-Request-ID` 贯穿、CORS(覆盖 413/400 短路响应)、gzip、请求体限制、优雅关闭 - ✅ 安全:恒定时间 key 比较、webhook 回调 SSRF 防护、开放代理启动告警、请求 ID 消毒 - ✅ 本地即开即用:`python run.py` 一键启动 + 配置热重载 + 单元测试 ## 架构 ``` api-gateway/ ├── data/gateway.yaml # 默认运行时配置(run.py 读取,hot_reload 开) ├── app/ │ ├── config.py # YAML 加载 → dataclass(供应商/模型/协议线/鉴权/熔断/可观测/定价) │ ├── models.py # Pydantic 请求/响应模型(chat/image/video/batch) │ ├── routing.py # model_id → 供应商解析 + 认证解析(名字沿用;与「路由别名」无关) │ ├── metrics.py # 用量指标 + 访问日志 + 限流(无外部依赖) │ ├── circuit.py # 供应商熔断器(CLOSED/OPEN/HALF_OPEN) │ ├── main.py # FastAPI 主入口(全部端点 + 中间件) │ └── adapters/ │ ├── __init__.py # 适配器工厂 │ ├── base.py # 抽象基类(chat / chat_stream / image / video) │ └── openai_compat.py # OpenAI 兼容适配器(四家通用 + 媒体端点) ├── tests/test_gateway.py # 单元测试(mock 供应商,不依赖真实网络) ├── Makefile # 快捷命令(install/run/test/lint/clean) ├── run.py # 启动入口 └── requirements.txt # 锁定版本 ``` ## 供应商与模型 | 供应商 | Base URL | 认证 | 模型 | |---|---|---|---| | Agnes AI | `https://api.agnes-ai.cn/v1` | Bearer | `agnes-3.0-flash`、`agnes-2.5-flash`(text,支持图像输入)、`agnes-image-2.5-flash`(image)、`agnes-video-2.5-flash`(video) | | 火山方舟 Coding | `https://ark.cn-beijing.volces.com/api/coding/v3` | Bearer | `ark-code-latest`(text) | | OpenCode Go | `https://opencode.ai/zen/go/v1` | Bearer + `x-opencode-session` | 35 个模型,含 **1 个免费**(`space-bunny-free`,见下方小节) | > OpenCode Go 是每月订阅的编程模型入口(不在订阅内按 token 额外计费)。官方硬性要求每个 > `/chat/completions` 带 **`x-opencode-session`**(缺失直接 400),并建议专属 `User-Agent`。 > 网关通过供应商 `requires_session_header: true` 动态注入该头,且**该头不能放静态 > `extra_headers`**(适配器缓存会把它冻结)。会话 id 的取值逻辑(方案 A + 第二十六轮加固): > 前端对话页为「同一段对话」维持一个稳定 `conversation_id` 并随请求带来;**纯 API 调用**则在请求体 > 里带同名字段(用 OpenAI SDK 时放 `extra_body={"conversation_id": ...}`)。网关**不原样透传**, > 而是派生成 `sha256("{账号}:{conversation_id}")[:32]` 再作为 `x-opencode-session` 发往上游: > 同一账号的同一段对话**恒定不变**(给上游一个语义正确的「对话级」标识,而不是每请求一个随机值), > 不同账号之间**天然隔离**(两人碰巧用了同一个字符串,也不会共用同一个上游会话标识); > 请求未带(或传空白串)时回退为每次请求一个随机 UUID(仍能过强校验)。 > > - **关于提示词缓存(实测更正,2026-09-18):不要指望用稳定会话 id 来吃缓存。** > 多轮实测(真实 key、长 prompt 约 940 token)显示 `cached_tokens` 与该头**没有稳定关系**: > 同一 session 连打 6 次得到 `[0,0,0,0,896,896]`(前 4 次未命中,之后才命中); > 等缓存落定后**换全新 session** 打同一 prompt,也是「命中 936」与「不命中 0」混合出现。 > 上游确实有内容前缀缓存(命中时能看到大比例 `cached_tokens`),但它是**机会性的**、与 session > 值无关,推测受上游多实例/缓存分片/写入延迟影响。该头的真实作用是上游的**会话标识** > (缺失直接 400),网关保证的只是「同一段对话 → 稳定标识」这一语义。 > - `conversation_id` 是网关内部字段(在 `ChatRequest` 显式声明),**不会透传给上游**。 > - **取值限制**:仅 ASCII、两端空白自动剥掉、最长 128 字符。它最终要进 **HTTP header**—— > 传中文时 httpx 组 header 会抛 `UnicodeEncodeError`,若不在入站拦住就会被误判成"上游失败" > 并重试 3 次、最终回 502(第二十六轮已修:这类非法值入站即 **422**,且**一次都不发上游**)。 > - 建议用 `uuid4().hex`,或用 `用户:对话` 这类你自己可控且稳定的值。 > > 收录 **35 个**模型(2026-09-21 按上游 `GET /models` + 官方文档表刷新,每条线的可用性都真实调用验过): > > - ⭐ **免费**:`space-bunny-free`(Space Bunny Free)—— 官方价格表标 Free / Free / Free、 > 额度 Unlimited(限时)。三处都标注了:配置里 `free: true`、`/v1/models` 带 `free` 字段、 > 前端「模型与供应商」页把绿色「免费」标签**放在模型名后面**(`display_name` 也带「(免费)」)。 > - ❌ **Zen 免费档(`*-free`)网关用不了,别再试**:实测(2026-09-21,用 **两把不同的 key** 各验一遍)—— > 在线免费清单只有 9 个(models.dev 里那 29 个大部分已下线 → `400 Model is unavailable.`); > 剩下的调 Zen 端点一律 `403 FreeTierError: OpenCode's free tier can only be used from within OpenCode` > (**服务端客户端锁定**,换 key 无效);付费 Zen 模型则是 `402 Insufficient account funds`。 > 唯一能用的 `space-bunny-free` 靠的是它在 **Go 计划**里(已收录,`free: true`)。 > - `chat/completions` 线:`glm-5.3-flash`、`glm-5.3`、`glm-5.2`、`glm-5.1`、`kimi-k2.7-code`、 > `kimi-k2.6`、`longcat-2.0`、`mimo-v2.5`、`mimo-v2.5-pro`、`mimo-v2.6-flash`、`mimo-v2.6-pro`、 > `omen-alpha`、`hy4-preview`、`hy3` > - `chat/completions` + `messages`:`kimi-k3`、`minimax-m3`、`minimax-m2.5`、`qwen3.8-max`、 > `qwen3.8-flash`、`qwen3.7-max`、`qwen3.7-plus`、`qwen3.6-plus`、`space-bunny-free` > - `messages` 线:`minimax-m2.7` > - `responses` 线:`grok-4.6`、`grok-4.7`、`gpt-5.6-luna`、`gpt-6-luna`、 > `muse-spark-1.3-contributor`、`muse-spark-1.2-contributor` > - 三线全通:`deepseek-v4.1-flash`(视觉)、`deepseek-v4-pro`、`deepseek-v4-flash`、 > `deepseek-v4-flash-vision-exp`(视觉)、`deepseek-flash` > > 本轮变化:新增 7 个(`deepseek-flash` / `grok-4.7` / `omen-alpha` / `gpt-6-luna` / > `mimo-v2.6-flash` / `mimo-v2.6-pro` / `space-bunny-free`),下线 1 个(`union-alpha`,上游已 retire)。 > 文档未收但上游有的(`deepseek-flash` / `omen-alpha`)按实测收录并注明。 > Agnes 的图像/视频走自有端点,通过供应商配置里的 `media` 段指定。 ## 虚拟模型 id(别名 `wjd`,第三十一轮) 给客户端一个**名字固定**的入口:客户端永远只写 `model: wjd`,实际转发到你选的哪个真实模型 由管理员在网页上决定 —— 上游模型换名字、换版本、换供应商,客户端一行代码都不用改。 **怎么配**:网页「供应商与模型」页有一张「虚拟模型 id(别名)」卡片 → 下拉选目标模型 → 「保存映射」。 **保存即生效**(走 `PUT /config`,不重启网关)。也可以直接改配置文件的 `aliases` 段: ```yaml aliases: wjd: enabled: true # false = 这个 id 不存在(客户端调用得到「未知模型」) target: opencode/deepseek-v4.1-flash # 必须是已配置的**文本**模型且支持 chat/completions note: "给客户用的固定入口" # 备注,只给人看;简写 `wjd: opencode/deepseek-v4.1-flash` 亦可 ``` **四条边界**(都在保存期校验,手改 YAML 同样拦,不靠前端自觉): 1. **只走 `chat/completions`(OpenAI)格式** —— 用 `/v1/messages`、`/v1/responses` 打 `wjd` 会在入口 **400** 并把目标模型名一并告诉你(网关不做跨格式转换,与三线直传的边界一致)。 因此**目标模型必须支持 `chat/completions`**:页面上其余模型置灰不可选,服务端同样拒绝。 2. **目标必须是存在的文本模型** —— 图像/视频模型在 yaml 里没写 `protocols`、看着像 OpenAI 线, 但真正的调用端点是 `/v1/images/generations` 之类,拿别名去聊天只会把上游 400 转给用户, 所以直接拦掉。别名 id 也不得与真实模型 id 重名。 3. **别名不复制目标的配置** —— 协议线、视觉能力、强制参数(`params`)、定价全部**继承 target**, 只有一份事实来源,改目标就整体切换;别名自己只有 `enabled` / `target` / `note` 三个字段。 4. **别名不是模型** —— 它出现在 `GET /v1/models`(带 `alias_of` 指向真实目标,方便客户端发现), 但不进 `/v1/models/speedtest`(测速请测它的目标模型)、不进模型计数、也不进成本/指标口径 (那些一律记在**真实模型**上)。 **看到的现象**:响应里 `model` 回显客户端请求的名字(`wjd`)、`served_model` 是真实目标 (流式同样口径:元信息帧与每个 chunk 都只报 `wjd`,真实目标只在 `served_model`); 访问日志 `model` / `served` 两列分别记请求名与真实模型,改指向的每次变更都会写一条 `虚拟模型 id 改指向(页面保存(<账号>)/配置热重载): wjd → …` 的日志。 **权限**:读靠登录凭据即可(普通账号在页面上只看到一行只读的映射);**改**只有 `admin` 用 **网页会话**能改(API Key 改不了)—— 沿用 `PUT /config` 既有的 `_require_admin + _require_session`。 > 与第二十七轮删掉的「路由链 / `routes`」无关:那套是**按 API Key 选链路、可多跳**;别名是 > **一对一指针**("这个名字转发给谁")。二者混在一起后没人看得懂配置,所以 `routes` 不会复活, > 配置里残留的 `routes` 段依旧只告警不解析。 ## 配置 所有数据从 yaml 读取,改供应商/模型/端点/熔断/限流只改配置文件,不改代码。 ### 供应商(含 media 媒体端点) ```yaml providers: agnes: name: "Agnes AI" base_url: "https://api.agnes-ai.cn/v1" auth: { token_env: "AGNES_API_KEY" } # token 走 env/.env,yaml 不再存明文 extra_headers: {} media: # 图像/视频端点(可选) image_endpoint: "/images/generations" video_create_endpoint: "/videos" video_poll_base: "https://api.agnes-ai.cn" video_poll_path: "/agnesapi" video_model_name: "agnes-video-2.5-flash" models: - { id: "agnes-3.0-flash", display_name: "Agnes 3.0 Flash", type: "text" } # params(可选,第二十五轮):该模型发往上游前**强制覆盖**的参数,用于应对上游硬约束。 # kimi-k2.7-code 只接受 temperature=1,写死后客户端传什么值都按 1 发(含一键测速探针)。 - id: "kimi-k2.7-code" display_name: "Kimi K2.7 Code" type: "text" params: { temperature: 1 } ``` 认证优先级:**环境变量 > yaml 里的 `token` 字段**。 **模型级强制参数 `models[].params`(第二十五轮)**:网关在组装完请求(**在 `extra` 逃生舱之后**)才应用它,所以客户端改不动 —— 目的就是"上游只接受某个值,别让用户踩雷"。允许的键:`temperature`、`top_p`、`top_k`、`max_tokens`、`min_tokens`、`presence_penalty`、`frequency_penalty`、`repetition_penalty`、`seed`、`logit_bias`、`n`;`model` / `messages` / `stream` / `tools` 这类**结构性键被刻意排除**(放行等于让配置文件改写路由与协议语义)。键名写错或值类型不对 → 启动/保存配置时直接 `ConfigError`,不会静默失效。`GET /v1/models` 会回 `params`,前端据此标挂锁。 此外还有一层运行时兜底:上游若回 400 说某参数"只允许 X"(`invalid temperature: only 1 is allowed for this model`)或"必须大于 N",网关会自动按上游要求修正并**重发一次**,并把这个值记在适配器实例上(后续请求不再多跑一轮);日志会提示建议把它写进 `params`。管理员已写死的值不会被自动改掉(冲突时只记日志)。 ### 三线直传(chat/completions · messages · responses)+ 熔断 三条协议线各有自己的入口,**入站格式 = 出站格式**:网关只做四件事 —— 鉴权、挑供应商、 定点改 `model` 与强制参数、把响应(含 SSE)原样推回并读 usage 记账。**不做跨格式翻译**: 把 chat 线的模型打到 `/messages` 上,上游回的是 `500 Internal server error`;把 messages 线的模型打到 `/responses` 上回的是 `401 not supported for format` —— 两种都不像"格式选错", 所以网关**在入口直接 400** 并列出该模型实际支持哪些线,不让这种事拖成半天排查。 | 线 | 入站端点 | 出站鉴权 | |---|---|---| | `chat/completions` | `POST /v1/chat/completions` | `Authorization: Bearer` | | `messages` | `POST /v1/messages` | `x-api-key` + `anthropic-version` | | `responses` | `POST /v1/responses` | `Authorization: Bearer` | 模型支持哪几条线写在各供应商的 `models[].protocols`;**不声明 = 只认 `chat/completions`** (Agnes / 火山方舟即如此,行为与改造前完全一致)。OpenCode Go 的 **35 个模型**按**实测**逐一 标线(`deepseek-v4.1-flash` / `deepseek-v4-pro` / `deepseek-v4-flash` / `deepseek-v4-flash-vision-exp` / `deepseek-flash` 三线全通)。`GET /v1/models` 会回 `protocols`,前端据此标格式。 **路由别名 `wjd` 已于第二十七轮(2026-09-18)整体删除**:不再有 `routes` 配置段、不再有 多模型 fallback、`/v1/models` 里也没有 `type: "route"` 条目。理由:三线直传下模型 id 必须与 协议线一一对应,再套一层"自动挑最快模型"的别名,会把调用方选定的格式与能力(视觉 / 工具 / 协议线)悄悄换掉。**要换模型就换 model id。** 老配置里残留的 `routes` 段会被忽略(日志一条 warning),不会让进程起不来。限流因此变成**两级:供应商 > 全局**。 ```yaml circuit: # 供应商熔断 enabled: true failure_threshold: 3 # 窗口内失败 ≥3 次即熔断 cooldown: 30 # 熔断持续 30 秒 window: 10 # 滑动窗口 = 最近 N 次调用(按次数,非按时间) ``` > **第二十七轮(2026-09-18):路由别名已整体删除** —— 下面这些路由相关修复 > (`fallback_total`、`route.retry`、`routes` 维度指标、路由级限流/超时、路由告警) > 随之一起移除,保留为历史记录。 > > v2.3:`window` 现在真正按**最近 N 次调用**生效(之前是写死 60 秒、配置无效)。判定 = 最近 `window` 次里失败数 ≥ `failure_threshold`。 > > **修复(v2.5)**: > - 媒体端点限流真正接线:`/v1/images/generations`、`/v1/videos` 现在确实按 `providers..rate_limit_rps` 供应商桶限流(此前该逻辑只定义未调用,属死代码)。 > - 全局 `server.rate_limit_rps` 不再依赖鉴权开关:auth 关时统一按 anonymous 桶限流,全局 QPS 始终生效。 > - 流式 fallback 增强:模型在**发出任何 content 之前**失败(如首字前断连),会回退到链上下一个模型;一旦已输出 content 则无法回退(避免破坏 SSE 流)。 > - 视频 webhook 回调的 `status` 按真实状态上报,`failed` 不再误标为 `completed`。 > - 适配器增加在途占用计数:热重载/关闭适配器时会等待在途请求(含流式)排空后再真正关连接,避免掐断正在进行的请求。 > - 新增 `smoke_test.py`:对运行中的网关做健康/模型/chat/batch/错误格式冒烟检查(网关未启动或缺失真实 key 时优雅跳过)。 > > **修复(v2.6)**: > - 指标更真实:`fallback_total` 只统计**成功降级**,全模型失败(502)不再污染该计数;`/metrics` 的 `routes` 现在记录真实的 ok/fail(此前恒为 0),并新增按路由维度的成功率。 > - `route.retry` 整条链统一:路由存在时链首也使用 `route.retry`(此前链首误用全局 `server.retry`)。 > - 媒体限流与 chat **共用同一供应商桶** `prov:`(此前媒体用独立桶,实际放行量翻倍,与文档不符)。 > - 热重载保留运行时状态:不再清空熔断状态 / 调用指标 / 访问日志 / 限流令牌桶(此前整体重建,刚熔断的坏供应商会被立刻恢复重试、指标与日志清零);`hot_reload_interval` 改为每轮读取,改配置即时生效;重载后重新打印路由告警。 > - CORS 改为**动态**:每次请求实时读取 `cors_origins`,热重载改来源即时生效(含 OPTIONS 预检),不再需要重启。 > - 健壮性:`/metrics` 快照全程持锁(并发下不再抛 `dictionary changed size during iteration`);`provider_health` 的 `reachable` 仅 2xx 时为真(此前 401/500 也误报可达);视频等待模式的 `wait_timeout` 钳制上限 600s,轮询期间尊重熔断;适配器缓存 key 纳入 token 指纹(环境变量换 token 可刷新)。 > - 配置校验:`load_config` 对缺供应商 / 缺 `base_url` / 空模型链等结构错误抛 `ConfigError`(友好中文说明),启动与热重载均可拦下。 > - 错误语义:未知模型/路由改为直接 **400**(客户端错误),不再走到 fallback 尽头后以 502(上游错误)误导性返回(chat 与 batch 入口均生效)。 > - 启动脚本 `run.py` 单一配置来源(不再双重加载),并采用配置里的 `observability.log_level`。 > - 清理死代码(未使用的 `ChatResponse`/`Usage`/`Choice`、`RouteInfo.effective_timeout`、`AuthConfig.type`);补齐测试(route 指标、快照并发、配置校验、媒体限流、413 体积限制、动态 CORS、鉴权开关、全局限流、流式 SSE、batch 并发、视频 webhook 真实状态、未知模型 400),测试数 24 → 37。 > > **修复(v2.7)**: > - `routing.ModelNotFoundError` 消息不再重复前缀,`model_id` 只存裸模型名(此前把整句当 `model_id`,报错形如「未知模型: 未知模型 '…'」)。 > - **请求体校验失败改为 OpenAI 兼容格式**:补 `RequestValidationError` 处理器,缺字段/类型错返回 `{"error":{"message","type":"invalid_request_error","code":"422"}}`(此前 FastAPI 默认 `{"detail":[...]}`,OpenAI SDK 无法解析)。 > - 畸形 `Content-Length` 请求头改为 **400**(此前进 `int()` 抛异常 → 500);体积检查只对 POST/PUT/PATCH/DELETE 生效,GET/HEAD/OPTIONS 直接放行。 > - `in_flight` 中间件异常时归还计数(修复未捕获异常 → 500 后计数永久 +1 的泄漏)。 > - 性能:模型查找改为 O(1) 索引(`GatewayConfig._model_index`),不再每请求线性扫描。 > - 限流桶首次请求也消耗 token(消除等效 cap+1 的突发)。 > - 热重载禁用熔断时复位已 OPEN 的 breaker,立刻恢复放行。 > - 图像默认档位提为配置项 `media.image_default_size`(默认 1K 兜底,去掉硬编码)。 > - 工程化:`Makefile` 的 `2>nul` 改为 `2>/dev/null`(原为 Windows 语法,Linux 下会误建 `nul` 文件);两份 yaml 补关系说明并删除已废弃的 `auth.type`。测试数 37 → 44。 > **修复(v2.8)**: > - **【P0】无法停服**:lifespan 里的 `loop.add_signal_handler(SIGTERM/SIGINT)` 覆盖了 uvicorn 自己的信号处理器,导致 `supervisorctl stop` / `Ctrl+C` 停不下来(只能等超时被 `kill -9`,在途请求被硬切、连接池不优雅关闭)。已移除自注册,实测 SIGTERM → 0.5s 内优雅退出。 > - **流式 fallback 指标记反**(v2.6 修复的漏网):流式路径**全失败也计 `fallback_total`、成功降级却完全不计**,与非流式语义相反。现已对齐:只有成功降级才计入。 > - **`/batch` 丢弃 `extra`**:`BatchRequest.extra` 从未传进单项请求 → 批量调用无法透传供应商参数(如 Agnes `chat_template_kwargs`),静默失效。已修复并写入 `max_concurrency` 实测值。 > - **`/batch` 防滥用**:`max_concurrency` 客户端可控(可传 1e5)、条目数只受 2MB 限制 → 自伤型 DoS。新增 `server.batch_max_concurrency`(钳制)与 `server.batch_max_items`(超出 400)。 > - **视频轮询**:① 无 `model` 时不再"猜第一个支持视频的供应商"(任务 ID 是供应商私有的,猜错必然 404/502);改为单供应商才推断、多供应商必须显式指定,并统一走 `_resolve_media_model`(支持路由别名);② `wait=true` 的轮询不再因一次瞬时抖动整段 502,改为记录失败后继续等到 deadline;③ 补上 `record_call`/`record_latency` 指标;④ 返回状态兼容 `state` 字段(此前只认 `status`,上游用 `state` 时会一直显示 `pending`)。 > - **媒体熔断桶独立**:图像/视频终于会喂熔断器(此前媒体调用完全不记录,而视频轮询却拿 chat 的桶做 `allow()` 检查 —— 一边永不计、一边永远查,检查形同虚设)。现用独立的 `#media` 桶,既拦住坏媒体供应商,又避免"客户端坏 prompt 导致上游 4xx"把 chat 熔断误打开。 > - **安全 · SSRF**:视频 `callback_url` 此前无任何校验,可让网关 POST 到任意地址(含 `169.254.169.254`、`127.0.0.1` 等)。现仅允许 http/https,默认拦截回环/私网/链路本地/保留/多播地址(域名会做异步 DNS 解析后校验,防"指向内网的域名"绕过),内网回调可用 `server.webhook_allow_private: true` 放行。 > - **安全 · 开放代理提示**:默认 `host=127.0.0.1`(只监听回环,安全);一旦把 `host` 改成非回环地址且 `auth.enabled=false`,启动会打醒目 WARNING —— 此时同网段任何人都能白用你配置的上游 Key,`/metrics`、`/logs` 也会暴露。 > - **安全 · 其它**:API key 比较改用 `hmac.compare_digest`(恒定时间,防时序侧信道);`auth.enabled=true` 但 `users` 为空时 `validate_config` 直接报错(此前会静默全站 401 自锁);`X-Request-ID` 做字符/长度消毒(防响应头与日志注入);`/health` 与 `/v1/models` 不再回显上游 `base_url`(内部拓扑)。 > - **OpenAI 兼容性**:`ChatRequest` 之前会**静默丢弃**未声明的标准参数(`n` / `presence_penalty` / `frequency_penalty` / `seed` / `user` / `response_format` / `logprobs` / `top_logprobs` / `parallel_tool_calls` / `stream_options`)。现已显式声明并透传,未知字段也不再丢弃(`extra="allow"` 原样透传 + 记日志)。 > - **CORS 覆盖短路响应**:`limit_body` 中间件在 CORS 外层,导致体积超限的 413 **不带 CORS 头**(浏览器只能看到 CORS 报错、读不到真实原因)。现把 CORS 注册到最外层,413/400 均带 CORS 头(已实测)。 > - **SSE 抗坏行**:上游发非 JSON 行(`data: ping` keep-alive、半截行)此前会抛异常**中断整个流**;现在跳过坏行继续。 > - **其它健壮性**:`rate_limit_rps` 写成字符串(`"5"`)不再在 `rps * 2` 处崩(配置层强转 `float`);请求体分块读取出错时不再静默放行而是 400(避免 handler 拿到不完整 body 报出无关的 422);Prometheus 标签值转义(模型名含 `"`/`\` 不再产出非法指标文本);P95 改用最近秩(此前 `int(n*0.95)` 在 20 倍数时取到最大值,退化成 P100);跨供应商重复模型 id 出启动告警。测试数 44 → 58(含本轮 14 项回归;顺带修掉"缺 pytest 时用例假红"的假红灯)。 > - 文档:修正 `media:prov:` 旧桶名残留(与 v2.6 说明自相矛盾)。 > **修复(v2.9 · 第六轮复查)**:本轮由三路独立审计(并发/生命周期、安全与配置、接口契约)交叉复核,P0×1、P1×8、P2×20+ 已全部处理: > - **【P0】`extra` 可劫持路由与协议**:`extra={"model": ...}` 会覆盖网关已解析的模型 → 用你的上游 Key 调**任意(更贵/未登记)模型**并绕过计费口径;`extra={"stream": ...}` 还能让非流式客户端收到 SSE(502)。现在 `model/messages/stream/tools/tool_choice` 等核心键一律剔除(`models.PROTECTED_PAYLOAD_KEYS` + 适配器侧兜底),视频路径用更窄的 `PROTECTED_VIDEO_KEYS`(保留 `first_frame` 等模式字段)。 > - **【P1】熔断器会被永久卡死**:HALF_OPEN 的试探令牌只发不收 —— 只要拿到令牌后没走到 `record()`(限流跳过、凭证缺失、客户端断连的 `CancelledError`),该供应商就**永远**被拒(只能重启)。现修三处:限流跳过前 `release_probe()` 主动归还、探测超时兜底(`probe_timeout`)、`allow()` 在 HALF_OPEN 下超时自愈回 OPEN。两位审计员用不同路径独立实测复现。 > - **【P1】`close()` 会关掉正在使用的连接池**:`close()` 先在锁内判定 `_active==0`、出锁后再关闭,两步之间的并发 `get_client()` 会把计数加到 1 并拿到那个 client,随后它被 `aclose()` → 在途请求 `RuntimeError: client has been closed`。现将"判定 + 关闭"合并进同一次持锁。 > - **【P1】`in_flight` 指标双缺陷互相掩盖**:① `except Exception` 抓不到 `CancelledError` → 客户端断连时计数永久 +1;② `isinstance(response, StreamingResponse)` 在 Starlette 1.6 下**恒为假**(`call_next` 返回的 `_StreamingResponse` 不是它的子类)→ 流式请求被"中间件 + 生成器"双重递减。现统一为 `try/finally` 只减一次,语义=「进入 → 响应头生成完毕」(**v2.10 进一步修正为"响应体发送完毕"**,见下)。 > - **【P1】function calling 多轮对话直接坏掉**:`Message` 此前只有 `role/content`,assistant 的 `tool_calls`、tool 消息的 `tool_call_id` 被静默丢弃 → 能发起工具调用,但回传历史时报错。现补全字段并改用 `to_upstream()` 透传。 > - **【P1】媒体端点凭证缺失漏出 500**:images/videos 的 `_get_adapter` 在 `try` 之外,供应商没配 token 时抛 `AuthConfigError` → 500 纯文本(与 chat 的 502/503 不一致)。现已纳入 `try` 并区分映射(凭证缺失 503、模型不可用 404,且不计入熔断)。 > - **【P1】异步回调后台任务无人管理**:新增 `_spawn_bg` 后关停时任务被硬切、`callback_url` 静默丢通知;lifespan 现在会等待(最多 5s)再取消,并且热重载的 adapter 字典改为**先原子摘除再关闭**(此前"先关后置空"会让并发请求新建的连接池成为孤儿,永远不被 close)。 > - **契约修复**:全失败 502 错误体 `error.error` → `error.message`(OpenAI 规范);流式首个 meta 帧与末尾 usage 帧补齐 `id/created/object=chat.completion.chunk/choices`(此前不是合法 chunk,严格校验的 SDK 直接报错);`/v1/models` 的 `data` 统一 `object="model"` 并补 `created/owned_by`(此前混入 `object="route"`);`/batch` 单项错误不再输出 Python dict repr;图像补 `created`;上游返回非 JSON/空 body 不再是 `Expecting value: line 1 column 1`。 > - **入参校验**:空 `messages` 与 `"stream": "yes"`(类型拼错)改为入参处 422,而不是打到上游变 502;图像请求未声明的标准参数(`quality/style/...`)不再静默丢弃。 > - **安全/健壮性**:`callback_url` 端口非法(`:99999`)→ 400(此前未捕获 `ValueError` → 500);`video_id` 等客户端可控字段进日志前剥离控制字符(防 `%0a` 伪造日志行);未捕获异常的 500 现在**带 CORS 头**(此前由最外层 `ServerErrorMiddleware` 生成,绕过 CORS,浏览器只看到 CORS 报错);配置解析全面加固(`null`/负数/非数字一律给出带字段名的 `ConfigError`,不再启动期 `TypeError` 崩进程或运行期 `httpx.Timeout("abc")` 每次 500);`health_auth=true` 但未开鉴权、以及"通配 CORS + 无鉴权"现在都会出启动告警;`/` 与 `/health/{provider}` 纳入 `health_auth` 保护(后者会用网关的 Key 主动探上游)。 > - **其它**:流式 `break` 后显式 `aclose()` 上游生成器(不再依赖 GC 来归还 lease);`estimated_cost_cny` 不再在上游无 usage 时报假 `0.0`;Prometheus 输出补 `# HELP/# TYPE`。测试数 58 → 78。 > **修复(v2.10 · 第七轮回归复查)**:把 v2.9 的全部改动交给独立审计员做**回归专项**复核(逐行推演 + 80 用例 + 只读运行时实测),抓到 **1 个本轮新引入的高危倒退** + 4 个中低风险项,已全部修复: > - **【P1·新引入】标准参数被静默丢弃**:v2.9 给 `_build_payload` 加 `strip_protected(extra)` 防 `extra` 劫持,但用的是**宽集合** `PROTECTED_PAYLOAD_KEYS`,而它恰好包含 `_PASSTHROUGH` 里全部 10 个键(`n/seed/user/response_format/logprobs/top_logprobs/parallel_tool_calls/stream_options/presence_penalty/frequency_penalty`)—— 刚塞进 extra 又被删掉,`_PASSTHROUGH` 机制事实上被废掉。实测:带 `response_format`/`seed`/`n` 的请求到上游只剩 `model/messages/stream`。现拆成三套集合:适配器侧只剔**自己刚写入的核心键**(`models.CHAT_CORE_KEYS`),客户端 extra 禁写集仍是宽集合(`upstream_extra()` 已挡,放行无风险)。**触发面**:任何用 `response_format`(JSON 模式)、`seed`、`n`、`user`、penalty、`logprobs*` 的 chat/batch 请求。 > - **【P2】图像 `response_format`/`user` 被误删**:图像路径同样用了宽集合,与 `ImageRequest` docstring(明说这些走 `model_extra` 透传)自相矛盾。现改用图像专用窄集 `PROTECTED_IMAGE_KEYS`(只挡 `model/prompt/size/n/image/images`),`quality/style/response_format/user` 正常透传。 > - **【P2】流式期间 `in_flight` 提前归零**:`call_next` 在收到 `http.response.start` 就返回(body 由外层继续迭代),故 v2.9 的"响应头生成完毕即减"会让 SSE **传输期间**读数为 0(实测 `yield#1` 起就是 0)。现把递减挂到响应体迭代结束/中断(包一层 `body_iterator`),语义=「进入 → 响应体发送完毕」。活体实测:877 帧的流式请求全程 `in_flight=2`(流本身 + 采样请求),结束后正确归位、`in_flight_peak` 无漂移。 > - **【P2】热重载后 `base_url` 改动可能不生效**:适配器缓存 key 不含 `base_url`,而本轮改成"先原子摘除字典再关闭"后,持有旧 cfg 的在途请求仍可能重建 adapter 并写回新字典 → 后续按新配置的请求命中旧地址。现把 `base_url` 指纹并入 `cache_key`。 > - **【P2】死代码**:`BaseAdapter._close_now()` 在 `close()` 改为持锁直调 `_close_now_locked()` 后已无调用点,删除。 > - **无可达风险(已加约束说明)**:`release_probe()` 不校验令牌归属,理论上可能误还并发请求的探测令牌;逐一核对全部调用点后**当前不可达**(同 tick 或 except 分支内无抛错源),已在 docstring 写明"仅令牌持有者、且放行与归还间不得有 await"的前置条件,并给出后续放宽方案(probe token 归属校验)。 > - 审计同时确认**无新问题**:`json_or_raise()` 空/非 JSON body 映射、`Message.to_upstream()` 多轮 function calling、`stream` 严格校验、`unhandled_error_guard` 位于最外层且 500 带 CORS、`release_probe` 常规路径与 `probe_timeout` 自愈、`videos_poll` 404 归还不计失败、`_get_adapter` 移入 try 后的 503/404 映射、`_spawn_bg` 强引用与 lifespan 等待、`_opt_int` 的 `default>=minimum` 逐处正确。测试数 78 → 84(补 4 项回归:标准参数最终 payload、图像额外参数、流式 `in_flight` 时机、`base_url` 缓存 key)。 > **修复(v2.11 · 第二十七轮上线后复验)**:老板批准重启上线后,用真机活体检查(`live_check.py` + 真实 key)复验, > 抓到 **3 个本轮新引入的缺陷**(其中 2 个是"改了 A 处、漏了 B 处"的接线漏改),已全部修复并补测试: > - **【P0】三线直传入门即 500**:`_passthrough()` 里调用 `_enforce_rate_limit()` 时多传了一个参数(5 参 vs 函数 4 参), > 于是**每一次** `POST /v1/messages` / `POST /v1/responses` 都以 `TypeError` → 500「网关内部错误」结束 —— > 正好是本轮的核心功能。真机表现为两条线全灭(chat/completions 线不受影响)。 > - **【P0】`GET /metrics/prometheus` 500**:导出器还在读 `snapshot["fallback_total"]`,而该字段已随路由/fallback 链删除 > → `KeyError`。Prometheus 抓取全断(`/metrics` JSON 不受影响)。已连同它的 HELP/TYPE 声明一起清掉, > 并加断言:**导出的指标必须有 HELP 声明**(防"声明与导出脱节")。 > - **【P0】图像 / 视频的 token 全部没发出去**:本轮把鉴权头改成"按协议线在 `_req_headers` 里组装"后, > `create_adapter` 不再往静态 headers 里塞 `Authorization`,而媒体三个调用点(图像生成 / 视频创建 / 视频轮询) > 仍在用 `self._headers` ⇒ 出站请求一个鉴权头都没有。真机表现:`POST /v1/images/generations` 上游 > 401「未提供令牌」(同一个 key 直接 curl 同一个地址是 **200**)。已加 `_media_headers()` 统一补回。 > - **测试基建(本轮漏检的根因之一)**:`tests/test_gateway.py` 的 `if __name__ == "__main__"` 运行块被夹在 > **文件中间**,运行器只收集"执行到该行时已存在"的 globals ⇒ 定义在它之后的测试在 `make test`(脚本模式)下 > 根本不会跑(`test_image_request_goes_to_requested_model` 白写了一轮)。已把运行块移到文件末尾, > 并补齐 /v1/messages、/v1/responses 的**真发请求**测试(此前零覆盖)。测试数 **165 → 173**,全部通过。 > - 复验结论:`live_check.py` **19 PASS / 0 FAIL / 0 WARN**(含三线直传真实 200、跨线 400、图像生成 200、 > Prometheus 200);图像下载 `/v1/media/download` 实测 560KB PNG 落地正常。 ### 鉴权(页面账号体系 + 每账号 API Key) 鉴权**不写在配置文件里**:账号、密码、API Key 全部由管理台页面维护,持久化在 `data/users.json` (密码只存 PBKDF2 哈希;Key 存 SHA-256 哈希用于鉴权,**另存一份明文**以便页面随时再复制 —— 取舍见下方 「Key 明文回显」;文件权限 600 且已加入 `.gitignore`)。 `data/gateway.yaml` 只剩 `auth.session_ttl_minutes`(会话时长,默认 1440 分钟)一项。 ```yaml auth: session_ttl_minutes: 1440 # 网页登录会话有效期(每次登录重新计时) ``` **两类凭证,职责不同**: | 凭证 | 形态 | 怎么来的 | 能做什么 | |---|---|---|---| | 会话 token | `sess-...`(短时) | `POST /auth/login` 用**账号 + 密码**换取 | 前端全部功能:调模型 + 看自己的指标/日志 + 管自己的 Key;admin 另可在用户管理页看别人的调用日志与生成资产、管账号 | | API Key | `wjd-...`(长期) | 各账号在「API Key」页自建(默认一把都没有);普通账号最多 3 把、admin 不限 | **只能调模型/媒体/指标**;不能改密码、不能铸删 Key、不能管账号 | - 初始管理员 `admin` / `admin`(首次启动自动创建,**登录后请立即改密**);`admin` 是唯一管理员。 - admin 可创建账号:账号名仅字母数字(2~32 位),不填密码时**默认密码 = 账号名**。普通账号看不到别人 的指标与日志,也不能建号(接口 403)。 - **停用 / 启用账号(admin,第二十四轮)**:用户管理页每行一颗「停用 / 启用」。停用后该账号 ①**不能登录**(密码正确也回 403「账号已被停用,请联系管理员」;密码错的人仍旧只看到 401, 不泄露账号是否存在/已被停用);②名下 **API Key 立刻失效**(回 403 说明原因,且不计入鉴权失败 限流 —— 拿得出有效 Key 的人不是暴力破解者);③**已登录会话当场踢掉**。Key 记录**不删除** —— 停用是「暂时关掉」,重新启用后原密码、原 Key 立刻恢复;真要作废凭证就点「吊销全部 Key」。 `admin` 账号永不可停用(唯一管理员被停用后没人能进管理页,只能停机改 `users.json` 救回,故 接口直接拒绝,且启动加载时会把手工写入的 `disabled` 自动恢复并告警),也不能停用自己。 停用状态落在账号记录的 `disabled` / `disabled_at` 两个字段上。 - 普通账号最多 3 把 API Key(到量后页面按钮置灰并给出提示,不再是一句裸 400);**admin 不限数量**。显式设置/修改的密码至少 **8 位**(第三十轮从 4 位提到 8 位:4 位在可离线爆破的空间里几乎等于没设)。 只作用于「建号时显式给密码 / 事后改密」;**登录不做长度校验**,所以既有短口令账号照常能登,只是不能再被改回短口令。 - **Key 明文回显**:创建后页面展示明文,之后随时可在列表里再复制。代价是 `data/users.json` 里额外存一份 明文 Key(该文件权限固定 600、已在 `.gitignore`)。因此 `GET /auth/apikeys` 也只认会话凭证—— 泄漏一把 Key 不该能顺走同账号其它 Key 的明文。此改动之前发的旧 Key 无法反推明文(只回显哈希前缀), 页面会提示「删除后重建」。 **吊销语义(第八轮审计补,之前"删号/改密"根本止不了损)**: | 动作 | 会话 | API Key | |---|---|---| | 删除账号(admin) | 该账号全部会话立即 401 | 随账号记录一起消失 | | **停用账号(admin,第二十四轮)** | 该账号全部会话立即 401,且停用期间**无法重新登录** | 全部 Key 立即 403(Key 记录**保留**,重新启用即恢复) | | 自己改密码 / admin 重置密码 | 该账号全部会话立即 401(含操作者自己,需重新登录) | **不受影响**(Key 与密码无关) | | 「API Key」页删除某把 Key(仅会话可操作) | 不受影响 | 该 Key 立即 401 | | admin 点「吊销全部 Key」(`DELETE /auth/users/{name}/apikeys`) | 不受影响 | 该账号全部 Key 立即 401 | | 正常登出(`POST /auth/logout`) | 仅当前这一个会话失效 | 不受影响 | > **安全基线(2026-09-11 依安全报告加固 + 第八轮补强)**: > - `/healthz`:纯探活,永远只回 `{"status":"ok"}`,不泄露任何信息。 > - `/health`:**未鉴权只回 `{"status":"ok"}`**;带有效凭证才给完整看板。 > - `/health/{provider}`:会用网关 Key 探上游,**一律要求鉴权**(无凭证 → 401)。 > - `/docs`、`/redoc`、`/openapi.json`:默认关闭(`server.docs_enabled=false`),本地开发想开再设 true。 > - 安全响应头:`X-Content-Type-Options: nosniff`、`X-Frame-Options: DENY`、`Referrer-Policy: no-referrer`、`Content-Security-Policy`(网关层已带)。 > - 防暴力枚举:同一来源 IP 每分钟鉴权失败超过 `server.auth_fail_limit_per_min`(默认 20)→ 429; > 登录成功一次即清零该来源计数(避免同出口 NAT 下被前人失败连坐)。 > - 防用户名枚举:账号不存在时也会走一次等代价的 PBKDF2,登录响应耗时不随账号存在与否变化。 > - 全局限流按**账号**归并成桶:同一账号多开几个会话/多建几把 Key 不再成倍放大配额。 > - **产物下载代理**(`/v1/media/download`):出网域名白名单在 `data/gateway.yaml` 的 > `download.allowed_hosts`,只代抓这里列出的域名(含子域)。供应商多一套存储(例如 Agnes 的 > **水印版**产物走另一个 CDN)而没补进白名单 → 页面「下载」按钮 400「该地址不在允许下载的域名白名单内」。 > 换 CDN 记得同步这一行(第三十轮补上水印域名 `maas-watermark-prod-new.cn-wlcb.ufileos.com`)。 > - **视频任务归属**(第三十轮):`GET /v1/videos/{video_id}` 按「创建时登记的 video_id → 账号」判权, > 别的账号拿到 id 也读不到(回 404,不用 403,免得 id 变成存在性探针);admin 放行; > 本次改动之前创建的老任务无登记 → 放行(渐进收紧,不砸正在轮询的流程)。 ### 历史(图像 / 视频 / 对话)落盘 这三类"生成过的东西"以前只存在浏览器里(图像/视频在 `localStorage`、对话在 `sessionStorage`), 于是换设备看不见、关标签页就丢;更糟的是 `setItem` 写失败(配额满)被 `catch {}` 静默吞掉, 表现就是"我生成过的东西怎么没了"。现在统一存服务端: ``` data/history.json # {账号: {类别: [条目…]}},权限 600,已进 .gitignore GATEWAY_HISTORY=<路径> # 可选,测试/多实例时指定 ``` 同目录还有两份运行期状态文件(第三十轮,均可整份删掉、重启从空开始): ``` data/sessions.json # 登录会话(**只存 token 的 sha256**,不存 token 本身),600 data/video_owners.json # 视频任务归属(video_id → 账号),600 GATEWAY_SESSIONS=<路径> / GATEWAY_VIDEO_OWNERS=<路径> # 可选覆盖(测试用) ``` 会话落盘是为了「重启不再把所有人踢下线」;吊销语义不变(改密/删号/停用仍旧立刻失效,且吊销也落盘)。 - **按账号隔离**:普通账号只看得到自己的历史;admin 也只看自己的(历史是个人数据,不是运维数据)。 - **按 id upsert**:带已存在 id → 原地更新(视频"生成中→完成"走这条);新 id → 插到最前。 所以两台设备各自生成不会互相覆盖;也因此**没有**"整份 PUT"那种一提交就把别人抹掉的坑。 - **容量**:对话 50 条(单条可到 512KB,正文不截)、图像/视频各 200 条;单条超限会截断其中的 长字段(视频的 `rawtext` 就是典型);整份文件软上限 4MB,超了按账号削最旧的尾部。 - 前端仍然写一份本地缓存作为离线兜底,但**服务端写不上会明确弹提示**,不再静默丢数据。 - 首次打开某页时,如果服务端为空而浏览器里有旧数据,会自动把旧数据搬上服务端(一次性迁移)。 ### 运维开关(server) ```yaml server: host: "127.0.0.1" port: 8808 timeout: 120 retry: 1 health_auth: false # /health/* 是否也要鉴权 hot_reload: true # 监听 yaml mtime 自动重载(改配置免重启) hot_reload_interval: 15 metrics_enabled: true # 记录调用指标 rate_limit_rps: null # 全局单 user QPS 上限(null=不限) max_body_size: 2000000 # 请求体字节上限(防 DDoS,约 2MB) cors_origins: ["*"] # CORS 允许来源 graceful_shutdown: 30 # 优雅关闭等待秒 # ── 防滥用 / 安全(v2.8;v2.9 起这些键全部做类型/范围校验) ── batch_max_concurrency: 16 # /batch 并发上限(客户端 max_concurrency 会被钳到此值) batch_max_items: 64 # /batch 单次最大条目数(超出返回 400) webhook_allow_private: false # 视频 callback_url 是否允许指向内网/回环(SSRF 防护) docs_enabled: false # FastAPI 文档(/docs、/redoc、/openapi.json)是否开放(安全默认关) auth_fail_limit_per_min: 20 # 同一来源 IP 每分钟鉴权失败上限,超过 → 429(防暴力枚举) ``` ### 可观测性 + 定价 ```yaml observability: log_level: "INFO" log_json: false # true = 结构化 JSON 行日志(接 ELK/CloudWatch) access_log_maxlen: 500 pricing: # 人民币/百万 token,用于估算成本 per_model: agnes-3.0-flash: { input: 0.35, output: 1.00 } ark-code-latest: { input: 0.50, output: 2.00 } # 未配置的模型不返回 estimated_cost_cny ``` ## 启动 ```bash cd api-gateway pip install -r requirements.txt python run.py # 默认读 data/gateway.yaml,端口 8808 ``` 或用 Makefile:`make install`、`make run`、`make test`。 ### 用 .env 提供 token 不想写死在 yaml 也不想像前缀 export 每个 token?在项目根或 `data/` 下放一个 `.env`: ```bash cp .env.example .env # 编辑 .env 填入 AGNES_API_KEY / VOLC_API_KEY / OPENCODE_API_KEY python run.py # 启动时自动读取 .env ``` 优先级:真实环境变量 > `.env`(密钥所在,经各供应商 `token_env` 引用)> yaml 其它字段。 > **两层 `.env`**(第三十轮补文档):`data/.env` 是「网关配置页 → 环境变量」那张卡写的那层, > 用 `load_dotenv(..., override=True)` 加载,**故意压过**项目根 `.env` —— 否则页面里刚改的 > Key 会被根 `.env` 的旧值顶掉。所以本机想把 Key 交给页面管理,就写 `data/.env`(权限 600, > 已进 `.gitignore`)。页面对值的校验:不得含换行/控制字符、长度 ≤4096(换行会让 `.env` > 凭空多出几行、改到别的变量)。 ## API 端点(含 v2.1 新增) | 方法 | 路径 | 鉴权 | 说明 | |---|---|---|---| | `GET` | `/` | 否 | 端点导航 | | `GET` | `/health` | 否(可开) | 运维看板:uptime/失败率/耗时/熔断状态 | | `GET` | `/health/{provider}` | 否(可开) | 供应商探活 | | `GET` | `/models` / `/v1/models` | 是 | 全部模型(含视觉位与支持的协议线)+ 供应商 | | `POST` | `/v1/chat/completions` | 是 | 主接口(chat/completions 线:流式 + 熔断 + 两级限流 + 成本) | | `POST` | `/v1/messages` | 是 | Anthropic `messages` 线直传(同方协议原样进出) | | `POST` | `/v1/responses` | 是 | OpenAI `responses` 线直传 | | `POST` | `/v1/chat/completions/batch` | 是 | 并发多 prompt | | `POST` | `/v1/images/generations` | 是 | 图像生成(`model` 填真实模型 id) | | `POST` | `/v1/videos` | 是 | 视频创建(`wait`/`callback_url`) | | `GET` | `/v1/videos/{id}` | 是 | 视频轮询(`?wait=true`) | | `GET` | `/metrics` | 是 | 用量统计(JSON,含熔断状态) | | `GET` | `/metrics/prometheus` | 是 | Prometheus 文本格式 | | `GET` | `/logs?n=100` | 是 | 最近访问日志(普通账号只看到自己的调用) | | `POST` | `/auth/login` | 否 | 账号密码换短时会话 token | | `POST` | `/auth/logout` | 是 | 吊销当前会话 | | `POST` | `/auth/password` | 是(仅会话) | 改自己的密码,改后全账号会话需重登 | | `GET` / `POST` / `DELETE` | `/auth/apikeys[/{id}]` | 是(仅会话,含只读) | 本账号 API Key:查看(回显明文)/ 创建 / 删除 | | `GET` / `POST` / `DELETE` | `/auth/users[/{name}]` | 是(admin) | 账号管理:列表 / 建号 / 删号(连带吊销会话与 Key) | | `GET` / `POST` / `DELETE` | `/history/{kind}` | 是(写仅会话) | 前端历史(`kind` = chat / images / videos),按账号隔离、按 id upsert | | `DELETE` | `/history/{kind}/{item_id}` | 是(仅会话) | 删除单条历史 | | `POST` | `/auth/users/{name}/password` | 是(admin,仅会话) | 重置某人密码(默认=账号名)并踢掉其会话 | | `PUT` | `/auth/users/{name}/disabled` | 是(admin,仅会话) | 停用 / 启用账号:`{"disabled": true\|false}`(停用=不能登录 + 名下 Key 全失效 + 会话当场踢;Key 记录保留,admin 不可停用) | | `DELETE` | `/auth/users/{name}/apikeys` | 是(admin,仅会话) | 一键吊销某人全部 API Key(长期泄漏时的止损开关) | | `POST` | `/feedback` | 是(仅会话,**管理员不可用**) | 提交意见/建议:正文 ≤2000 字 + 最多 3 张图(data URI 直传,服务端按解码后魔数验类型);admin 提交一律 403 | | `GET` | `/feedback/mine` | 是 | 「我提交过的」:含处理进度 `status` / `note` / `updated` | | `GET` | `/feedback` | 是(admin) | 「用户反馈」收件箱:全部账号,按时间新→旧 | | `PATCH` | `/feedback/{id}` | 是(admin,仅会话) | 更新处理进度:`status` = `pending` / `doing` / `done`,可选处理说明 `note`(≤500 字,提交人可见) | | `DELETE` | `/feedback/{id}` | 是(仅会话,**仅本人**) | 撤回自己提交的反馈(连图片文件一起删):**只有 `pending` 待处理的能撤**;处理中/已处理 → 400,撤别人的 → 403 | | `GET` | `/feedback/media/{id}/{idx}` | 是 | 反馈原图:仅**提交人本人或 admin**;`id` 必须先在库里存在(防路径穿越) | > 「仅会话」= 只接受账号密码登录换来的 `sess-` token,用 API Key 调用返回 403(见上文吊销语义)。 > 媒体端点的 `model` 必须是**真实模型 id**(第二十七轮起路由别名已删除,不再有别名解析)。 ## 关键行为说明(v2.4) - **两级限流**:供应商级 `providers..rate_limit_rps` > 全局 `server.rate_limit_rps`。供应商级按独立桶分桶,打满则 429(chat / 媒体共用 `prov:` 桶);路由级限流随路由功能删除。 - **媒体端点也限流**(v2.3 / v2.6 修正):`/v1/images`、`/v1/videos` 按 `providers..rate_limit_rps` 的**供应商桶**限流,与 chat 共用同一个 `prov:` 桶(v2.6 起媒体不再另起 `media:prov:` 独立桶 —— 那样实际放行量会翻倍、与文档不符)。高成本资源不再裸奔。 - **协议线闸门**(第二十七轮):`POST /v1/messages`、`/v1/responses` 只放行声明了对应线的模型,否则 400 并列出该模型支持的线;网关不做跨格式翻译。 - **熔断按次数窗口**(v2.3):`circuit.window` 现在真正按"最近 N 次调用"滑动(之前写死 60 秒、配置无效)。判定 = 最近 window 次里失败 ≥ failure_threshold。 - **失败也算耗时**:`/metrics` 的 P50/P95 包含失败请求的等待时间。 - **in_flight 精确统计**(v2.4):按响应**实际类型**(`StreamingResponse`)判断流式,非流式/413/502 在中间件减计数,SSE 流式在生成器收尾减计数。修复了"3MB 的流式 POST 被 413 后 in_flight 永久 +1"的泄漏。 - **适配器 client 并发安全**(v2.4):`get_client()` 加 `asyncio.Lock`,并发下只建一个 client(之前竞态建多个泄漏 fd);`close()` 幂等可重入(之前并发 double-close 抛 `Event loop is closed`)。 - **图像 size 缺省 1K**(v2.4):`/v1/images/generations` 不传 size 时默认最低档 `1K`,避免 Agnes 因缺 size 返回 400;`n=1` 时省略该字段(Agnes 一次一张)。 - **热重载真正生效**:改 `circuit` / `observability` / `metrics` / `auth` / `pricing` / 模型与协议线即时重建运行时对象;日志级别/JSON 格式热改也真能生效;`uptime_seconds` 因热重载不会清零。 - **优雅关闭**:`server.graceful_shutdown` 传给 uvicorn `timeout_graceful_shutdown`,收到停止信号时先排空在途请求再退出。**(v2.8 重要修复)**:lifespan 里曾用 `loop.add_signal_handler` 注册自己的 SIGTERM/SIGINT 处理器,把 **uvicorn 自己的处理器覆盖掉了**,导致 `SIGTERM`/`SIGINT` 完全无法停服(实测发信号后 10s+ 仍存活,只能 `kill -9`)。现已移除该注册,交给 uvicorn 处理;实测 SIGTERM 后 0.5s 内完成 `Shutting down → 应用收尾 → Finished`。 - **OpenAI 全兼容**(v2.2):响应带 `created` / `system_fingerprint`,流式末尾带 `usage` 块,错误为 `{"error":{message,type,code}}`,`/v1/models` 标准端点——OpenAI 官方 SDK 零适配直连。 ### 调用示例 ```bash # 授权:所有调用带 Bearer(Key 在「API Key」页自助铸造;admin 密码在 data/users.json) AUTH="Authorization: Bearer <你的 key>" # 文本(chat/completions 线;第二十七轮起没有路由,model 就是真实模型 id)+ 响应带 estimated_cost_cny curl -X POST http://localhost:8808/v1/chat/completions \ -H "$AUTH" -H "Content-Type: application/json" \ -d '{"model":"agnes-3.0-flash","messages":[{"role":"user","content":"你好"}],"max_tokens":256}' # 换模型 = 换 model id(第二十七轮起没有路由别名,网关不会替你挑模型) curl -X POST http://localhost:8808/v1/chat/completions \ -H "$AUTH" -H "Content-Type: application/json" \ -d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"hi"}]}' # Anthropic messages 线(同方协议直传,鉴权头换成 x-api-key) curl -X POST http://localhost:8808/v1/messages \ -H "$AUTH" -H "Content-Type: application/json" \ -d '{"model":"deepseek-v4.1-flash","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}' # 并发多 prompt(batch) curl -X POST http://localhost:8808/v1/chat/completions/batch \ -H "$AUTH" -H "Content-Type: application/json" \ -d '{"model":"agnes-3.0-flash","max_concurrency":4, "items":[{"messages":[{"role":"user","content":"say 1"}],"label":"a"}, {"messages":[{"role":"user","content":"say 2"}],"label":"b"}]}' # 图像 curl -X POST http://localhost:8808/v1/images/generations \ -H "$AUTH" -H "Content-Type: application/json" \ -d '{"model":"agnes-image-2.5-flash","prompt":"A red cube on white background","size":"1K","ratio":"1:1"}' # 视频(创建 + 轮询) curl -X POST http://localhost:8808/v1/videos \ -H "$AUTH" -H "Content-Type: application/json" \ -d '{"model":"agnes-video-2.5-flash","prompt":"A cat walking","seconds":"4","mode":"text","size":"720P","aspect_ratio":"16:9"}' # → 返回 video_id,然后: curl "http://localhost:8808/v1/videos/?model=agnes-video-2.5-flash&wait=true&wait_timeout=180" ``` 响应带 `provider` / `provider_name` / `served_model` / `estimated_cost_cny` / `x_request_id` 字段。 ## 前端 Web 控制台 - 前端由网关托管:`frontend/dist` 由网关挂在 `/web`(同源、公开无密钥),浏览入口 `https://127.0.0.1:8808/web/`(哈希路由,默认 `/web/#/dashboard`,未登录跳 `/web/#/login`)。 - 登录:POST `/auth/login` 用原始 key 换会话(`sess-` 前缀、TTL 滑动过期 86400s), 前端不持原始 key;登出 `/auth/logout`。 - 根路径 `/`:浏览器(`Accept: text/html`)访问自动 307 跳 `/web/`;API 调用(Accept 无 text/html)仍返回 JSON 端点导航。 - CSP(网关 security_headers):`default-src 'self'; script-src 'self'` —— 放行同源前端 脚本、仍禁外部 CDN 脚本与框架嵌入。若引入外部字体/脚本,需对应放宽 `font-src`/`script-src`。 - 里程碑:**M1** 登录 + 网关托管 + 去掉批量页(构建栈 Vue 3 + Vite + TS + Element Plus + ECharts + Pinia + Vue Router + marked)。JS 主包约 1.2MB,分包/按需引入留给 M5。 - 里程碑:**M2** 对话 Playground(`/web/#/chat`):流式/非流式对话(fetch 直连 `/v1/chat/completions` 解析 SSE)、模型选择(第二十七轮起是模型 + 协议线,不再有路由别名)、参数面板 (temperature / top_p / max_tokens / 流式开关 / 系统提示词)、Markdown+代码高亮渲染 (marked + highlight.js + DOMPurify 消毒)、推理折叠(`reasoning_content` 单独折叠)、 服务信息徽标(meta 帧的 served/provider;`fallback_used` 随路由功能删除)、token/成本展示(流式 usage 帧现也带 `estimated_cost_cny`)、会话历史 sessionStorage 持久、Enter 发送/Shift+Enter 换行。 - 里程碑:**M3** 图像页面(`/web/#/images`)+ 视频页面(`/web/#/videos`): 图像生成网格(`/v1/images/generations`,url/base64 均可显示、el-image 大图预览、耗时/供应商标注、 尺寸/张数可选)、视频(异步提交 `/v1/videos` 立即返回 + 前端每 5s 后台轮询 `GET /v1/videos/{id}`, 任务卡片展示状态/耗时/原始返回、完成后内嵌播放器播放真实 mp4;也可选同步 `wait=true` 直出)。 图像/视频的 `src` 走外部 CDN,故 CSP 放宽 `img-src`/`media-src` 允许 `https:`。 - **M3 补充(第十三轮)素材上传**:对话/图像/视频三页都能**直接上传素材**(对话附图、图像参考图、 视频首帧/尾帧/参考图/参考音频)。图片在浏览器内压缩成 data URI(`src/lib/upload.ts`,分级档位 + 逐级降档 + 缩略图),提交前做整包体积预算检查;视频「张数」改为逐张串行(上游 `n` 必须为 1)。 - 里程碑:**M4** 仪表盘图表打磨 + 指标页 + 日志页(引入 ECharts,`src/components/EChart.vue` 封装 + `src/lib/echarts.ts` tree-shake 按需注册): 仪表盘新增供应商份额饼图 + 模型延迟 P50/P95 柱图;指标页(`/web/#/metrics`)含指标卡 (已运行/在途/双 token/调用比)+ 各模型 ok/fail 堆叠柱图 + 供应商份额 + 按供应商成功/失败 堆叠 + 延迟 P50/P95 + 熔断器状态表(自动刷新 8s);日志页(`/web/#/logs`)展示最近 200 条 `/logs` 访问日志(方法/路径/供应商/实际模型/OK-FAIL/SSE/调用方/rid/错误),支持方法、结果、 关键字筛选与自动刷新 5s。EChart 共享分包约 594kB。 - 里程碑:**M5** 设置页(`/web/#/settings`)+ 分包优化: - 设置页:连接信息(网关地址/版本/用户/会话长度)、供应商状态表、账号(退出登录)、 对话默认参数(model/temperature/top_p/max_tokens/stream/system,存 localStorage, Chat 新会话用作默认值)、主题切换(浅色/深色,`` + Element Plus dark css-vars + 本项目配色 CSS 变量,localStorage 持久化、mount 前应用避免闪烁)、关于。 - 分包:主入口由约 1.2MB 降到 ~6.7kB;`vite.manualChunks` 拆 `vendor-vue` / `vendor-element` / `vendor-echarts` / `vendor-markdown` 四个缓存友好 chunk; highlight.js 由全量改为 core + 15 种常用语言按需注册(Chat chunk 1MB → ~77kB)。 - 里程碑:**M6 前端重设计 v2(2026-09-13)**:一套结构 + 三套主题 token (`html[data-theme="A|B|C"]`:**A 深空蓝**(深色)/ **B 素白蓝紫**(默认)/ **C 暖砂墨绿**), 切换入口=顶栏调色盘按钮 + 手机抽屉主题卡 + 设置页「外观与语言」,另有「跟随系统深色模式」 开关(系统深色自动用 A;`html.dark` 只给 Element Plus 弹层兜底)。 - 新增 `src/lib/theme.ts`(`initTheme()` / `getThemeId()` / `useTheme()`,mount 前上色避免闪屏)、 `src/lib/nav.ts`、`src/components/Icon.vue`(内联线性图标,替掉 emoji)、 `src/layouts/{SideNav,TabBar,MainLayout}.vue`;`style.css` 重写为三套 token + Element Plus 变量桥接;图表配色改由 `chartTheme()` 按主题取(ECharts 不认 CSS 变量)。页面改造规范见 `frontend/REDESIGN.md`。 - 手机端导航改「左上汉堡抽屉 + 底部 5 Tab(仪表盘 / 对话 / 图像 / 视频 / 更多)」; 图像/视频下载按钮统一为卡片下方的普通按钮(去掉缩略图上的绝对定位浮层,修手机端变形)。 - `lib/echarts.ts` 补注册 `GraphicComponent`:少注册它时 ECharts 会**静默丢掉** empty 图表的 「暂无」文案,空数据显示成一块空白画布(按需引入的坑)。 - i18n 收口:主题名/说明(`theme.nameA|B|C` / `theme.descA|B|C`,`THEME_META` 只留色值 + key)、 对话参数占位符、token 合计、已上传图片占位、导出文件的「推理」标签、密钥页示例代码里的 注释与示例文案,全部走 `t()`;中英 key 对称(488/488)、插值占位符一致、无未定义 key。 - 用户管理页展开账号后的「图像资产 / 视频资产」补**下载**按钮(管理员代下载该账号产出的图/视频): 与图像页/视频页同一条路(`lib/download.ts` → 同源 `/v1/media/download` 代拉 + `Authorization`), 按钮样式同为卡片下方的普通 `el-button--small`(全宽,手机端不挤变形)。 - 去掉「配置在 data/gateway.yaml,密钥在 .env;改完重启生效」提示(仪表盘底部 `gwLine` 与设置页 网关信息卡的 `gwReadonly` 一处不留,相关 i18n key 一并删除,避免死文案)。 - 登录页去掉副标题「统一接入三家上游大模型,对外只暴露一个 OpenAI 兼容入口。」(`login.lead`, 中英 key 同步删除):左栏改为「品牌 → 标题 → 四条特性」,原留给副标题的间距由 `h1` 下边距 (26px)撑开,桌面三主题/手机/英文复核留白正常、无溢出。 - **手机端登录页回归修复**(去掉副标题带出来的问题):手机端色块原来是「内容高度 + padding」, 副标题一去掉就变矮,而 `.pane-wrap` 的 `-46px` 上浮(沿用设计稿的卡片压接缝效果)是固定值, 于是开始吃卡片自己的内容 —— 「登录」标题整行被色块盖住、下面一行被接缝横切。修法三条: ① 手机端色块改给死留白高度(`min-height: 232px` + `padding-bottom: 72px`),让接缝只落在空白区; ② 卡片补 `position: relative; z-index: 1`(`.login-art` 是 `position: relative`,会盖住未定位的卡片); ③ 卡片 `flex: 1` 撑满剩余高度,消掉页面底部那一大片死白。 390×844 / 360×640 / 414×896 × 中英 × 三主题复核:标题与说明行均在卡片之上、无横竖溢出、控制台无报错。 - 手机端登录页按老板要求**去掉卡片底部所有提示**:四条特性(手机端不出)与 「密码只用于换取短时会话」胶囊都不显示,**中英切换挪到色块右上角**(`.lang-top`,半透明白胶囊 + `--primary-ink`)。窄屏 390/360 × 三主题复核:切换器位于 `right: 18px; top: 22px`、 点开可切中英(切完按钮文案变 `EN`/`Sign in`)、无溢出无报错。 - **桌面端登录页第二次调整**(老板后续要求,手机端验收通过后):① 顶部加通栏背景图; ② 登录卡整体往下挪;③ 卡片底部那行提示(`密码只用于换取短时会话` + 切换器)桌面端也**整行去掉**, 中英切换统一挪到页面右上角(`.lang-top` 从 `.login-art` 里提出来、挂到 `.login-wrap` 下, 桌面=深色毛玻璃胶囊 + 白字,窄屏=半透明白胶囊 + `--primary-ink`,同一个组件两套配色)。 背景图是一张**自绘 SVG**(`src/assets/login-banner.svg`,约 2.8KB,含注释;Vite 构建时内联成 data URI, 不引外链、不动 CSP,`img-src 'self' data:` 已覆盖):图形层只画白色低透明度形状 (点阵 + 同心圆弧 + 「三家上游汇到一个网关」的路由母题),底色用主题 token 铺渐变 (`--primary` → `--bg-2` 垂直渐变),所以 A/B/C 三套主题自动对色;另叠了左上柔光与整体压深两层, 压深的目的是让卡片的主色面板(`--primary`)在图上有边界 —— 不加这层,A 主题这种亮主色会和图糊成一块。 尺寸取 `clamp(270px, 40vh, 380px)`(矮屏图要矮一点,否则渐变的过渡段正好落在卡片上沿)。 登录区下移靠 `.login-wrap` 上下内边距不对称(`156px / 44px`,等效下移约 56px),不是写死 margin。 - **顺带修掉一个绘制顺序 bug**(几何位置对、探针量不出来,肉眼看出来的): `.login-bg` 是绝对定位元素,会画在**未定位**的 `.login-frame` 之上,矮屏(720p)下它把卡片上沿、 「登录」标题和两个输入框盖住;给 `.login-frame` 补 `position: relative; z-index: 1` 后正常 (与手机端当年修 `.login-art` 盖住卡片是同一类问题)。切换器 `.lang-top` 的 `z-index: 3` 保持在其上,`pointer-events: none` 只加在背景图上。 - 桌面端复核(本地临时实例真机走查 + 尺寸探针):1024×768 / 1280×700 / 1280×720 / 1440×900 / 1440×950 / 1920×1080 全部 `noOverflow=true`、卡片均在图下方(y=218/228/318/343/408)、 三主题(含 A 深色)边界清晰、无控制台报错;真实页面真机交互:输入框可聚焦可输入、 右上角切换器点开可切中英(`Sign in` / `EN`)、`.tail` 与 `footShort` 文案确认消失。 窄屏 390×844 / 360×640 复核为**未变**(背景图 `display: none`、色块 232px、卡片 y=186、 特性与底部提示不显示);i18n 486/486 对称(`login.footShort` 中英一并删除)、`typecheck` 0 error。 线上为纯静态资源切换,后端零改动、未重启,`Login-Ddk7Znt9.css` 与本地构建 md5 一致。 - **登录页第三次调整**(老板要求:提示内容全去 + 换科技抽象背景图 + 手机端上面也用这张图 + 登录区再往下挪): ① **提示文案清零**:卡片里的提示行(`login.subtitle`)与品牌区四条特性(`login.feat1-4`)连同 早已无人引用的 `login.connectedTip` / `login.foot` 一起删掉(中英 key 同步删),登录页现在只剩 「品牌标题 + 登录标题 + 用户名/密码 + 按钮」(`.hint` 样式与 `.feats` 样式一并清理, `h2` 下边距 6 → 20px 补上原来那行提示占的间距);i18n 从 486/486 降到 **479/479**(仍完全对称)。 ② **背景图重画成科技抽象**(同一路径 `src/assets/login-banner.svg`):方格网 + 交错点阵 + 星座网络 (节点/连线/发光节点)+ 中心「核心」母题(同心环 + 六边形 + 六向辐射)+ 两道斜向光带 + 右上角轨道环 + 左下角弧线与十字标记;配色口径不变(只画白色形状,底色仍走主题 token 渐变), 另加两团**取主题图表色**(`--chart-a` / `--chart-b`)的侧翼光晕,三主题各自换色更明显。 构图按两种裁切取交集排布(桌面端中间被卡片盖住、窄屏 cover 后只剩中间一列), 主视觉统一落在图里 y 40~300 的中间带。底色渐变的保持段 44% → **58%**,让白色形状在卡片上沿附近 仍有对比度。 ③ **窄屏顶部色块改用同一张图**:把整套图层收进 `.login-wrap` 上的变量 `--hero-img`, 桌面通栏 `.login-bg` 与窄屏 `.login-art` 共用(不会再出现两边不一致);窄屏隐藏 `.login-art .orb`(原来那两个装饰圆与图上的轨道环打架)。 ④ **登录区继续下移**:桌面 `.login-wrap` 内边距 `156/44` → **`190/44`**(等效下移约 73px, 1280×720 下卡片上沿 y=257,1440×900 y=347,1024×768 y=281);窄屏色块 `min-height` 232 → **268px**(卡片随之再下移 36px,y=222)。 ⑤ **顺手补一个构建自检**:`frontend/scripts/check-svg.mjs`(`npm run check:svg`,已挂进 `build` 前置) 逐个校验 `src/assets/*.svg`。起因是这轮真踩了坑 —— SVG 注释里写了 CSS 变量名(连续两个连字符), XML 不允许,整个文件解析失败、图层**静默不画**:页面不报错、探针也量不出,只表现为「改完没变化」。 guard 会拦住这类注释与标签不配平,构建期直接失败。 - 本轮复核:本地临时静态服务 + 真机走查(1280×720 / 1024×768 / 1440×900 / 1920×1080 × 三主题 × 中英,以及 390×844 / 360×640 × 三主题):全部 `ok ok`(无横竖溢出)、卡片均落在图上且边界清晰、 `hint`/`feats` 节点确认为 0、窄屏 `.login-art` 已带 `url(login-banner-*.svg)` 且 `.orb` 为 `display:none`、 真实交互(输入框聚焦输入、右上角切换器切到 English 后文案变 `Sign in`)通过; `typecheck` 0 error、`npm run build` 成功(新产物 `index-DG7g6NaW.js` / `Login--E4bzU7N.css` / `login-banner-7rrSIoiP.svg`)。线上 `https://127.0.0.1:8808/web/#/login` 已服务新产物 (公网取 `login-banner-7rrSIoiP.svg` 200 / 7139B),后端零改动、未重启。 另修一处小 a11y 问题:`i18n.ts` 只在 `setLocale()` 里写 ``,初始化路径漏了, 导致 localStorage 存 `en` 的用户 `lang` 一直停在 `zh-CN`;改为模块初始化时也写一次。 - **登录页第四次调整**(老板:① 去掉品牌区底部版本行 ② 整页重做): ① 品牌区底部那行「v2.4.0 + 网关地址」(`.art-foot`)删掉:模板、桌面样式与窄屏那条 `.login-art .art-foot { display:none }` 一并清理;随之失效的 `version` / `base` 状态、 `onMounted` 里那次「只为取版本号」的 `/healthz` 请求与 `api` import 一起删除 —— 登录页现在 不再额外发任何请求。i18n 无改动(那行是直读 `/healthz` 与 `location.origin`,没走 `t()`), 无 key 残留。 ② 整页重做为**三套设计稿**,落在 `design/login-v3/`(该目录 2026-09-13 按老板指示清理归档,未 `rm`,恢复见 `/root/.trash/<归档>/MANIFEST.md`):`d1.html` 极简白卡(浅底单列居中卡)、 `d2.html` 深色玻璃卡(深色科技底 + 毛玻璃)、`d3.html` 通栏一体(左侧主题色品牌面 + 右侧白色 表单面,整屏无卡片框);`h.html` 是「iframe 定尺预览机」(每条 `文件:宽x高x缩放`,按指定视口 真实渲染再 scale 进浏览器窗口),出稿对照图都用它。三套各含桌面端与手机端形态、token 口径与 产品 `style.css` 的 B 主题一致(A/C 主题落地时自动跟随),**等老板选定方向后再改产品代码** (`views/Login.vue`)。 - **登录页方案一落地**(老板从三套设计稿里选定 `d1`「极简白卡」): `views/Login.vue` 整页重写。结构从「顶部通栏背景图 + 左品牌面 + 右表单面」的两栏卡片改成 **浅底 + 单列居中白卡**:logo 方块 + 品牌标题 + 用户名/密码 + 登录按钮,卡片 440×444 居中, 页脚 / 版本行 / 提示行一律没有。整页装饰改为纯 CSS 四层(全部 `pointer-events:none`、无外链 资源):左上与右下双柔光 `radial-gradient`、卡片背后一团主色光雾(`blur(14px)`)、左上角渐显 点阵肌理(`mask-image` 化开)、右下三个同心细线环。原先内联的 `login-banner.svg`(科技抽象 自绘)自此无任何代码引用(文件保留备查;Vite 未引用就不入产物,`dist/assets` 里已无它)。 配色一律走 token + `color-mix(in srgb, var(--x) N%, transparent)`,不再写死 `rgba(79,99,245,…)` 这类只对单一主题成立的常量,所以 A 深空蓝 / C 暖砂墨绿下自动换色: logo 方块是「主色自身上下渐变」、按钮阴影是主色半透明、柔光与同心环也跟着主色走。 手机端(≤600px)卡片化整为零:去掉底 / 边框 / 阴影,表单直接在柔光底上居中,同心环缩一档。 踩坑:输入框聚焦本想要「1px 主色 + 3.5px 柔光」双环,被全局 `style.css` 里 `.el-input__wrapper.is-focus { box-shadow: … !important }` 整条盖掉(只剩 1px 细边), 已在登录页作用域内用 `!important` 覆盖并写明原因(作用范围仍只限本页)。 验证:`typecheck` 0 error、`build` 成功(`Login-CazImMjd.css` / `Login-tSNCQlh5.js` / `index-BWFYxQdn.js`);用同源探针 `probe.html`(原 `design/login-v3/probe.html`,已随设计稿目录归档)逐格量过 **3 主题 × 7 分辨率** (1280×720 / 1024×768 / 1440×900 / 1920×1080 / 390×844 / 360×640 / 414×896)共 21 组: 全部 `ovX=ovY=0` 无溢出、卡片 440×444 居中、三主题的卡片 / 按钮 / logo / 聚焦环颜色各自正确、 旧结构节点 0;英文单独验过(`API Gateway Console` / `Username` / `Password` / `Sign in`、 ``、卡片 434 高同样无溢出);真机交互验过语言切换(右上角胶囊 → English → 文案与 `` 同步)与空提交报错(卡片内红色提示、卡片自动增高不溢出)。 线上 `https://127.0.0.1:8808/web/#/login` 已服务新产物(`Login-CazImMjd.css` 200 / 4426B, 旧 `Login-BMLIXfzt.css` 404),后端零改动、未重启。 > 探针为什么挂在 vite dev 上:CSP 里有 `frame-ancestors 'none'`(安全项,不为此放宽), > `/web` 下的页面不能被 iframe 嵌(`__probe.html` 放 `/web` 里量不到东西),所以改用 > **无 CSP 的 vite dev(`--port 5199`)**同源托管探针:同源才能读 iframe 的 DOM、才能直接写 > `localStorage` 切主题/语言,再逐格量溢出与计算样式。探针跑完即从 `frontend/public/` 删除 > (否则会被 build 拷进 `dist`),只留 `design/login-v3/probe.html` 这一份;该探针与三套设计稿 > 已于 2026-09-13 一并归档到 `/root/.trash/<归档>/`(未 `rm`,可恢复)。 - 修 data URI 下载的 CSP 坑:产物是 `data:` 时原实现用 `fetch(dataURI)` 取字节,而 CSP `connect-src 'self'` 会把它拦掉(上游以 base64 直回图片时「下载」必失败,本地 vite preview 无 CSP 时看不出来)。改为本地 base64 解码 `dataUriToBlob()`,不触网、也不动 CSP 白名单。 - 复核(本地临时实例真机走查,未动线上数据):10 个路由 × 桌面 1440 / 手机 390 / 手机英文, 页面级横向溢出 0、控制台无报错(仅 seed 的假视频地址报 `ERR_NAME_NOT_RESOLVED`); 移动端表格横滑时表头与表体同步(Element Plus 内部 `overflow: hidden` + JS 同步,非缺陷)。 已知残留:英文界面下上游/网关返回的**服务端消息**仍是中文(如 `size 仅支持 720P`), 以及历史里的业务数据(提示词等)不翻译 —— 这两类按老板决定**不做双语** (要双语得后端按 `Accept-Language` 出英文消息,收益不抵成本)。 - **日志响应内容 + 推理回退**:`/logs` 每条新增 `response`(流式累积 delta.content、 非流式取 message.content,截断 2KB);正文为空时回落到 `reasoning_content`(标注 `[推理] `,避免小预算下看起来像“空响应”);日志页去掉常驻的「调用方/rid」列 (收进展开行),合并路径+SSE 标、模型/供应商一列,新增「响应内容」列,搜索覆盖 请求/响应/错误。流式全失败此前会因累加器未初始化而 NameError(SSE 变 500),已修复 并在全链 `_get_adapter` 失败路径补回归测试。 - **图表文字挤压修复**:ECharts 6 把 legend 默认位置从 top 改为 bottom,导致图例压在 x 轴标签上。新增 `src/lib/charts.ts` 统一 `legend(top:0)` / 类目轴截断+倾斜+hideOverlap / `grid.containLabel` 留白,仪表盘与指标页 4 类图全部接入。 - **模型与供应商页**(`/web/#/models`):指标卡(模型/文本/图像/视频/供应商)+ 模型清单(ID/类型/供应商/视觉/延迟,一键测速按模型自己的协议线探测),数据来自 `/v1/models` + `/health`。(第二十七轮:路由别名表已随功能删除) (降级链逐 tag 展示、供应商数)+ 模型清单(ID/类型/供应商/Key 已配),数据来自 `/v1/models` + `/health`。 - **多语言(M5+)**:Vue I18n + `src/locales/zh|en.ts`,全站中英可切换;语言按钮在头部与登录页、设置页 (`settings.language`),存 `localStorage.gw_locale`、默认中文;Element Plus 语言包经 `ElConfigProvider` 跟随(`App.vue` 引入 `element-plus/dist/locale/zh-cn|en.mjs`)。 所有视图(导航/登录/仪表盘/指标/日志/对话/图像/视频/模型/设置)主要文案已接入 `t()`。 - **白屏根因修复(CSP)**:接入 vue-i18n 后网关 CSP 从 `script-src 'self'` 拦掉其运行时 message 编译(`new Function`),整个前端白屏(本地仅无 CSP 的 vite preview 正常,极难察觉)。 已把 `script-src` 补为 `'self' 'unsafe-eval'`,其余安全策略(禁外部脚本/连接/框架/base/form)不变。 - **`/web` 缓存策略(M5+)**:Vite 滚动产出时若 index.html 被缓存,会引用已被新一轮 build 删除的旧 hash asset 而 404 白屏。网关对 `/web` 的 index.html 响应 `Cache-Control: no-cache`(每次重新校验), asset(带 hash)回 `public, max-age=31536000, immutable`。 里程碑:此前 `frontend/dist` 每次 `npm run build` 后即被网关挂载(`app.mount("/web", StaticFiles(html=True))`)。 - **杂项**:版本号收敛为单一 `VERSION = "2.4.0"` 常量(FastAPI / `/` / `/auth/login` / `/health` 四处对齐,修复前端「网关版本 v-」);`/health` 新增 `version` 字段;Dashboard 熔断列大小写归一化(`/health` 返回小写,此前一直误标红)+ 新增「媒体熔断」列; Dashboard 轮询定时器改为 onMounted/onUnmounted 配对(原来裸 setInterval 泄漏)。 - **日志显示请求内容**:后端 `/logs` 每条现在带 `body`(请求体摘要,中间件按 rid 暂存、 截断到约 2KB),前端日志页新增「请求内容」列(两行截断、悬停看全文、可搜索);GET 类 请求及校验/鉴权拒绝的请求无 body。另前端新增会话过期自动引导:任一接口 401 时清空本地 token 并回登录页(此前会话失效会 401/429 循环、静默空数据)。 > **第九轮(2026-09-13)历史落盘 + 视频卡片修复** > - 图像/视频/对话历史改为服务端持久化(`data/history.json`,按账号隔离、按 id upsert), > 前端本地只留缓存,**写失败改为明确提示**(以前 `catch {}` 静默丢数据)。 > - **真 Bug**:视频页卡片 `v-for="t in tasks"` 的别名 `t` 把 i18n 的 `t()` 遮蔽了 —— > 卡内 `t('videos.status')` 变成"对任务对象调用函数",卡片整块渲染不出来, > 表现就是"任务在列表里计数、却看不到任何视频"。循环变量改名 `tk` 后实测恢复 > (1 张卡片、`