From d143d8da22c26ad0ba2f7531c9eb96ed552a3c57 Mon Sep 17 00:00:00 2001 From: api-gateway Date: Tue, 15 Sep 2026 17:05:05 +0800 Subject: [PATCH] =?UTF-8?q?init:=20api-gateway=20v2.4.0=EF=BC=88Agnes/b.ai?= =?UTF-8?q?/=E7=81=AB=E5=B1=B1=E6=96=B9=E8=88=9F=20=E4=B8=89=E5=AE=B6?= =?UTF-8?q?=E4=BE=9B=E5=BA=94=E5=95=86=E7=BD=91=E5=85=B3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 13 + .gitignore | 36 + CHANGELOG.md | 195 + Makefile | 34 + README.md | 1178 ++++++ app/__init__.py | 1 + app/adapters/__init__.py | 31 + app/adapters/base.py | 191 + app/adapters/openai_compat.py | 228 ++ app/circuit.py | 205 + app/config.py | 535 +++ app/feedback.py | 427 ++ app/history.py | 204 + app/main.py | 3175 +++++++++++++++ app/metrics.py | 333 ++ app/models.py | 208 + app/routing.py | 46 + app/sessions.py | 99 + app/settings.py | 485 +++ app/users.py | 362 ++ data/gateway.yaml | 147 + data/gateway.yaml.20260915-104301.bak | 152 + data/gateway.yaml.20260915-104324.bak | 148 + data/gateway.yaml.bak | 148 + docs/frontend-design.md | 169 + docs/speedtest-current-row-spinner.png | Bin 0 -> 121741 bytes docs/speedtest-per-row-retry.png | Bin 0 -> 131838 bytes docs/speedtest-per-row-test-button.png | Bin 0 -> 117620 bytes docs/speedtest-sequential-progress.png | Bin 0 -> 123054 bytes docs/st-err-speedtest-error-display.png | Bin 0 -> 129247 bytes frontend/.visual-check/vite.config.mjs | 10 + frontend/REDESIGN.md | 93 + frontend/index.html | 12 + frontend/package-lock.json | 1787 +++++++++ frontend/package.json | 33 + frontend/scripts/check-i18n.mjs | 114 + frontend/scripts/check-svg.mjs | 47 + frontend/src/App.vue | 18 + frontend/src/api.ts | 95 + frontend/src/assets/login-banner.svg | 126 + frontend/src/components/EChart.vue | 40 + frontend/src/components/FeedbackImages.vue | 76 + frontend/src/components/FeedbackTimeline.vue | 97 + frontend/src/components/Icon.vue | 76 + frontend/src/env.d.ts | 12 + frontend/src/i18n.ts | 34 + frontend/src/layouts/MainLayout.vue | 239 ++ frontend/src/layouts/SideNav.vue | 78 + frontend/src/layouts/TabBar.vue | 44 + frontend/src/lib/charts.ts | 139 + frontend/src/lib/chat.ts | 134 + frontend/src/lib/download.ts | 143 + frontend/src/lib/echarts.ts | 28 + frontend/src/lib/features.ts | 10 + frontend/src/lib/feedback.ts | 123 + frontend/src/lib/history.ts | 56 + frontend/src/lib/markdown.ts | 44 + frontend/src/lib/media.ts | 44 + frontend/src/lib/nav.ts | 60 + frontend/src/lib/settings.ts | 26 + frontend/src/lib/theme.ts | 126 + frontend/src/lib/ui.ts | 32 + frontend/src/lib/upload.ts | 221 ++ frontend/src/locales/en.ts | 781 ++++ frontend/src/locales/zh.ts | 787 ++++ frontend/src/main.ts | 23 + frontend/src/router.ts | 47 + frontend/src/store/session.ts | 36 + frontend/src/style.css | 682 ++++ frontend/src/views/ApiKeys.vue | 287 ++ frontend/src/views/Chat.vue | 822 ++++ frontend/src/views/Dashboard.vue | 293 ++ frontend/src/views/Feedback.vue | 251 ++ frontend/src/views/FeedbackInbox.vue | 264 ++ frontend/src/views/GatewayConfig.vue | 274 ++ frontend/src/views/Images.vue | 402 ++ frontend/src/views/Login.vue | 211 + frontend/src/views/Logs.vue | 353 ++ frontend/src/views/Metrics.vue | 262 ++ frontend/src/views/Models.vue | 333 ++ frontend/src/views/Placeholder.vue | 20 + frontend/src/views/Settings.vue | 324 ++ frontend/src/views/Users.vue | 446 +++ frontend/src/views/Videos.vue | 720 ++++ frontend/tsconfig.json | 17 + frontend/vite.config.ts | 43 + live_check.py | 127 + requirements.txt | 6 + run.py | 31 + smoke_test.py | 95 + tests/test_gateway.py | 3749 ++++++++++++++++++ 91 files changed, 24653 insertions(+) create mode 100644 .env.example create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 Makefile create mode 100644 README.md create mode 100644 app/__init__.py create mode 100644 app/adapters/__init__.py create mode 100644 app/adapters/base.py create mode 100644 app/adapters/openai_compat.py create mode 100644 app/circuit.py create mode 100644 app/config.py create mode 100644 app/feedback.py create mode 100644 app/history.py create mode 100644 app/main.py create mode 100644 app/metrics.py create mode 100644 app/models.py create mode 100644 app/routing.py create mode 100644 app/sessions.py create mode 100644 app/settings.py create mode 100644 app/users.py create mode 100644 data/gateway.yaml create mode 100644 data/gateway.yaml.20260915-104301.bak create mode 100644 data/gateway.yaml.20260915-104324.bak create mode 100644 data/gateway.yaml.bak create mode 100644 docs/frontend-design.md create mode 100644 docs/speedtest-current-row-spinner.png create mode 100644 docs/speedtest-per-row-retry.png create mode 100644 docs/speedtest-per-row-test-button.png create mode 100644 docs/speedtest-sequential-progress.png create mode 100644 docs/st-err-speedtest-error-display.png create mode 100644 frontend/.visual-check/vite.config.mjs create mode 100644 frontend/REDESIGN.md create mode 100644 frontend/index.html create mode 100644 frontend/package-lock.json create mode 100644 frontend/package.json create mode 100644 frontend/scripts/check-i18n.mjs create mode 100644 frontend/scripts/check-svg.mjs create mode 100644 frontend/src/App.vue create mode 100644 frontend/src/api.ts create mode 100644 frontend/src/assets/login-banner.svg create mode 100644 frontend/src/components/EChart.vue create mode 100644 frontend/src/components/FeedbackImages.vue create mode 100644 frontend/src/components/FeedbackTimeline.vue create mode 100644 frontend/src/components/Icon.vue create mode 100644 frontend/src/env.d.ts create mode 100644 frontend/src/i18n.ts create mode 100644 frontend/src/layouts/MainLayout.vue create mode 100644 frontend/src/layouts/SideNav.vue create mode 100644 frontend/src/layouts/TabBar.vue create mode 100644 frontend/src/lib/charts.ts create mode 100644 frontend/src/lib/chat.ts create mode 100644 frontend/src/lib/download.ts create mode 100644 frontend/src/lib/echarts.ts create mode 100644 frontend/src/lib/features.ts create mode 100644 frontend/src/lib/feedback.ts create mode 100644 frontend/src/lib/history.ts create mode 100644 frontend/src/lib/markdown.ts create mode 100644 frontend/src/lib/media.ts create mode 100644 frontend/src/lib/nav.ts create mode 100644 frontend/src/lib/settings.ts create mode 100644 frontend/src/lib/theme.ts create mode 100644 frontend/src/lib/ui.ts create mode 100644 frontend/src/lib/upload.ts create mode 100644 frontend/src/locales/en.ts create mode 100644 frontend/src/locales/zh.ts create mode 100644 frontend/src/main.ts create mode 100644 frontend/src/router.ts create mode 100644 frontend/src/store/session.ts create mode 100644 frontend/src/style.css create mode 100644 frontend/src/views/ApiKeys.vue create mode 100644 frontend/src/views/Chat.vue create mode 100644 frontend/src/views/Dashboard.vue create mode 100644 frontend/src/views/Feedback.vue create mode 100644 frontend/src/views/FeedbackInbox.vue create mode 100644 frontend/src/views/GatewayConfig.vue create mode 100644 frontend/src/views/Images.vue create mode 100644 frontend/src/views/Login.vue create mode 100644 frontend/src/views/Logs.vue create mode 100644 frontend/src/views/Metrics.vue create mode 100644 frontend/src/views/Models.vue create mode 100644 frontend/src/views/Placeholder.vue create mode 100644 frontend/src/views/Settings.vue create mode 100644 frontend/src/views/Users.vue create mode 100644 frontend/src/views/Videos.vue create mode 100644 frontend/tsconfig.json create mode 100644 frontend/vite.config.ts create mode 100644 live_check.py create mode 100644 requirements.txt create mode 100644 run.py create mode 100644 smoke_test.py create mode 100644 tests/test_gateway.py diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..4f6c4a2 --- /dev/null +++ b/.env.example @@ -0,0 +1,13 @@ +# API Gateway 环境变量模板 +# 复制为 .env 并填入真实 token(本机使用即可;如需版本管理,建议自行把 .env 加进 .gitignore) +# 真实环境变量优先级高于 .env(load_dotenv override=False) + +AGNES_API_KEY= +B_AI_API_KEY= +VOLC_API_KEY= + +# 运行参数(可选,覆盖 yaml) +# GATEWAY_CONFIG=/path/to/gateway.yaml +# GATEWAY_HOST=127.0.0.1 +# GATEWAY_PORT=8808 +# GATEWAY_GRACEFUL_SHUTDOWN=30 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5c339ab --- /dev/null +++ b/.gitignore @@ -0,0 +1,36 @@ +# ── 缓存 / 构建产物 ── +__pycache__/ +*.pyc +*.pyo +.pytest_cache/ +.venv/ +venv/ +*.log + +# ── 本地敏感文件 ── +.env +.env.* +!.env.example +# 账号体系数据:密码哈希 + API Key 哈希,属凭证材料,不入库 +data/users.json +# 前端历史(提示词/回答正文属隐私) +data/history.json +# 意见反馈(正文 + 图片,属隐私) +data/feedback.json +data/feedback_media/ +# 单测运行时会往项目根写这几个临时数据文件(test_gateway.py 用),别入库 +.test_users.json +.test_history.json +.test_feedback.json +.test_feedback_media/ + +# 说明:data/gateway.yaml 不含明文 Key —— 三家供应商密钥统一在 .env(已被上面忽略), +# 由 yaml 各供应商的 token_env 引用。只要 .env 不提交,密钥就不会进版本库。 + +# ── 依赖与构建产物(不入库,均可重新生成:npm ci && npm run build)── +node_modules/ +frontend/node_modules/ +frontend/dist/ +dist/ +*.egg-info/ +.DS_Store diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..4efc410 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,195 @@ +# CHANGELOG + +按轮次记录 api-gateway 的修复与优化(README 侧重能力/配置说明,这里侧重每轮的改动、排查、验证与上线)。 + +--- + +## 2026-09-15 · 新增 OpenCode Zen(免费档)供应商 + +**一句话**:把 OpenCode Zen 作为第 4 个供应商接入,只收录文档定价页列出的**免费模型**。打通后发现免费档比较刁钻:既被 Cloudflare 拦默认 UA,又强制要求每个请求带独立会话头——两条都已在适配器层解决,实测全部 200。 + +### 背景 / 需求 +老板要求查看 [OpenCode Zen 文档](https://opencode.ai/docs/zh-cn/zen#pricing),接入该供应商,**模型只要文档里免费的模型**,并提供一把 API Key。 + +### 上游真相(重点!) +文档定价页的"免费模型"共有 6 个。**直接以"Bearer key + 标准请求"裸调全部失败**,逐一实测定位(带浏览器 UA 后才能看到模型层错误): + +| 免费模型 id | 裸调结果 | 根因 | 处理 | +|---|---|---|---| +| `big-pickle` | 401 `Model is disabled` | 隐身模型,未对本工作区/Key 开放 | ❌ 排除 | +| `mimo-v2.5-free` | 400 `MissingSessionID` | 免费档要求每个请求带会话 id | ✅ 收录 | +| `ling-3.0-flash-fin-free` | 400 `MissingSessionID` | 同上 | ✅ 收录 | +| `nemotron-3-ultra-free` | 400 `MissingSessionID` | 同上 | ✅ 收录 | +| `nemotron-3.5-lightning-free` | 400 `MissingSessionID` | 同上 | ✅ 收录 | +| `muse-spark-1.3-contributor-free` | 400 `MissingSessionID` | 且走 `/responses` 端点(本适配器是 `chat/completions` 调不了)+ contributor 档会用你的提示词/补全训练 Meta 模型 | ❌ 排除 | + +**根因一(Cloudflare)**:裸调用默认 `urllib` UA 报 `403 error code: 1010`(基于客户端签名的访问被禁)。改成浏览器 UA 后请求才抵达模型层。网关默认 `python-httpx` UA 大概率同样被拦 → 必须在请求头带浏览器 `User-Agent`。 + +**根因二(会话标识)**:通过 [DeepSeek Harness 生产集成讨论帖](https://github.com/deepseek-ai/deepseek-harness/discussions/5495) 确认——所有打到 `opencode.ai` 的请求都要带 **`x-opencode-session`** 请求头(会话 id,UUID 即可;同一次多轮保持稳定会走路由亲和性)。不带 → `400 MissingSessionID`。带上后 4 个免费模型全部可用。 + +**Key 与计费**:该 Key 有效(能通过鉴权、能识别到 workspace),但账号**未绑定支付方式** → 付费模型返回 `CreditsError: No payment method`。因此当前这套 Key 下能用的只有免费档(且经会话头 + 浏览器 UA 后确实能用)。 + +### 改动明细 +- **`app/adapters/openai_compat.py`**(后端代码改动,需重启生效) + - 新增常量 `OPENCODE_SESSION_SENTINEL = "@per-request-uuid@"`。 + - 新增 `_call_headers()`:若 `extra_headers` 里 `x-opencode-session` 为哨兵值,则**每次 `chat` / `chat_stream` 调用现生成一个新 UUID** 再发请求;否则原样返回静态头(其它供应商零行为变化)。 + - 目的:所有用户/会话共用一个固定 session 会互相踩 OpenCode 的限流与路由亲和,必须按请求/会话隔离。 + - `chat()` 与 `chat_stream()` 的请求头由 `self._headers` 改为 `self._call_headers()`。 +- **`data/gateway.yaml`** + - 新增 `opencode` 供应商:`name: OpenCode Zen`、`base_url: https://opencode.ai/zen/v1`、`token_env: OPENCODE_API_KEY`。 + - `extra_headers`:`User-Agent`(浏览器 UA,过 Cloudflare)+ `x-opencode-session: "@per-request-uuid@"`(哨兵)。 + - `media: {}`(仅文本,无图像/视频)。 + - `models`:4 个免费模型(`mimo-v2.5-free` / `ling-3.0-flash-fin-free` / `nemotron-3-ultra-free` / `nemotron-3.5-lightning-free`)。 + - `pricing.per_model`:新增这 4 个,`input: 0, output: 0`(免费)。 + - 顶部注释供应商清单补 `OpenCode Zen(免费档)`。 +- **`data/.env`**:新增 `OPENCODE_API_KEY=`,权限 0600(保留原行、仅追加)。key 明文不进 yaml、不入版本库。 +- **`tests/test_gateway.py`**:`test_load_config_providers` 断言更新为 4 家,并新增守卫断言(opencode.base_url / 浏览器 UA / 哨兵头 / 4 个模型集),防以后误改。 +- **`README.md`**:顶部供应商清单、供应商表格、`openai_compat.py` 架构注释、OpenCode 两条硬性要求说明。 + +### 验证(非编造,实录) +- 上游直打 `https://opencode.ai/zen/v1/chat/completions`(**浏览器 UA + 每请求新 UUID 会话头**): + - 4 个免费模型**非流式全部 200**,`nemotron-3.5-lightning-free` 出真实中文回复 + `usage.reasoning_tokens`(推理模型先吐推理再吐内容)。 + - **流式全部 200**:`content-type: text/event-stream`,`nemotron-3.5-lightning-free` 收了 123 个 chunk 并正常收到 `[DONE]`。 + - `big-pickle` 反复 401 `Model is disabled` → 确认本 Key 未开放,排除。 +- 适配器哨兵逻辑单测:哨兵值 → 每次新 UUID(36 位);普通静态值 → 原样保留。 +- 全量单测 `python tests/test_gateway.py`:**153 passed, 2 failed**。 + - 涉及的 provider 相关用例通过;余下 2 个失败为历史遗留、与本次无关: + - `test_load_config_routes`:断言 `wjd.models == 6`,但 GLM-5.3-Flash 移除后 `wjd` 链是 5 个(旧断言未同步)。 + - `test_feedback_withdraw_only_when_pending`:feedback 撤回逻辑,非本次改动范围。 + +### 部署 +- `supervisorctl restart api-gateway:api-gateway_00`。 +- 重启前验证文件已就位:yaml `safe_load` 通过、`providers = [agnes, b_ai, volc_engine, opencode]`、opencode 4 个模型。 +- 上线后校验:新 pid 61457、healthz `{"status":"ok"}`、`/v1/models` 200 且含 opencode 4 个免费模型、无凭证/错 key 仍 401、真实 chat 调用 `provider=opencode` 返回 200。 + +### 待办 / 已知 +- `big-pickle` 与付费模型都因账号条件(Model disabled / 未绑支付方式)不可用,等以后条件变化再按需补录。 +- 免费档是否偶尔有速率/额度上限:OpenCode 注明"目前免费提供,团队在收集反馈",可能随时变化;若某模型开始报错,在 Models 页一键测速即可发现。 +- 本次未把 OpenCode 加进 `wjd` 兜底路由,先在 **Models 页 + 直连模型 id** 可用;要进 `wjd` 需老板另行确认。 + +### 视觉支持实测(2026-09-15,真图判定) +发一张「青色背景 + 品红五角星」的答案唯一测试图,走 OpenAI 多模态 `image_url` 格式(带浏览器 UA + `x-opencode-session`)实测: +- `ling-3.0-flash-fin-free` → **❌ 无视觉**:上游 `400 ... [404] No endpoints found that support image input`。 +- `nemotron-3-ultra-free` → **❌ 无视觉**:同上。 +- `nemotron-3.5-lightning-free` → **❌ 无视觉**:同上。 +- `mimo-v2.5-free` → **⚠️ 未判定**:连纯文本都持续 `429 FreeUsageLimitError`(免费额度是小时/天级窗口,等 7 分钟未回血),够不到读图那步。强先验:MiMo-V2.5 家族在 b.ai 早前实测即 `Vision is disabled`,故基本可断定无视觉。 +- 结论:4 个 OpenCode 免费模型**均无视觉**(3 个实测坐实、1 个受限于限流未坐实但先验一致)。gateway.yaml 里这 4 个都只标 `type: text`、**未加 `vision:true`**,与实测一致,无需改动;Models 页也不会给它们显示 👁 图标。 + +--- + +## 2026-09-15 · 一键测速报错展示优化(Models 页) + +**问题**:Models 页「一键测速」某个模型失败时,错误内容被塞进硬编码的窄 `pill`(`.st-lat`)里,长错误(无空格 JSON / 上游错误串)不换行、到卡片边缘就被切掉 → 报错显示不全。 + +**改动**(`frontend/src/views/Models.vue`,纯前端,不重启后端): +- 模板:每个测速行 `st-row` 外包一层 `st-item`;当某模型测速失败时,在行下方新增一整行 `st-err`(`ban` 图标 + 完整错误文本)全宽展示。 +- 逻辑:新增 `latErr(id)` 返回完整错误串(用于 st-err 行);`latText(id)` 失败时只返回短的「失败」标记(长错误不再塞窄 pill)。 +- 样式:`.st-err` 用 `--err` 文字 + `--err-soft` 底、圆角块;`overflow-wrap: anywhere` + `word-break: break-word` 让长 JSON/无空格错误串自动换行不溢出;`.st-item + .st-item` 虚线分隔。 + +**验证**:`npm run check:svg && npm run check:i18n && vite build` 通过;`vue-tsc --noEmit` 无错;新产物 `index-C_e1f2ok.js` / `Models-C-QAxhv1.js` 线上 200、旧 hash 404。后端挂载 `frontend/dist`,build 即可见,pid 未动、会话不掉。 + +### 附带修复:后端空错误兜底 +真实实测中发现 nemotron-3-ultra-free / mimo-v2.5-free 偶尔 429 限流,部分时候上游只返回空 body 导致 `error = "{}"`(`str({})`),既丑又无信息。`app/main.py` 的 `_upstream_detail` 修复:当 `j` 无 `message/error/detail` 且 `str(j) in ("{}","","null","None")` 时返回空串,前端 `row.error` 兜底显示「调用失败」而不是 `{}`。重启后生效(`pid 121772`)。 + +### 截图留档 +- `docs/st-err-speedtest-error-display.png`:真实浏览器实拍,两个 OpenCode 免费模型同时报错,`st-err` 红块完整展示 429 限流错误信息(含上游文档链接)——验证"显示不全"已修复。 + +--- + +## 2026-09-15 · 一键测速改为「逐个测、测一个显示一个」 + +**需求**:一键测速原来是并发/一次性返回全部结果、最后一起显示;改成**串行逐个测,每测完一个立刻显示那一行,再测下一个**。 + +**改动** +- **`app/main.py` `/v1/models/speedtest`**:新增可选 `body.model`。传了就只测该模型、返回单条(不排序);乱传/非文本模型返回一条兜底错误行「模型不存在或非文本模型」。不传仍是一次性全测(保留兼容)。 +- **`frontend/src/views/Models.vue`**:`runSpeedtest()` 改为按列表顺序 `for` 循环,逐个 `POST {model:id}`,每测完一个 `latByModel.value = {...latByModel.value, [id]: row}` 响应式即时刷新该行;**单个模型异常不中断整轮**(catch 后标失败继续下一个)。新增 `latDone/latTotal`,按钮测速中显示「测速中 n/total」进度。`latText()` 改为:已测行显示 ms/失败、测速中未轮到的显示 `…`、空闲显示 `—`。 + - 注:`textModelRows` 本就按供应商分组顺序、不随延迟重排,所以逐个测时行不会跳动,无需额外锁序。 +- **i18n**:`models.testingProgress` 中英各加一条(`测速中 {n}/{total}` / `Testing {n}/{total}`),保持对称。 + +**为什么串行更好**:并发一次性测会把 OpenCode 免费档瞬间打满触发 429;串行逐个测天然错峰。 + +**验证**:后端单测 153 passed(2 个历史遗留不变);前端 build + `vue-tsc` 通过;新产物 `index-D81T1xmr.js` / `Models-DpOHvPHF.js` 线上 200、旧 hash 404;`supervisorctl restart` → pid 187860、healthz ok。接口实测 `{model:"hy3"}` 只返回 1 条、乱传 model 有兜底错误行。浏览器实拍:点测速后按钮「测速中 1/9」、第一行已出 `748 ms`、其余 8 行 `…` 排队,33s 全部完成——逐个填充生效。 +- 截图留档:`docs/speedtest-sequential-progress.png` + +### 追加:按钮去数字 + 当前行加载图标 +老板反馈测速按钮不要出现 `n/total` 数字,改成「轮到哪个模型、就在那一行显示加载图标」。 +- 按钮:`runSpeedtest` 期间文案改 `t('models.testingShort')`(「测速中…」),去掉 `latDone/latTotal` 数字;`el-button :loading` 自带转圈。 +- 当前行:新增 `latCurrentId`,循环里每测一个置为该 id、整轮结束清空;模板延迟格里 `v-if="m.id===latCurrentId"` 显示 CSS spinner(`.st-spin` 圆环旋转,`prefers-reduced-motion` 降速),否则显 `latText`。`latText` 未轮到/空闲统一 `—`(去掉原 `…`)。 +- i18n:删 `testingProgress`、加 `testingShort`(中英)。 +- 纯前端,build 覆盖 dist 即生效、未重启后端。新产物 `index-CZxVI3oL.js` / `Models-C-o3SZgZ.js`,线上 200、旧 hash 404。 +- 浏览器实拍:按钮「测速中…」无数字、`agnes` 已出 `929 ms`、`qwen3.8-flash` 行内转圈、其余 `—`。截图 `docs/speedtest-current-row-spinner.png`。 + +### 追加:失败行「重新测速」按钮 +老板要失败的模型旁边可点击单独重测。 +- `Models.vue` 新增 `retestOne(id)`:只测这一个模型(`POST {model:id}`),复用当前行加载图标;`latTesting || latCurrentId` 时禁用/忽略,避免与整轮或另一单测打架;单模型异常也不抛、写回失败行。 +- 模板:`st-err` 错误块右侧加 `.st-retry` 胶囊按钮(`refresh` 图标 + 「重新测速」),`v-if="latErr(m.id)"` 只在失败行出现;错误文本用 `.st-err-txt{flex:1}` 占满、按钮靠右。 +- i18n:`models.retry`(`重新测速` / `Retry`)中英。 +- 纯前端,build 覆盖 dist 即生效、未重启后端。新产物 `index-nCRwIFRg.js` / `Models-CGpanPte.js`,线上 200、旧 hash 404。 +- 浏览器实拍:整轮后 4 个失败行各带「重新测速」;点其中一个 → 仅该行转圈(`.st-spin`=1)、按钮未变「测速中…」(未误触发整轮)、15s 后该行结果刷新。截图 `docs/speedtest-per-row-retry.png`。 + +### 追加:每行常驻「单独测速」按钮(取代仅失败行重试) +老板要常态下(没跑整轮时)每个模型行右侧都有测速按钮,可单独测任意一个模型。 +- 把上一版只在 `st-err` 里的「重新测速」按钮改为**每个 `st-row` 右侧常驻一个 ⚡ 图标按钮** `.st-one`(`bolt` 图标,`title/aria-label=单独测速`),点击调 `retestOne(id)` 只测该模型;`latTesting || latCurrentId` 时禁用(一次只允许一个测速动作,防与整轮/另一单测打架)。 +- `st-err` 移除旧 `.st-retry` 按钮,只留错误文本;删除 `.st-retry` 样式,新增 `.st-one` 图标按钮样式(hover 用 `--primary`/`--primary-soft`)。 +- i18n:删 `models.retry`、加 `models.testOne`(`单独测速` / `Test this model`)中英。 +- 纯前端,未重启后端。新产物 `index-BYzyfwi3.js` / `Models-CJ5mchi4.js`,线上 200、旧 hash 404。 +- 浏览器实拍:9 个文本模型行 = 9 个 `.st-one` 按钮、无 `.st-retry` 残留;点第一行 `agnes-3.0-flash` 只它出 `754 ms`、其余仍 `—`、未误触发整轮。截图 `docs/speedtest-per-row-test-button.png`。 + +--- + +## 2026-09-15 · 移除 OpenCode 的 mimo-v2.5-free 模型 + +**需求**:老板要求把 `mimo-v2.5-free` 从 OpenCode 供应商去掉,相关配置与文档一并清理。 + +**改动** +- **`data/gateway.yaml`**:删 `providers.opencode.models` 里的 `mimo-v2.5-free` 条目、删 `pricing.per_model` 的 `mimo-v2.5-free`;opencode 注释「这 4 个」改「这 3 个」,并在排除/已移除清单加一行说明(此前实测可 200,但免费档常 429 限流,按要求移除)。opencode 现 3 个免费模型:`ling-3.0-flash-fin-free` / `nemotron-3-ultra-free` / `nemotron-3.5-lightning-free`。 +- **`README.md`**:供应商表格 OpenCode 行的模型清单去掉 `mimo-v2.5-free`。 +- **`tests/test_gateway.py`**:`test_load_config_providers` 里 opencode 模型集断言去掉 `mimo-v2.5-free`。 +- 注意:只删 OpenCode 的 `mimo-v2.5-free`,**b.ai 的 `mimo-v2.5` 保留不动**。 + +**验证**:`yaml.safe_load` 后 opencode models=3、pricing 无该项;全量单测 153 passed(2 个历史遗留不变)。**纯配置改动,hot_reload 自动生效、未重启**——线上 `/v1/models` 由 12 → 11、`mimo-v2.5-free` 已消失、`mimo-v2.5`(b.ai) 仍在。CHANGELOG 保留此前收录/实测该模型的历史条目(真实记录),此处仅追加移除说明。 + +--- + +## 2026-09-15 · 排查「opencode 模型大概率失败」+ 测速探针加 429/5xx 重试 + +**排查结论(非网关 bug)**:翻网关日志 `opencode.ai/zen/v1/chat/completions` 上游响应 = 30×200 / 14×429 / 3×503,且有明显「首个 429 → 隔 1~2s → 200」模式。**根因是 OpenCode 免费档对共享 key 的激进限流(429) + 偶发 503**。真实 chat 直连有 `retry:3` 兜底(退避 0.3/0.6s)多能扛过;但**一键测速是单次探针、不重试**,正好撞高频首个 429 → Models 页显示一片"失败"。反复点测速又消耗同一把免费 key 的额度 → 越点越限流。 + +**修复(老板选定的方案 1)**:让测速探针也重试。 +- `app/main.py` 新增 `_speedtest_retryable(e)`:仅上游 **429 / 5xx** 判为可重试;4xx(模型不存在/鉴权/参数)与超时**不重试**(前者无意义、后者拖慢整轮)。 +- `/v1/models/speedtest` 探针由单次改为 `for attempt in range(1,4)` 最多 3 次、退避 `0.3*attempt`(与真实链路一致),成功即 break;`latency_ms` 记整个重试过程总耗时(用户真实等待)。 + +**验证**:`_speedtest_retryable` 判定单测全对(429/503/500→重试、400/401/404/超时→不重试);全量单测 153 passed;`supervisorctl restart` → pid 249194、healthz ok。日志实测到重试生效:`ling-3.0-flash-fin-free` 一次 `503→503→200`(attempt 1/3、2/3)被救回。 + +**遗留发现(待老板定)**:`nemotron-3-ultra-free` 仍测速失败,但**已不是 429**——直连实测它响应要 **88.4 秒**("Ultra" 大推理模型 + 免费档,极慢),远超探针 15s 超时;`nemotron-3.5-lightning`(2.4s)、`ling`(1.1s) 正常。可选:①调大探针超时(但 88s 会让整轮测速极慢、意义不大);②像 mimo-v2.5-free 一样把 nemotron-3-ultra-free 移除(88s 不实用);③保留(测速如实显示它太慢,真实 chat 靠 120s server timeout 仍可用但要等 ~88s)。 + +--- + +## 2026-09-15 · 整体移除 OpenCode Zen 供应商 + +**需求**:老板决定把 OpenCode Zen 供应商整个去掉,相关配置、代码、文档一并清理。 + +**移除(opencode 专属)** +- **`data/gateway.yaml`**:删 `providers.opencode` 整块(base_url / `token_env: OPENCODE_API_KEY` / UA+哨兵 `extra_headers` / 3 个免费模型)+ `pricing.per_model` 里 3 条 opencode 免费模型 + 顶部注释供应商清单去 OpenCode。 +- **`app/adapters/openai_compat.py`**:删 `OPENCODE_SESSION_SENTINEL` 常量、`_call_headers()` 方法、`import uuid`;`chat()`/`chat_stream()` 请求头由 `self._call_headers()` 回滚为 `self._headers`(适配器回到"纯静态头")。 +- **`data/.env`**:删 `OPENCODE_API_KEY` 行(保留 AGNES/B_AI/VOLC 三把,权限 0600)。 +- **`README.md`**:顶部"四个供应商"→"三个"、架构注释"四家通用+opencode 会话头"→"三家通用+媒体端点"、供应商表格 OpenCode 行删除、OpenCode 两条硬性要求 blockquote 删除。 +- **`tests/test_gateway.py`**:`test_load_config_providers` 回退到 3 家、删 opencode 相关断言。 + +**保留(通用改进,非 opencode 专属)**:测速探针 429/5xx 重试(`_speedtest_retryable` + 重试循环)与 `_upstream_detail` 空 body→「调用失败」兜底 —— 对 b.ai/agnes 等偶发限流同样受益,仅把注释里的 "OpenCode" 字样改通用。前端 Models 页动态读 `/v1/models`,opencode 行自动消失,无需改前端。 + +**验证**:`yaml.safe_load` 后 providers=[agnes,b_ai,volc_engine]、文本模型回到 5 个;`openai_compat` 已无 `_call_headers`/`OPENCODE_SESSION_SENTINEL`;`import app.main` OK;源码/配置/README/测试 grep `opencode` 清零(CHANGELOG 历史条目保留);全量单测 153 passed。代码有改动 → `supervisorctl restart` → pid 254282、healthz ok、线上 `/v1/models` = 8(无 opencode)。CHANGELOG 此前收录/排查 opencode 的历史条目全部保留(真实记录)。 + +--- + +## 2026-09-15 · 移除 b.ai 的 mimo-v2.5 模型 + +**需求**:老板要求把 b.ai 供应商下的 `mimo-v2.5` 也去掉,相关配置、代码、文档一并清理。(注:与上一轮已删的 OpenCode `mimo-v2.5-free` 是两个不同模型。) + +**改动** +- **`data/gateway.yaml`**:删 `providers.b_ai.models` 里的 `mimo-v2.5` 条目、删 `pricing.per_model` 的 `mimo-v2.5`、并从 **`routes.wjd` 兜底链**移除第 4 项 `mimo-v2.5`(`hy3` 由「5)」改「4)」重编号)。wjd 链现 `[ark-code-latest, agnes-3.0-flash, qwen3.8-flash, hy3]`。 +- **`app/main.py`**:测速探针注释里 `b.ai(qwen3.8-flash/mimo-v2.5/hy3)` 去掉 `mimo-v2.5`(`max_tokens>2` 约束对 qwen3.8-flash/hy3 仍成立,逻辑不变)。 +- **`README.md`**:供应商表格 b.ai 行模型清单去掉 `mimo-v2.5`;路由链示例同步去掉并重编号。 +- **`tests/test_gateway.py`**:`test_load_config_routes` 断言 `wjd.models` 数量由历史遗留的 `== 6` 修正为实际 `== 4`(该用例此前一直 FAIL,本次顺带修好)。 + +**验证**:`yaml.safe_load` 后 b_ai models=[qwen3.8-flash,hy3]、wjd 链 4 项、pricing 无 mimo-v2.5;源码/配置/README/测试 grep `mimo-v2.5` 清零(CHANGELOG 历史保留);全量单测 **154 passed / 1 failed**(routes 用例转绿,仅剩 feedback 无关遗留)。**纯配置改动,hot_reload 自动生效、未重启**——线上 `/v1/models` 由 8 → 7、`mimo-v2.5` 已消失。 \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..5edb1c5 --- /dev/null +++ b/Makefile @@ -0,0 +1,34 @@ +# API Gateway 快捷命令 +# Windows 若无 make,可手动执行对应命令;或装 https://chocolatey.org/packages/make + +.DEFAULT_GOAL := help +CONFIG := data/gateway.yaml +PORT ?= 8808 + +.PHONY: help install run test lint clean + +help: ## 显示帮助 + @echo "api-gateway 常用命令:" + @echo " make install 安装依赖" + @echo " make run 本地启动(端口 $(PORT))" + @echo " make test 跑单元测试(不依赖真实上游)" + @echo " make lint 语法编译检查" + @echo " make clean 清理缓存/临时文件" + +install: ## 安装依赖 + pip install -r requirements.txt + pip install pytest httpx # 测试依赖(测试用,非运行必需) + +run: ## 本地启动 + @python -c "import os,sys,subprocess; env=dict(os.environ); env['GATEWAY_CONFIG']='$(CONFIG)'; env['GATEWAY_PORT']='$(PORT)'; subprocess.call([sys.executable,'run.py'],env=env)" + +test: ## 跑单元测试 + python tests/test_gateway.py + # 或: pytest tests/ -q + +lint: ## 语法编译检查 + python -m py_compile app/config.py app/circuit.py app/metrics.py app/main.py app/routing.py app/models.py app/adapters/*.py run.py + @echo "syntax OK" + +clean: ## 清理 + @python -c "import shutil,glob,os; [shutil.rmtree(os.path.join(d,'__pycache__'),ignore_errors=True) for d in glob.glob('**',recursive=True)]" diff --git a/README.md b/README.md new file mode 100644 index 0000000..14ee979 --- /dev/null +++ b/README.md @@ -0,0 +1,1178 @@ +# API Gateway + +统一多供应商 LLM 接入网关,纯后端 FastAPI,配置驱动。支持 **Agnes AI**、**b.ai**、**火山方舟 Coding Plan** 三个供应商,全部走 OpenAI 兼容协议。v2.4 已集成熔断、限流、图像/视频、指标、成本估算、热加载、测试等完整能力。 + +## 特性 + +- ✅ 多供应商统一路由(`model` 字段自动分发) +- ✅ 路由别名 `wjd`:运行时挑「当前可用 + 最近最快」的文本模型优先调用,其余按速度顺序 fallback + 熔断 +- ✅ 同模型重试 + 路由级超时 + **供应商熔断器**(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`(text)、`agnes-image-2.5-flash`(image)、`agnes-video-2.5-flash`(video) | +| b.ai | `https://api.b.ai/v1` | Bearer | `qwen3.8-flash`、`hy3`(text) | +| 火山方舟 Coding | `https://ark.cn-beijing.volces.com/api/coding/v3` | Bearer | `ark-code-latest`(text) | + +> Agnes 的图像/视频走自有端点,通过供应商配置里的 `media` 段指定。 + +## 配置 + +所有数据从 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" } +``` + +认证优先级:**环境变量 > yaml 里的 `token` 字段**。 + +### 路由别名 + 按「可用 + 速度」动态排序 + 熔断 +(第十一轮 #4:`wjd` 不再按配置里的数组优先级,改为运行时挑可用且最快的文本模型先调用;详见下方路由说明) + +```yaml +routes: + wjd: + timeout: 60 # 单模型 60s 没出结果就切下一个(避免 6×120s 挂死) + retry: 1 # 每个模型试 1 次,失败立即切下一个 + models: + - "ark-code-latest" # 1) 火山方舟(最高优先级) + - "agnes-3.0-flash" # 2) Agnes 兜底 + - "qwen3.8-flash" # 3) b.ai qwen 兜底 + - "hy3" # 4) b.ai hy3 兜底 + +circuit: # 供应商熔断 + enabled: true + failure_threshold: 3 # 窗口内失败 ≥3 次即熔断 + cooldown: 30 # 熔断持续 30 秒 + window: 10 # 滑动窗口 = 最近 N 次调用(按次数,非按时间) +``` + +> 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)。 + +调用时 `model` 填 `wjd`,网关按顺序尝试;某供应商连续失败会被熔断,期间快速跳过,让健康供应商顶上。 + +### 鉴权(页面账号体系 + 每账号 API Key) + +鉴权**不写在配置文件里**:账号、密码、API Key 全部由管理台页面维护,持久化在 `data/users.json` +(密码 PBKDF2 哈希、Key SHA-256 哈希,均不落明文;文件权限 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 不限数量**。显式设置/修改的密码至少 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 不再成倍放大配额。 + +### 历史(图像 / 视频 / 对话)落盘 + +这三类"生成过的东西"以前只存在浏览器里(图像/视频在 `localStorage`、对话在 `sessionStorage`), +于是换设备看不见、关标签页就丢;更糟的是 `setItem` 写失败(配额满)被 `catch {}` 静默吞掉, +表现就是"我生成过的东西怎么没了"。现在统一存服务端: + +``` +data/history.json # {账号: {类别: [条目…]}},权限 600,已进 .gitignore +GATEWAY_HISTORY=<路径> # 可选,测试/多实例时指定 +``` + +- **按账号隔离**:普通账号只看得到自己的历史;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 } + qwen3.8-flash: { input: 0.30, output: 0.60 } + # 未配置的模型不返回 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 / B_AI_API_KEY / VOLC_API_KEY +python run.py # 启动时自动读取 .env +``` + +优先级:真实环境变量 > `.env`(密钥所在,经各供应商 `token_env` 引用)> yaml 其它字段。 + + +## API 端点(含 v2.1 新增) + +| 方法 | 路径 | 鉴权 | 说明 | +|---|---|---|---| +| `GET` | `/` | 否 | 端点导航 | +| `GET` | `/health` | 否(可开) | 运维看板:uptime/失败率/耗时/熔断状态 | +| `GET` | `/health/{provider}` | 否(可开) | 供应商探活 | +| `GET` | `/models` / `/v1/models` | 是 | 全部模型 + 路由别名 + 供应商 | +| `POST` | `/v1/chat/completions` | 是 | 主接口(fallback + 流式 + 熔断 + 三级限流 + 成本) | +| `POST` | `/v1/chat/completions/batch` | 是 | 并发多 prompt | +| `POST` | `/v1/images/generations` | 是 | 图像生成(支持路由别名) | +| `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` 可以填**路由别名**(如 `wjd`):网关会自动解析到该路由链里第一个 `type==image/video` 的模型,找不到才 404。 + +## 关键行为说明(v2.4) + +- **三级限流**:路由级 `routes..rate_limit_rps` > 供应商级 `providers..rate_limit_rps` > 全局 `server.rate_limit_rps`。路由/供应商级按独立桶分桶,打满则 429;chat 接口下打满会切下一个模型而不是直接 429。 +- **媒体端点也限流**(v2.3 / v2.6 修正):`/v1/images`、`/v1/videos` 按 `providers..rate_limit_rps` 的**供应商桶**限流,与 chat 共用同一个 `prov:` 桶(v2.6 起媒体不再另起 `media:prov:` 独立桶 —— 那样实际放行量会翻倍、与文档不符)。高成本资源不再裸奔。 +- **route.timeout 全链生效**(v2.3):配了 `routes..timeout` 后,**整条链(含链首最高优先级模型)统一用这个超时**;之前只对兜底模型生效、链首仍用 `server.timeout`。 +- **熔断按次数窗口**(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` / `routes` / `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(data/gateway.yaml 的 auth.users 里 key) +AUTH="Authorization: Bearer <你的 key>" + +# 文本(自动路由)+ 响应带 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}' + +# 路由别名 wjd(运行时挑可用 + 最快文本模型优先,其余按速度顺序 fallback + 熔断) +curl -X POST http://localhost:8808/v1/chat/completions \ + -H "$AUTH" -H "Content-Type: application/json" \ + -d '{"model":"wjd","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 堆叠柱图 + 供应商份额 + 路由 vs 供应商 + 堆叠 + 延迟 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`):指标卡(模型/文本/图像/视频/路由/供应商)+ 路由别名表 + (降级链逐 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 张卡片、`