jidekin 3999c075ae feat(metrics): 指标改由 SQLite 提供(重启不清零)+ 月度用量导出
- 新增 _usage_snapshot():调用数/供应商/token/耗时(p50,p95) 走 api_calls 聚合,
  运行时长/在途/熔断仍取内存;库不可用自动回落内存态
- 影响 /metrics、/metrics/prometheus、/health.models;口径从「启动以来」变「最近 90 天」
- token 落库:表加 4 列(老库自动 ALTER),用 rid contextvar + token 侧信道关联
- 新增 /logs/usage/monthly 与 /logs/usage/monthly/export(仅管理员)+ 前端月度用量弹窗
- 模型统计排除无模型行(匿名早失败不再显示 ?)
- 版本 2.8.0 → 2.9.0
2026-10-23 11:28:53 +08:00

API Gateway

统一多供应商 LLM 接入网关,纯后端 FastAPI,配置驱动。支持 Agnes AI、OpenCode Go、Dots AI(小红书) 三个供应商,全部走 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 10 个模型:4 text(agnes-3.0-flash 旗舰、agnes-2.5-flash 支持图像输入)、3 image、3 video;其中 6 个免费 + 1 个限时免费(agnes-video-2.5-flash,见「模型清单同步」)
OpenCode Go https://opencode.ai/zen/go/v1 Bearer + x-opencode-session 35 个模型,含 1 个免费(space-bunny-free,见下方小节)
Dots AI(小红书) https://note3-prev-api.askdiandian.com/v1 自定义头 api-key dots3-note-prev(text + 视觉,512K,免费体验)

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": ...})。网关不原样透传, 而是按下面的优先级派生成一个稳定值再作为 x-opencode-session 发往上游 (第三十五轮更新;任何一级都不再回退成随机 UUID —— 随机 = 缓存命中率恒为 0):

优先级 来源 派生方式
① 入站 x-opencode-session 头(客户端显式指定,第三十五轮新增) sha256("s:{账号}:{客户端值}")[:32]
② 请求里的 conversation_id sha256("{账号}:{conversation_id}")[:32]
③ 都没带 → 用这个 API Key 自己(一个 Key 一个稳定会话) sha256("k:{去前缀Key}")[:32]
④ 连 Key 都没有(登录页会话) sha256("u:{账号}")[:32]
  • ①「客户端带了就用客户端的」:客户端最清楚哪几次调用算同一段对话,比网关拿 Key 兜底更贴合 它的会话划分;但仍按账号哈希,保留账号隔离 —— 否则两个账号只要用同一个值就会共用上游 缓存作用域。值同样过 conversation_id 那套入口校验 (仅 ASCII、≤128 字符),非法值静默丢弃并回退(可选头不该把请求打回 400)。

  • 同一账号的同一段对话恒定不变,不同账号之间天然隔离(两人碰巧用了同一个字符串也不会 共用同一个上游会话标识)。

  • 关于提示词缓存:会话 id 稳定是吃到缓存的前提,但不是充分条件(上游缓存本身是 机会性的)。2026-09-28 复测:同一个稳定会话下、同一段 4k token 前缀连打两次, 第二次 cached_tokens=1920(命中);而 2026-09-18 的观测里同一 session 连打 6 次 得到 [0,0,0,0,896,896](前几次未命中、之后才命中)。所以:别把它当保证, 但千万别让它随机 —— 每请求一个随机 UUID 等于永远不命中。 2026-09-28 实测更正:上游缓存并非严格按 session 隔离 —— 换一个会话头、同一段 4k 前缀照样命中(1920)。所以会话 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 段指定。

Dots AI(小红书,第三十六轮 2026-09-28)

官方文档:https://dots.ai/platform/docs(通读后按下面接入)。

项 值
Base URL https://note3-prev-api.askdiandian.com/v1
协议线 POST /v1/chat/completions(OpenAI 兼容)、POST /v1/messages(Anthropic 兼容,需固定头 anthropic-version: 2023-06-01)
认证 自定义头 api-key: <KEY> —— 既不是 Authorization: Bearer,也不是 x-api-key
模型 dots3-note-prev:上下文窗口 524,288(512K);官方未给最大输出上限("省略时由服务端默认策略决定")→ 配置留空不猜
能力 文本 / 图片 / 视频 / 音频输入、工具调用;OpenAI 线 chat_template_kwargs.enable_thinking 控制深度思考,Anthropic 线用 thinking.type
计费 当前免费体验(恢复收费前会提前告知)→ 配置 free: true,页面上打「免费」标
限流 官方按单个 API Key 计:60 次/分钟、1,500,000 Tokens/分钟 → 配置 rate_limit_rps: 1.0(网关限流桶按 Key 分,语义一致)

为它新增的鉴权样式 api-key:AUTH_STYLES 原有 bearer / x-api-key / none,现加 api-key。用法:providers.<key>.endpoints.<protocol>.auth: "api-key" → 适配器在 auth_headers() 里发 api-key: <token>;静态头里残留的同名头同样会被剥掉再按线补上 (与 Bearer / x-api-key 一致)。上线实测:两条线各发一次瘦请求均 200, /v1/chat/completions 回 usage{prompt 17, completion 8}, /v1/messages 回 usage{input 17, output 8}。

顺带补的一条口径(接 Dots 时实测发现):Anthropic 系的 usage 里 input_tokens 不含缓存部分 —— 缓存命中在 cache_read_input_tokens、写缓存在 cache_creation_input_tokens (三者互斥)。因此 _usage_detail() 现在分口径计算:OpenAI 口径 prompt_tokens 已含缓存; Anthropic 口径 = 三者相加为输入总量、缓存命中取 cache_read_input_tokens —— 否则 messages 线的缓存量永远记成 0。

虚拟模型 id(别名 wjd,第三十一轮)

给客户端一个名字固定的入口:客户端永远只写 model: wjd,实际转发到你选的哪个真实模型 由管理员在网页上决定 —— 上游模型换名字、换版本、换供应商,客户端一行代码都不用改。

怎么配:网页「供应商与模型」页有一张「虚拟模型 id(别名)」卡片 → 下拉选目标模型 → 「保存映射」。 保存即生效(走 PUT /config,不重启网关)。也可以直接改配置文件的 aliases 段:

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 媒体端点)

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),不会让进程起不来。限流因此变成两级:供应商 > 全局。

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.<key>.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:<pkey>(此前媒体用独立桶,实际放行量翻倍,与文档不符)。
  • 热重载保留运行时状态:不再清空熔断状态 / 调用指标 / 访问日志 / 限流令牌桶(此前整体重建,刚熔断的坏供应商会被立刻恢复重试、指标与日志清零);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() 检查 —— 一边永不计、一边永远查,检查形同虚设)。现用独立的 <provider>#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:<key> 旧桶名残留(与 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 分钟)一项。

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)

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(防暴力枚举)

可观测性 + 定价

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 }
    # 未配置的模型不返回 estimated_cost_cny

启动

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:

cp .env.example .env
# 编辑 .env 填入 AGNES_API_KEY / OPENCODE_API_KEY / DOTS_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.<key>.rate_limit_rps > 全局 server.rate_limit_rps。供应商级按独立桶分桶,打满则 429(chat / 媒体共用 prov:<pkey> 桶);路由级限流随路由功能删除。
  • 媒体端点也限流(v2.3 / v2.6 修正):/v1/images、/v1/videos 按 providers.<key>.rate_limit_rps 的供应商桶限流,与 chat 共用同一个 prov:<pkey> 桶(v2.6 起媒体不再另起 media:prov:<key> 独立桶 —— 那样实际放行量会翻倍、与文档不符)。高成本资源不再裸奔。
  • 协议线闸门(第二十七轮):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 零适配直连。

调用示例

# 授权:所有调用带 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/<video_id>?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://api.wangjinding.com/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 新会话用作默认值)、主题切换(浅色/深色,<html class="dark"> + 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://api.wangjinding.com/web/#/login 已服务新产物 (公网取 login-banner-7rrSIoiP.svg 200 / 7139B),后端零改动、未重启。 另修一处小 a11y 问题:i18n.ts 只在 setLocale() 里写 <html lang>,初始化路径漏了, 导致 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、 <html lang="en">、卡片 434 高同样无溢出);真机交互验过语言切换(右上角胶囊 → English → 文案与 <html lang> 同步)与空提交报错(卡片内红色提示、卡片自动增高不溢出)。 线上 https://api.wangjinding.com/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。(第二十七轮:路由别名表已随功能删除)
    • 测速两种用法(2026-10-12):一键测速=整轮串行(测一个显示一个,避免把免费档额度瞬间打满 → 上游 429);每行的 ⚡ 单独测速可并发(各测各的、不用等上一个回来,上限 3 个;与整轮互斥)。后端同一个探针端点 POST /v1/models/speedtest,传 model 即只测那一个。 (降级链逐 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 张卡片、<video> 正常、状态/任务号/服务/耗时齐全)。
  • 图像卡与视频卡下方新增提示词一行(视频任务对象以前根本没存 prompt,现已随任务一起记录并 upsert 到服务端;改动前生成的旧条目无提示词可考,显示 —)。长提示词按 3 行截断、悬停看全文。
  • 仪表盘「已运行」改为本地每秒推进(/health 5s 一拉,旧版每 5 秒跳一格)。
  • 新增 /history/{kind} 端点与 2 组回归测试,单测 116 passed / 0 failed。

第十六轮(2026-09-13)Key 数量上限的提示收敛为「已达上限」

  • 老板要求:到量时的长句(「已达上限:普通账号最多同时保存 3 把,删掉不用的再创建」)改掉, 只留「已达上限」四个字。三处一起收敛:接口 400 文案(app/users.py)、页面顶部告警、 创建按钮 tooltip 与点按钮时的 toast。
  • 「最多几把、要删哪把」这类说明留在页面上(按钮到量置灰 + 数字仍在 /auth/apikeys 响应里), 不再塞进每次点击的 toast 里。

全面体检后的「全部修复」轮(2026-09-13,紧跟全站体检):一个 P0 撞名 + 六个 P1 + 三处 P2 来源:老板要求全站体检(前端 8 分辨率 × 3 主题 × 中英 × 11 页 + 后端 130 单测), 体检发现的问题全部核实属实后按 P0 → P1 → P2 顺序修完。 (注:README 的轮次序列主线是后端修复轮(第九~十六轮),媒体产物下载与前端整体重设计两轮未单独编号; 本轮即「体检发现项修复」轮,内部代号 fix18,备份在 /root/.trash/<归档>/。)

  • P0 全局类名撞车(真 Bug,肉眼可见):style.css 里有个全局进度条样式 .bar { height: 5px; overflow: hidden },而对话页输入区那一行按钮的容器 class 也叫 bar —— 于是「上传图片 / 上传文件」按钮、模型下拉、token 计数、发送按钮全被压进 5px 高、还被裁掉。 进度条改名 .meter(Dashboard.vue 同步),.composer .bar 恢复 34px(手机 86px)。 教训:全局样式里别用 bar/cell/t 这类极短通用词做类名,组件内同名会被静默命中。
  • P1-1 设置页标签被挤成竖排:.set-row > .lb 没有 flex-shrink: 0,窄卡片下「供应商状态」被压到 13px 宽、 一个字一行。改 flex: 0 0 auto(.lb.flex-1 保留可伸缩),.rt 改 flex: 0 1 auto + min-width: 0 + flex-wrap: wrap。 实测 390 宽下所有标签单行、右侧不再溢出卡片。
  • P1-2 图像页「张数」数字看不见:el-input-number 的 controls-position="right" 占了宽度, 窄列 92px → 108px、min-width: 30px。实测输入区 8px → 51px(桌面与手机一致)。
  • P1-3 非对象 JSON 从 500 变 400:POST 时若 body 是合法 JSON 但不是对象([1,2] / "x" / 1), pydantic 会抛 ValidationError → 500。新增 _json_object() 统一入口,/auth/login、/auth/password、 /auth/users、/auth/users/{u}/password、/auth/apikeys、/history/{kind} 一律回 400 并说清「请求体必须是 JSON 对象」。
  • P1-4 X-Forwarded-For 取段错误(限流可被绕过 / 也可被冒用):原来取 XFF 的最左段, 而左侧段是客户端可以随便编的 → 攻击者每次换一个假 IP 就能绕过登录失败限流,反过来也能伪造别人的 IP 把别人刷进黑名单。改为取最右段(真正由我们信任的反代写进去的那一跳),并且只在本机反代直连时才信 XFF, 另截断到 64 字符防超长头部。
  • P1-5 视频轮询偷跑熔断试探令牌:videos_poll 里 wait=true 分支会走两次 allow(); 且 n != 1 的归还挪到了限流/熔断检查之后 —— 纯参数错误会白吃掉一个 HALF_OPEN 试探令牌。 改为 probe_held 标记(一次请求只取一次令牌),并把 n != 1 的入站校验放在所有限流/熔断检查之前 (图像侧同样处理,/v1/images/generations 的 n != 1 现在也先于熔断检查返回 400)。
  • P1-6 history.upsert 索引重建:没有 id 的条目插入后索引不更新,后续同 id upsert 会追不到。 改为恒重建索引,并补回归测试。
  • P2-1 配置里的明文 Key 死配置:data/gateway.yaml 里残留的 key: 明文配置(早已废除、不会被读取, 但会误导人以为「密钥写在 yaml 里」)删除,密钥统一走 .env。
  • P2-2 vite 代理漏了 /history:frontend/vite.config.ts 的 dev proxy 没配 /history, 本地开发时历史读写会 404(构建产物走同源,线上不受影响)。
  • P2-3 手机端手感:.el-button--small 手机端 min-height: 34px(原 24px,低于触控推荐下限)、 底部 tab 与场景卡副标题字号 11.5px(原 10 / 10px)、视频场景卡手机端两列(原来一格一行、 且「首尾帧(图生视频)」会折成两行)、用户管理页手机端折列 + 操作按钮改图标。
  • 顺带:PBKDF2 哈希挪到线程池(_offload),避免登录/改密时阻塞事件循环。
  • 回归测试新增 7 条(非对象 JSON 400 / XFF 最右段 / 图像 n≠1 不吃试探令牌 / 视频轮询只取一次令牌 / 索引重建 / 线程池哈希),单测 137 passed / 0 failed、pyflakes 0、vue-tsc typecheck 0 error、 构建通过(index-Du-kU_xh.css / vendor-element-Bryi61XR.js)。
  • 场景卡由三列改两列(老板 2026-09-13 拍板「改」):桌面参数列只有 ~289px 宽,三列时每格 91px, 中文「首尾帧(图生视频)」标签(实测 108px)在格内必然折两行、英文 Keyframe (img2video)(117px)更挤。 改为 repeat(2, minmax(0, 1fr))(手机端原来的两列覆盖也随之删掉,规则收敛到 style.css 一处), 每格 141px(可用 127px):中英标签全部单行、三格等高(zh 49px / en 46px)、右边界距卡片 15px。 实测 1280/1440/1024 桌面 + 390 手机 × 中英 7 组全部 折行=no、横向溢出 0。
  • 上线与复核(2026-09-13 17:13 老板批准重启):supervisorctl restart api-gateway:api-gateway_00; 线上 /healthz 200、非对象 JSON 400、错误密码 401、无凭证 401;线上 CSS 内含 .meter{height:5px}、 .set-row>.lb{...flex:0 0 auto}、手机端 min-height:34px,旧的 .bar{height:5px 已消失; 专项探针 24 组合(B/A/C 主题 × 1280/390 × 6 页)横向溢出全 0,输入区 34/86px、张数输入 51px、 手机触控目标 34px、字号 11.5px,.acc-sub 仅手机显示、操作按钮 3 个全在屏内。 收尾(同日傍晚,老板「收掉、清掉、改」):临时体检环境(后端 8899 + vite dev 5199 + gwcheck.vite.config.mts) 已停进程并归档到 /root/.trash/<归档>/(含 MANIFEST.md 与恢复命令); frontend/dist.bak-0913-0127 与 4 处 __pycache__ 同样归档;场景卡改两列后构建并上线 (index-Gg1BF2WV.js / index-DdRZNrpf.css,纯静态切换、后端零改动未重启); 顺手补 .gitignore 里漏掉的 .test_history.json。 保留未动:live_check.py / smoke_test.py(README 写明的正式运维脚本)、现役 frontend/dist/。

第十五轮(2026-09-13)改密不再要求「当前密码」

  • 老板要求:已经用网页登录进来了,改密就别再让人输一遍当前密码 —— 会话本身就是身份证明。 设置页现在只留「新密码」输入框(+一句说明),POST /auth/password 的 current_password 变为可选。
  • 安全边界不退化(单测覆盖):仍然必须持会话(API Key 调这里照样 403); 改完立刻吊销该账号全部会话强制重新登录;新密码与原密码相同时照样拒绝(不填当前密码也能判断 —— 拿新密码去校验已有哈希即可);老客户端若仍传 current_password,传错必须报错,不能默默放行。
  • 单测新增 1 组共 5 个断言(免密改密成功/旧会话失效/旧密码失效/同密码拒绝/错误当前密码拒绝/Key 改密 403), 总 125 passed / 0 failed。

第十四轮(2026-09-13)页面细节:运行时间实时走 + 真删要二次确认 + Key 页自带调用文档

  • 指标页运行时间实时跳动:/metrics 是 8s 一拉,直接把返回值渲染就是「8 秒跳一格」。 改成以「拿到值的那一刻」为基准、本地每秒累加(uptimeAt + nowTick + 1s 心跳,onUnmounted 清理), 与仪表盘同一套做法 —— 秒针连续走,且不影响后台 8s 的真实采样。
  • 清空/清除类操作补二次确认:视频页「清除已完成」、图像页「清空历史」都是服务端真删且不可逆 (不是只清本地视图),原先点一下就没了。现在弹确认框并写明条数与后果(另:视频页没东西可清时按钮置灰)。
  • 设置 → 关于去掉文档外链(不再往外部站点跳),同时删掉对应 i18n 键。
  • API 密钥页新增「API 调用说明」:接口地址(复制按钮)· 鉴权头 · 模型选择(填真实模型 id;路由别名已于第二十七轮删除)· 请求格式 · 常用端点表(与 app/main.py 的真实路由一一对应)· 四段可直接复制的示例 (对话 / 图像 / 视频提交+轮询 / Python OpenAI SDK)· 七条注意事项(n=1、seconds 4–12、 轮询别快于 5s、素材可用 data URI 但请求体 <2MB、Key 调管理接口 403、Key 泄漏处置、审计归属)。 示例里 Key 一律用 $GW_KEY 占位,不把真实密钥渲染进文档。
  • 前端 npm run typecheck 0 error、npm run build 通过(index-Dp4R0e28.js);真机(临时实例)验过: 运行时间 21s→24s→28s 连续走、确认框「取消保留 / 删除真删(服务端历史同步清空)」、 Key 页文档中英文渲染、按文档中的 curl 原样调用对话/图像成功、Key 调管理接口回 403。 后端本轮无改动。

第十三轮(2026-09-13)按 Agnes 三个文档把「对话 / 图像 / 视频」做全场景覆盖(含素材上传) 依据:agnes-30-flash / agnes-image-25-flash / agnes-video-25-flash 三份官方文档 + 真 key 实测。

  • 素材上传(三个页面都能"给图"了):新增 frontend/src/lib/upload.ts —— 浏览器内把选中的 图片用 Canvas 压缩到分级档位(对话/参考图 1024px、视频首尾帧 1280px),逐级降档直到落进单件预算, 再转成 data: URI 直传。实测上游三条路径都接受 data URI(对话视觉、图生图、视频首尾帧/参考音频), 所以不必引入上传端点与临时文件:素材不落盘、不占公网带宽。音频无法在浏览器重编码,只做体积与格式校验。
  • 整包体积预算:网关 max_body_size = 2MB、Nginx 也是 client_max_body_size 2m,而 base64 会再放大 4/3 —— 提交前统一 assertBodyBudget() 检查(素材 + 提示词),超了给一句人话,而不是让用户撞 413。
  • 对话页:新增「上传图片」(可多张、可删、可混 URL);模型下拉给视觉模型标 👁;带图但所选模型 不支持视觉时提前告警 + 一键切到视觉模型(避免"发了图但模型根本没看")。历史落盘只存缩略图 (服务端单条上限 512KB,原图 base64 会被截断成坏图)。
  • 图像页:参考图可上传(缩略图预览,≤5 张;也可粘 URL);张数改成逐张串行生成 —— 实测上游 n=2 直接 400「n 必须为 1」,网关入站挡下并 400 说明正确用法,页面则每张一次 n=1、 出图即上屏、中途失败保留已生成的说清第几张断的。
  • 视频页:首帧/尾帧可上传或粘 URL(二者可混用);reference 模式的参考图(≤5)与参考音频(≤3) 同样支持上传;新增 seed;卡片显示素材摘要(只存文件名,不把 data URI 塞进 16KB 的历史条目)。
  • 后端入站校验补齐(按文档"Flash 专属错误/生成模式规则"):size 只认 720P、aspect_ratio 白名单 (21:9/16:9/4:3/1:1/3:4/9:16)、n 必须 1、videos 明确拒绝(此前字段未声明会被 pydantic 静默丢弃, 用户以为传了参考视频其实被吞);非法组合一律干净 400、不发上游、不进熔断。
  • 上游错误分流对齐:图像路径此前所有上游错误一律 502 且都记媒体熔断 —— 选错一个尺寸戳三次就能把 图像页+视频页一起打成 503;现在 4xx → 干净 400(带上游原话)不记熔断,5xx 才 502 + 记熔断(与第十轮视频对齐)。
  • 轮询限流不再误伤:实测 /agnesapi 每 3 秒一问就零星回 429「查询过于频繁」;原逻辑把 429 记成熔断失败 并给前端 502 —— 连撞三次就把整个媒体服务熔断 30 秒。现在回 200 + throttled + retry_after, 熔断桶与调用指标都不动,前端按退避继续轮(页面轮询间隔保持 5s,不按文档建议的 1~2s,正是为了不撞限流)。
  • 视觉能力位:/v1/models 新增 vision(agnes-3.0-flash = true,即文档里的"输入模态:文本、图像 URL"; OpenCode Go 侧 deepseek-v4.1-flash 与 deepseek-v4-flash-vision-exp 实测同为 true); 带图请求不再重排模型(第二十七轮:路由链已整体删除,网关不替用户换模型)——选了不支持视觉 的模型就照原样发上去,前端提前给告警条并提供一键切换,网关侧只记一条日志。
  • 回归测试新增 6 组(vision 暴露 / 视觉优先重排 / 带图块识别 / 图像 n 拦截 / 图像 4xx·5xx 分流 / 视频 videos·size·aspect·n 校验 / 轮询 429),单测 124 passed / 0 failed、pyflakes 0; 前端 npm run typecheck(vue-tsc)0 error —— 顺手补了 element-plus 语言包的模块声明、 删掉 Dashboard.vue 里残留的 :class="c.cls || ''"(该字段早已不存在)。

第十一轮(2026-09-13)日志:图像/视频响应数据 + 视频轮询合成一条

  • /logs 里图像 / 视频生成现在有「响应数据」了:图像行补 response(上游摘要: served 模型 / 供应商 / 张数 / 耗时 / 首张 url,base64 太长只留头部),视频创建行补 response(video_id / 模型 / 供应商 / status / async)—— 展开行即可看到,不用再翻上游。
  • 视频轮询不再每条各占一行(原来每 5s 一个 GET /v1/videos/{id} 就多一行,整个 生成过程刷屏几十行)。改为按 video_id 在内存聚合,/logs 只返回「创建」那一条, 展开后在「轮询记录」时间线里一次看全每次轮询的状态 / 进度 / 上游原文(前端 el-timeline 渲染,时间线每行附原始 JSON,上限 500 次、最多追踪 200 个任务)。
  • 新增 3 组回归测试(图像带响应 / 视频轮询合成一条 & 轮询全部数据 / 4xx 分流), 单测 113 passed / 0 failed、pyflakes 0。

第十二轮(2026-09-13)设置精简 + 按用户审计 + 速度路由

  • **#1 设置页去掉「对话默认参数」**卡片(对话页内的参数照常可临时调,只是不再有全局默认值编辑器)。
  • #2 日志/资产按用户隔离 + admin 集中审计:/logs 现在对所有人(含 admin)只显示自己的调用; 新增管理员专属只读端点 GET /auth/users/{name}/logs 与 GET /auth/users/{name}/history/{kind}, 集成进「用户管理」页的行展开:展开任一账号即看 TA 的调用日志(含视频轮询合成)、图像资产、视频资产(三个 tab、懒加载、缩略图/预览)。非 admin 403、账号不存在 404。
  • #4 wjd 路由改为「先判可用 + 速度最快优先」:不再按 yaml 里的数组优先级,而是 —— ① 当前不可用的模型(供应商没配凭证 / 熔断 OPEN)排到最后;② 可用模型按最近平均延迟升序(最快先调); ③ 没测到延迟的可用模型给「探测位」排在已测慢模型之后,以便学到它的速度;④ 冷启动全链无样本时原样退回配置顺序。 直接填真实模型 id(非路由别名)不受影响,保持确定性。新增 Metrics.recent_avg_latency()。
  • 新增回归测试(按用户日志/资产端点 + 越权/404/非法 kind + 速度&可用性排序 + 冷启动回退), 单测 115 passed / 0 failed、pyflakes 0。
  • #3 全场景调用(依 Agnes 官方文档解锁):
    • 视频页新增「场景」选择器 —— 文生视频 / 首尾帧(图生视频)/ 参考图·音频,字段严格对齐 Agnes mode ∈ {text, keyframe, reference}:keyframe 传 first_frame/last_frame(至少一个),reference 传 images(≤5)/audios(≤3,提示词可用 <Picture N>/<Audio N>);seconds 放开到 4–12;aspect_ratio 全量 21:9/16:9/4:3/1:1/3:4/9:16;size 固定 720P。
    • 图像页新增「比例」(1:1/3:4/4:3/16:9/9:16/2:3/3:2/21:9)、尺寸 1K–4K,以及图生图 / 多图合成(每行一个图片 URL 或 data:)。
    • 对话页新增「附图(视觉)」:带图的用户消息按 OpenAI 视觉格式 content=[{type:text},{type:image_url}] 发送(需所选文本模型本身支持多模态)。
    • 后端 _validate_video_request 在网关按上述契约入站校验非法 mode/媒体/时长组合 → 干净 400、不发上游、不进熔断。
    • 实测:真实调用 Agnes(当前免费)跑通 文生图→图生视频(keyframe, completed 带 mp4)、参考图(reference, completed)、6 图被网关 400 拦下。

第十一轮补充(2026-09-13)鉴权可见性 / 日志展开 / 速度路由

  • 日志展开不被自动刷新收起:日志页每 5s 自刷新会整体替换表格数据、把展开的视频 轮询详情重新折叠;改为记录已展开行的 row-key(rid 兜底 method:path:ts),刷新后 toggleRowExpansion 显式恢复;并对已展开、仍生成中的视频行由日志页每 5s 主动轮询 (先看旧数据里展开的未完成视频 → 打一次 GET → 再取 /logs),让详情时间线实时往下走, 完成后自动停轮询。视频页本身也已是 5s 轮询。
  • **#1 设置页去掉「对话默认参数」**卡片(对话页内联参数照常保留)。
  • #2 日志可见性收口:/logs 对所有人(含 admin)只显示自己;新增 admin 专属 GET /auth/users/{name}/logs 与 GET /auth/users/{name}/history/{kind},把「看别人的 调用日志 + 生成的图像/视频资产」集成进用户管理页的行展开(调用日志 / 图像资产 / 视频资产 三个 tab,懒加载、只读、非 admin 403、账号不存在 404)。
  • #4 wjd 路由改「可用 + 速度」排序:路由别名不再走配置里的静态优先级,而是先剔除 当前不可用的文本模型(供应商没凭证 / 熔断 OPEN),可用者按最近平均延迟升序(最快先调), 没测到延迟的可用模型给「探测位」兜到已测慢模型之后,整条链都没样本时原样退回配置顺序。 直接填真实模型 id(非路由)不受影响。新增 Metrics.recent_avg_latency()。
  • 单测 115 passed / 0 failed、pyflakes 0。

第二十轮(2026-09-13)对话页「整页要一直往下拉」——grid 行高没钉住 来源:老板 ——「对话里面被挤压,页面要一直下拉,对话框要固定高度、滚动条」。

先说清真因(临时实例实测复现,不是感觉问题):.chat-layout 是 display:grid, 但没有声明 grid-template-rows → 默认 auto,这一行的高度按内容撑开 (24 条消息时行高 6156px、手机 7982px)。行一撑高,.chat-main / .chat-card 的 height:100% / flex:1 又反过来跟着这个行高走,于是: .msgs(overflow-y:auto)永远等于内容高度、自己永远不滚, 整页(.gw-body)被撑成 6172px / 7994px 的可滚区域, 输入框被推到视口下方 5354px / 7202px —— 想发下一条得先一路滚到底。 佐证:旧构建下 .gw-body 可滚 5354px、.msgs scrollHeight == clientHeight、 输入区 ❌ 被切 5354px;其余页面(图像 / 视频 / 日志)量下来都没有这个问题 —— 只有对话页的两栏骨架有这个 bug。

修复三处(前端):

  1. style.css .chat-layout 补 grid-template-rows: minmax(0, 1fr):行高吃容器给的 确定高度(height:100%),超出的部分交给内部滚动。minmax(0, …) 而不是 1fr 是必须的 —— 1fr 的下限仍是 auto,照样会被内容顶开。
  2. Chat.vue .chat-main 补 min-height: 0:flex/grid 子项默认 min-height:auto (= 内容高度),不写这一条,里面的 .msgs 还是撑得开、滚不动。
  3. Chat.vue .conv-list 补 min-height: 0(左栏会话列表同理,长列表自己在栏内滚)。
  4. 顺带修掉一个连带 bug:scrollToBottom() 原来在 watch(messages, …)(默认 flush:'pre')里同步读 scrollHeight —— 读到的还是旧的高度,加上 .msgs 之前根本 不滚,等于一直是空操作。现在改成 nextTick() 里滚,打开长会话直接停在最新一条。

实测(临时实例,24 条混合消息:长 markdown + 代码块 + 推理块 + 降级 meta):

项 桌面 1280×880 手机 390×844
页面自身滚动 ✅ 不滚(.gw-body 可滚 0px) ✅ 不滚(0px)
消息区自己滚 ✅ 可滚 5370px ✅ 可滚 7269px
打开位置 ✅ 最新一条(scrollTop = 最大) ✅ 最新一条
输入框 ✅ 完整可见(距底 16px) ✅ 完整可见(距底 67px,底部 Tab 之上)
真越界元素 ✅ 0 个 ✅ 0 个

另测:点「新建对话」清空后空态占位居中、输入框仍贴底;同批体检脚本依次量了 仪表盘 / 图像 / 视频 / 日志,均无「真越界」(仪表盘与视频页在窄屏按设计让整页滚,属预期)。 质量门:vue-tsc 0 错、vite build 通过、check:svg 通过(本轮未动后端,故不涉后端单测)。 滚动条本身沿用全局 ::-webkit-scrollbar 细条样式(8px);是否常显取决于各系统 是否启用 overlay 滚动条,与站内其他滚动区域口径一致。

  • 上线(2026-09-13 17:56,老板批准):npm run build → 线上现役 index-C_MmjTC1.js / index-BuS4X-hx.css / Chat-DUjZh8wz.js / Chat-C5OGUx8e.css (Videos-CYhg2onR.js 等也跟着换名 —— 它们 import 了换名后的 index chunk,内容里引用文件名变了)。 旧 index-Yy0kGuVA.js / index-DKyqf84q.css / Chat-BMV2mwlU.js / Chat-CJxLcgM9.css 均已 404。 本轮只动前端,没有重启后端:进程 pid 1999293(127.0.0.1:8808)未动,网页会话不会被踢、不用重新登录。 复核:公网 /web/ 200 且引用新 hash、新 asset 200 / 旧 asset 404、/healthz 200、CSP 未放宽; 拉线上产物核对 —— index CSS 含 grid-template-rows:minmax(0,1fr)、Chat CSS 含 min-height:0、 Chat JS 里滚到底已包在 nextTick 回调里;公网登录页实测正常渲染(无白屏)。 小坑记一笔:查 Cache-Control 要用 GET(curl -s -D - -o /dev/null), curl -I 发的是 HEAD,而 web_cache_policy 中间件只处理 GET → 会误判成「没设缓存头」。

第二十四轮(2026-09-13)管理员停用 / 启用账号(停用=登不进、Key 也失效) 来源:老板一句「admin 管理员支持停用和启用用户,停用的用户不能登录,也不能调用 apikey」。

  • 改了什么

    位置 内容
    app/users.py 账号记录新增 disabled / disabled_at;is_disabled()、set_disabled(name, disabled, by)(幂等;admin 永不可停用、不能停用自己,两条规则只在 store 里判一次);list_users() 回状态与停用时间;resolve_key() 跳过已停用账号(Key 记录不删除);disabled_key_owner() 供鉴权层区分「Key 有效但账号停用」;启动加载时 _keep_admin_usable() 把手工写入的 admin disabled 自动恢复并告警
    app/main.py 登录:口令校验通过之后再判停用 → 403「账号已被停用,请联系管理员」(不知道密码的人依旧只看到 401,探不出账号状态);_identity_from_credentials() 会话分支加兜底(停用即吊销该账号会话);require_auth() 对「已停用账号的 Key」回 403 而非 401,且不计入鉴权失败限流;新增 PUT /auth/users/{name}/disabled(admin + 仅会话;停用时吊销其全部会话);新增 _body_bool() —— {"disabled":"false"} 绝不能被 bool("false") is True 当成真,坏值直接 400
    用户管理页 每行「停用 / 启用」(停用带二次确认)、账号名旁「已停用」胶囊(悬停显示停用时间)、停用行压暗;admin 那行不给这颗按钮;操作列手机端从 4 颗图标变 5 颗 → .ops 加 flex-wrap(宁可换行也不撑宽表格)
    i18n 新增 7 条中英文案(userDisabled / userDisabledAt / disableUser / enableUser / confirmDisableUser / userDisabledOk / userEnabledOk),中英 674 / 674 对称
    顺带修的真 bug frontend/src/api.ts 一直只读 body.detail,而网关自己的报错信封是 {"error":{"message":…}} → 全站错误提示退化成「HTTP 400」。现在统一认两种信封并导出 errText();登录页 403 也改为显示服务端原文(此前是写死的「账号被禁用或角色异常」)
  • 验证(隔离实例 8899,项目副本 + 临时 users24.json,生产 data/ 未碰)

    • 单测 155 passed / 0 failed(原 151 + 新增 4:三闸门 + 启用恢复、权限与入参矩阵、全接口闸门与手工改盘兜底、admin 自动恢复)。环境无 pytest,用 python tests/test_gateway.py 跑。
    • API 逐条实测:停用前 Key 调 /models 200 → 停用后登录 403、Key 403、旧会话 401、密码错仍 401 → 重新启用后登录 200 且原 Key 恢复 200(api_key_count 仍为 1,证明 Key 没被删);负例:停用 admin 400、不存在的账号 404、"maybe"/[] 400、字符串 "false" 不停用、拿 Key 调停用接口 403。
    • 真浏览器:确认框文案、toast、已停用胶囊、按钮切换、启用恢复、英文界面(Disable / Disabled)全部实测;被停用账号在页面上登录,报的就是「账号已被停用,请联系管理员」;顺带验证错误信封修复(非法账号名 toast 从 HTTP 400 变成「账号名只能由字母和数字组成」)。
    • 未实测项(如实记):390px 手机断点没测到 —— 本会话浏览器没有视口控制(试过 Ctrl+缩放压低 CSS 视口无效),故用 flex-wrap 兜住「5 颗图标超宽」的最坏情况,建议真机上瞄一眼。
  • 上线(2026-09-13 20:0x,老板批准):npm run build → 线上现役 index-BYW9huII.js / index-BCEpjaoj.css / Users-Ym7Y7v4h.js(旧 index-BV89HnWe.js 已 404); supervisorctl restart api-gateway:api-gateway_00(旧 pid 2102891 → 新 pid 2157737,仍监听 127.0.0.1:8808)。 本轮有后端改动,重启会清空内存态网页会话 —— 所有人(含 admin)需要重新登录。 复核:公网 /healthz 200、/web/ 200 且引用新 hash、新 asset 200(immutable 长缓存)与旧 asset 404、 CSP 未放宽、index.html 仍 no-cache;新端点在线判据 = 无凭证调 PUT /auth/users/x/disabled 得 401(旧代码是 404)。

第二十三轮(2026-09-13)「网关配置」页 —— 配置文件可视化(admin,保存即生效) 来源:老板三点 ——「设置里的『关于』整块去掉」「配置文件里的配置项都做成 admin 能配、保存后实时生效」 「改完直接重启上线」。收尾时老板一句「收掉」= 把这一轮彻底闭合(含排查卡点、上线、清理)。

  • 改了什么

    项 内容
    设置页 「关于」整块删除(设置页不再露出版本/仓库信息)
    新页面 /gateway-config(侧栏「网关配置」,仅 admin):data/gateway.yaml 的每一项都成了可视控件
    保存行为 校验 → 原子写盘(os.replace + 滚动备份 .bak + 权限 600)→ 复用同一条 _apply_config 立刻切运行态
  • 后端

    • 新增 app/settings.py:配置文件 ↔ 面板 JSON 的完整映射、带注释的 YAML 渲染(保存后文件还是人读的样子)、备份与原子写。
    • app/config.py 抽出 parse_config():先内存解析校验、不通过就不写盘;新增 _opt_bool() (顺手修掉 bool("false") == True 这个真 bug);server.port 走 _opt_int + 1–65535 校验。
    • GET /config(管理员):面板值 + 文件原文 + 告警 + 需重启键 + 模型/路由清单; 密钥只回报「配没配」,绝不回显。
    • PUT /config:管理员 + 网页会话(拿 API Key 调一律 403);热重载循环改为共用这条应用路径, server.hot_reload 关掉后真正停手。
  • 前端

    • 5 张分区卡片(服务与安全 / 供应商与模型 / 路由与熔断 / 日志与定价 / 下载代理)
      • 顶部「跳到」胶囊 + 每张卡右上与页面底部各一组保存按钮;改了「需重启」的键会亮 需重启 药丸。
    • 保存成功顶部出「已保存并生效」;失败出错误框且盘上文件不动。
  • 这一轮真正的坑(记一笔,别再踩)

    • 现象:/gateway-config 第一屏整块不渲染,其余屏正常;app.config.errorHandler 也不报错。
    • 真因:文案里写了 {"status":"ok"} —— vue-i18n 把 {...} 当占位符,这条编译不过 (Invalid token in placeholder),而文案是渲染时才编译的,于是"用到这条文案的整块界面直接空白"。 修法:字面量花括号写成 {'{'} / {'}'}(这条文案因此改用双引号 TS 字符串)。
    • 顺着补了 frontend/scripts/check-i18n.mjs(npm run check:i18n,已挂进 build 前置): 扫占位符语法 + 中英键对称 + 重复键 + 空文案,四类问题都在构建阶段拦下(自测能抓回上面那条)。
    • 另一个小坑:页面标题取 t('nav.menu' + route.name),路由 name 必须和 nav.ts 的 key 一致, 否则标题直接显示原始键名(本轮把 gatewayconfig 改回 gatewaycfg)。
    • 教训:界面"整块空白 + 控制台只有一条 Vue 报错"时,先查文案编译,别先去怀疑组件库的渲染机制。
  • 质量门 / 上线(2026-09-13 19:1x,老板批准)

    • 后端 151 passed / 0 failed(原 146 + 新增 5:视图↔yaml 往返零漂移、密钥不回显、自定义段/明文 token 不丢、 假值/坏值报字段名、权限矩阵 + 保存即生效)。
    • 前端 vue-tsc 0 错、check:svg / check:i18n 通过、vite build 通过。
    • 隔离实例(8899,配置走 /tmp 副本,生产 data/ 全程只读)真浏览器实测:5 屏全渲染、 「跳到」滚动生效(目标卡片 y 4221 → 62)、会话时长改成 45 保存 → 盘上文件立刻更新且生成 .bak(权限 600)、 页面出「已保存并生效」。
    • 上线:npm run build → 线上现役 index-T9rUvEqS.js / GatewayConfig-Cujt5GjO.js (旧 index-BMd-U-9_.js 已 404);supervisorctl restart api-gateway:api-gateway_00 → 新 pid 2102891(127.0.0.1:8808)—— 本轮有后端改动,重启踢掉所有网页会话,需重新登录。 随后小修一处文案({'{'}"status":"ok"{'}'} 里花括号写法之间多打了空格,渲染成 { "status":"ok" }, 与 /health 真实报文不符)→ 再 npm run build → 现役 index-CladK7BT.js / GatewayConfig-V1lLUX_x.js(旧 index-T9rUvEqS.js、GatewayConfig-Cujt5GjO.js 已 404); 只动前端,没有重启后端(pid 2102891 未动、网页会话不掉)。 用 vue-i18n 自己的运行时核过两份文案的渲染结果都是 {"status":"ok"}(无空格)。
    • 复核(全部实测):/healthz 200、/web/ 200 且 Cache-Control: no-cache、新 asset 200 / 旧 asset 404、 CSP 未放宽、GET|PUT /config 未登录 401(证明新端点已随重启上线)。 线上产物含 sec-server / sec-download 分区。 线上逐屏复核没做(当前管理员密码非默认值,小银不掌握、也不去试),面板的浏览器实测以隔离实例为准。
    • 收尾:隔离实例 8899 已 kill(线上 8808 未受影响),/tmp 残留与临时配置副本归档到 /root/.trash/<归档>/(含 MANIFEST.md),frontend/public/ 与 dist/ 无探针残留。
  • 追加一(同日 19:2x,老板「模型定价去掉」「左侧菜单上下间距缩短一点,让滚动条不要出现」)

    • 侧栏间距收紧(layouts/SideNav.vue):菜单项内边距 9px→7px(行高 36→32px)、项间距 2px→1px、 分隔线上下 10px→7px、.rail-inner 16px→14px、.brand 下边距 16px→12px。 实测(视口 720px):菜单区 500px → 427px,出滚动条的临界视口高 ~605px → ~538px。
    • 当轮还按字面把「网关配置」页里的模型定价块删了(prices / PriceRow / PUT 的 pricing.per_model 一起撤), i18n 中英各删 5 条。此改动已按追加二回退,见下(settings.py 的"只在视图带 pricing 时才覆盖"行为 当时验证过:面板保存不会清空 data/gateway.yaml 里的价格段)。
  • 追加二(同日 19:3x,老板「网关配置功能先不要删掉先隐藏起来,这块先不支持页面配置」)

    • 定价块原样恢复:模板整块、prices 状态、interface PriceRow、GET /config 填充、PUT /config 的 pricing: { per_model: perModel } 全部退回;i18n 中英各恢复 5 条(pricing / h_pricing / priceIn / priceOut / addPrice)+ tabLog / tabLogSub / gwConfigSub 复原 → check:i18n 中 667 / 英 667。 zh 五条取自归档 zh.ts.good 逐字原文;en 的 addPrice / priceIn / priceOut 三条因旧构建产物已删、 无留底,按中文对应重写(Add pricing / Input price / Output price),恢复页面时如有原稿可覆盖。
    • 整页隐藏(不删):新增开关 src/lib/features.ts 的 GATEWAY_CONFIG_ENABLED = false,一处控三处 —— ① lib/nav.ts 的侧栏/手机抽屉入口 ② views/Settings.vue 那颗跳转按钮 ③ router.ts 守卫: 手敲 #/gateway-config 会被送回 /dashboard。页面组件、路由定义、i18n、GET|PUT /config 全部保留 (懒加载 chunk 仍照常打包,恢复 = 把开关改 true)。
    • 质量门:vue-tsc 0 错、check:i18n 中 667 / 英 667、npm run build 通过。
    • 上线:纯前端,npm run build 覆盖 frontend/dist(dist 即线上目录),未重启后端(pid 2102891 未动、 网页会话不掉)。线上现役 index-71M4gDBC.js / GatewayConfig-DBW2jA7a.js / MainLayout-D8ZEF-hU.css(旧 index-CHZfJ5j7.js = 19:2x 那版已 404)。公网复核:主页现在指向 index-71M4gDBC.js、index.html 仍 no-cache、CSP 未放宽。
    • 隔离实例(8899;GATEWAY_CONFIG / GATEWAY_USERS / GATEWAY_HISTORY / GATEWAY_FEEDBACK 全指 /tmp, 生产 data/ 只读)真浏览器实测:侧栏 11 项、无「网关配置」;设置页无那颗跳转按钮; 手敲 #/gateway-config 落回 /dashboard。构建产物静态核对:定价块文案仍在(addPrice / h_pricing / 输入价 / 输出价 / list-edit 均能在产物里找到)→ 功能只是藏起来、没被删。
    • 收尾:隔离实例已 kill,两轮残留分别归档 /root/.trash/<归档>/ 与 /root/.trash/<归档>/(各含 MANIFEST.md)。
    • 备注:生产 data/users.json 在 19:29 有一次写入,不是本次验证造成(隔离实例的账号/配置/历史全走 /tmp), 看字段像线上侧的登录/建 Key 动作。
  • 追加三(同日 19:4x,老板「左侧菜单上下间距可以大一点」)

    • 上一版把行距压到 7px(行高 32px)是为了不出滚动条,老板觉得偏紧 → 改成随窗口高度自适应: 菜单项 padding: clamp(7px, 1.4vh, 11px) 10px、分隔线 margin: clamp(7px, 1.2vh, 13px) 8px (下限 7px/32px 与上一版一致、上限 11px/40px 比最初的 9px/36px 更松)。
    • 实测(隔离实例,视口 720px):行高 38.2px、菜单内容 468px / 可用 609px → 无滚动条; 推算"开始出滚动条"的窗口高从最初的 ~605px、上一版的 ~538px 降到 ~508px。
    • 上线:纯前端 npm run build 覆盖 frontend/dist(未重启后端,会话没掉)。线上现役 index-BV89HnWe.js / MainLayout-BOSEGVwr.css(index-BeKWQQGn.js、MainLayout-8X3ca3Qa.css 已 404)。
    • 收尾:残留归档 /root/.trash/<归档>/(含 MANIFEST.md)。

第二十二轮(2026-09-13)意见反馈 / 用户反馈 + 侧栏底部清理 + 处理进度 来源:老板三点 ——「侧栏菜单左下角那行去掉」「普通用户新增意见反馈,支持上传图片」 「管理员账号新增用户反馈菜单,内容是全部用户的反馈意见」;第二轮追加定稿 —— 「管理员只能看没法提,用户提完后可以查看处理进度,管理员处理反馈可以更新状态」。

  • 侧栏底部两行删除:SideNav.vue 的 .rail-foot(B · 素白蓝紫 / v2.4.0 · 控制台) 整块移除,连带删掉只服务于它的 version prop 与 MainLayout.vue 里的 version ref (/health 探针与顶栏连接小灯保留)。实测侧栏菜单到「设置」为止。
  • 两条菜单互斥,权限双向封闭:
    账号 菜单 说明
    普通账号 「意见反馈」(提 + 看自己的进度) 无「用户管理」「用户反馈」
    管理员 「用户反馈」(看全部 + 改进度) 无「意见反馈」,提交接口也 403
    双向都不只是 UI 约定:nav.ts 不显示 + 路由守卫兜住手敲地址
    (member 进 /feedback-inbox → 仪表盘;admin 进 /feedback → 收件箱),
    服务端 POST /feedback 对 admin 直接 403「管理员账号只处理反馈,不提交反馈」。
  • 处理进度(三档状态机):pending 待处理(提交即此态)→ doing 处理中 → done 已处理, 外加一条处理说明(≤500 字,可选)。管理员在收件箱每条右侧点「处理」→ 选状态 + 写说明 → 保存; 提交人刷新「我提交过的」就能看到状态徽标(.badge.o/p/g 橙/蓝/绿)、说明(左侧主题色竖线块) 和「更新于 …」(追加项后这块由「处理记录」时间线取代,见下方)。 status/note/updated 落 data/feedback.json, 重启不丢;老数据缺 status 字段按 pending 归一化(不会因未知状态白屏)。
  • 撤回(只能趁「待处理」):提交人在「我提交过的」里,仅 pending 的单子右侧出现「撤回」, 走二次确认(撤回=真删:条目 + data/feedback_media/ 下的图片文件一起删)。 管理员一动它(处理中/已处理)就不能撤 —— 否则管理员白干,且已处理的单子从提交人列表里 凭空消失也不合理。权限三层都把着:前端只对 pending 渲染按钮、DELETE /feedback/{id} 校验「本人 + 待处理」、管理员也不能替谁撤(收件箱本就没有删除入口)。 拒绝口径:非本人 403「只能撤回自己提交的反馈」、已进流程 400「管理员已开始处理,这条不能撤回了」、 已撤过/不存在 404。前端遇到 400 会把服务端原话弹出来并重拉列表(可能刚好被管理员接管了)。
  • 存储:正文 + 内嵌缩略图进 data/feedback.json,原图落 data/feedback_media/<fid>-<i>.<ext> (列表页零额外请求预览,点开才取原图)。上限:3 张/条、单张解码后 ≤700KB、正文 2000 字、 保留 500 条(超限丢最旧并连带删其图片文件)、坏 JSON 自动备份重建、无主图片启动时清理。 图片类型按解码后魔数判定,不信任客户端 MIME。
  • 只管会话:POST /feedback 只认网页会话,API Key 调用 403(与 /history 写接口同一口径)。
  • 前端新增 lib/feedback.ts、Feedback.vue(普通账号)、FeedbackInbox.vue(管理员,账号下拉
    • 进度下拉 + 关键词 + 10 条/页 + 缩略图弹大图)、FeedbackImages.vue,nav/router/图标 (bulb / inbox)/i18n(中英 527/527 键集对称)/vite 代理 /feedback。 (追加项再新增 FeedbackTimeline.vue 与 fbLog.* 四条文案,中英仍对称。)
  • 处理记录(本轮追加:每个环节都留痕):老板「处理的每个环节都要记录和展示」—— 每条反馈多一个 history 数组,只增不改,一条记录 = 谁(by)、什么时候(ts)、 从哪一档到哪一档(from → to)、留了什么说明(note)。
    • POST /feedback 落第 1 条(from 为空串 = 「提交」,by = 提交人自己); PATCH /feedback/{id} 每成功一次追加 1 条(by = 操作的管理员账号); 被拒的请求(400/403/404)不留下记录,记录只跟着成功变更走。
    • 同一档位重复改(如「处理中 → 处理中」只补说明)也记一条,from === to 时前端不画「← 来源」箭头。
    • 每条最多留 50 条(超出丢最旧,只影响展示);history 随 status/note/updated 一起落 data/feedback.json,重启不丢。
    • 老数据自动补记录:本轮之前提交、没有 history 的条目,加载时按现有字段补 「提交 → 待处理」;若已推进过,再补一条「待处理 → 现状态」(当时是谁点的已不可考,by 留空)。
    • 展示:新组件 FeedbackTimeline.vue,提交人与管理员看的是同一串记录(服务端原样下发), 竖线 + 状态色圆点 + 账号标签 + 时间,说明块沿用左侧主题色竖线;超过 4 条默认折叠成 最后 4 条(最新的处理动作最重要),带「展开全部 N 条 / 收起」。 「我提交过的」里原「更新于 …」的单行说明块被时间线取代(信息不再重复两处)。
  • 验证:隔离实例(8899 + vite dev 5199)真浏览器跑通闭环 —— member 带图提交 → admin 收件箱可见并弹大图 → 管理员改「处理中」+ 写说明 → member 端立刻看到状态与说明; curl 另验:admin 提交 403、member 改状态 403、非法状态 400、不存在 id 404、未登录 401。 窄屏 390×844 实测(同源 iframe 探针)两页均无横向溢出,进度徽标与「处理」按钮不挤爆。 质量门:vue-tsc 0 错、build 通过(check:svg 前置)、后端单测 146 passed / 0 failed (新增处理进度用例:状态非法 400 / 越权 403 / 落盘重载仍在 / 缺字段归一化; 处理记录用例:提交即有第 1 条且 by 是提交人 / 两次 PATCH 后 to 依次 pending→doing→done 且 by 是操作管理员 / 被拒请求不追加 / 老数据自动补记录 / 重载后记录仍在; 新增撤回用例:本人撤待处理 200 且图片文件被删 / 再撤 404 / 撤别人的 403 / 管理员替撤 403 / 处理中·已处理 400 / API Key 撤不动 403)。撤回部分在隔离实例复核过接口与真浏览器交互。
  • 上线(2026-09-13 18:4x,老板批准「补上说明后直接上线」):npm run build → 线上现役 index-b0LZHsJm.js / index-BCEpjaoj.css(旧 index-CDcUA_16.js 已 404); supervisorctl restart api-gateway:api-gateway_00 → pid 2055315(127.0.0.1:8808)—— 本轮有后端改动,重启会踢掉所有网页会话,需重新登录。(该次 pid 已被下方追加项的上线覆盖。) 追加项(老板 18:39「待处理的单子用户可以自己撤回」)代码与隔离实测完成后,老板 18:5x 批准上线: 再次 npm run build + supervisorctl restart → 现役 index-9Whl_Fn4.js(旧 index-b0LZHsJm.js 已 404)、 pid 2063248(127.0.0.1:8808)。复核:/web/ 引新 hash、index-9Whl_Fn4.js/index-BCEpjaoj.css 200、 线上产物含「撤回这条反馈?/ 撤回后这条反馈「…」会被删除 / 已撤回 / 管理员已开始处理的单子撤不了」、 DELETE /feedback/{id} 未登录 401(路由在)、6 条反馈路由全在、/healthz 200、CSP 与缓存头未变、 登录页正常渲染。重启同样踢掉了所有网页会话,需重新登录。 复核(全部实测):公网 /web/ 200 且引用新 hash、新 asset(含 Feedback-* / FeedbackInbox-*)全 200、 旧 index asset 404、/healthz 200、CSP 未放宽、index.html → no-cache、带 hash asset → immutable; 线上主 chunk 内含 memberOnly 守卫与 feedback-inbox 路由;线上产物含 「待处理 / 处理中 / 已处理 / 处理说明(提交人可见)/ 进度已更新 / 提交后在这里看处理进度」; 未登录打 /feedback 系列 5 个路由全部 401(PATCH 也在,证明新接口已随重启生效)。
  • 待老板刷新(Ctrl/Cmd+Shift+R)确认:侧栏底部两行没了、普通账号有「意见反馈」且能提图、 提完能看到进度、管理员只有「用户反馈」并能改进度。 追加项(老板「处理的每个环节都要记录和展示,改好后直接重启上线」)已上线: npm run build(先确认 frontend/public/ 无探针残留)→ 现役 index-BTllhoyi.js (旧 index-9Whl_Fn4.js 已 404;index-BCEpjaoj.css 哈希未变,本轮无样式改动); supervisorctl restart api-gateway:api-gateway_00 → pid 2073622(127.0.0.1:8808)—— 有后端改动,重启踢掉了所有网页会话,需重新登录。 复核(全部实测):公网 /web/ 200 且引用新 hash、index-BTllhoyi.js 与 FeedbackTimeline-CfkAgUmj.js / Feedback-DsePxU4t.js / FeedbackInbox-D1R_k-8C.js 全 200、 旧 index-9Whl_Fn4.js 404、/healthz 200、CSP 未放宽、index.html → no-cache; 线上产物含「处理记录 / 展开全部」;PATCH /feedback/{id} 与 GET /feedback/mine 未登录均 401 (路由已随重启生效)。生产 data/* 全程只读(并未往线上写测试反馈)。 收尾:隔离实例(8899 / vite dev 5199)已 kill,探针 gwmv23.html + 临时 vite 配置 gwcheck23.vite.config.mts 与 /tmp/gw23 已归档到 /root/.trash/<归档>/(含 MANIFEST.md),frontend/public/ 已清空、 dist 无探针残留。

第二十一轮(2026-09-13)顶栏「铃铛」删除 + 主题下拉点不开(tooltip 套在 dropdown 触发器里) 来源:老板 ——「右上角的通知图标是有功能的吗?…如果有用就保留,没用就去掉,然后主题点击没反应」。

两个都是真问题,先说结论:

  1. 铃铛是死图标:顶栏那个 <button class="icon-btn"><Icon name="bell"/></button> 没有 @click,唯一的行为是一句 tooltip「暂无新通知」——没有任何通知数据源。 按老板要求删掉(连同 top.noNotify 文案,中英各删 1 条,键集仍对称 482/482)。 顶栏控件从 4 个变 3 个:主题 / 刷新 / 账号。 bell 图标保留在 Icon.vue —— ApiKeys.vue 还在用它(密钥页提示)。
  2. 主题点了没反应=dropdown 触发器被 tooltip 包住了。原写法:
    <el-dropdown trigger="click" @command="onTheme">
      <el-tooltip :content="t('theme.choose')"><button class="icon-btn">…</button></el-tooltip>
      <template #dropdown>…</template>
    </el-dropdown>
    
    Element Plus 的 el-dropdown 用 ElOnlyChild 给默认槽的第一个节点挂点击事件; 第一个节点是 el-tooltip(它自己又渲染一层包装),于是事件挂在包装层上, 真正被点的 <button> 收不到 → 菜单永远不开。 实测证据(临时实例 + 真浏览器):DOM 里 .el-dropdown__popper 存在且文案完整 (A · 深空蓝 / B · 素白蓝紫 / C · 暖砂墨绿 / 跟随系统深色模式), 但 bounding_box() 为 None(不可见)——点了等于没点。 修法:tooltip 挪到 dropdown 外面:
    <el-tooltip :content="t('theme.choose')">
      <el-dropdown trigger="click" @command="onTheme"> <button class="icon-btn">…</button> … </el-dropdown>
    </el-tooltip>
    
    修完实测:点调色盘 → 菜单真的弹出(160×153 @ 顶栏下方)、 「A · 深空蓝」→ 全站变深色且侧栏标签同步为 A · 深空蓝,再点回 B · 素白蓝紫 正常; tooltip「主题外观」悬停照常显示。 顺带全库扫了一遍同类写法(每个 el-dropdown 触发器的第一个元素):只有这一处,无第二个。

窄屏回归(390×844 iframe 实测):手机顶栏 2 个图标(菜单 / 主题),点主题仍在 B → C → A 循环切换(本次实拍 B → C 生效);抽屉底部 4 张主题卡布局正常 (x=12…240、抽屉宽 252,.dt-card 各 51px,无溢出),当前主题卡高亮正确。 质量门:vue-tsc 0 错、build 通过、check:svg 通过(本轮未动后端,不涉后端单测)。 生产 dist 在本轮验证期间未被覆盖(构建先出到临时目录 /tmp,探针 html 也随构建产物一并归档)。

  • 上线(2026-09-13 18:2x,老板批准):npm run build → 线上现役 index-CDcUA_16.js (旧 index-C_MmjTC1.js 已 404)。index-BuS4X-hx.css 哈希没变(本轮没动样式,正常); Chat-* / Videos-* 的 JS 换了名但 CSS 没换 —— 它们 import 的 index chunk 文件名变了, 只是引用串跟着变(内容无关)。 本轮只动前端,没有重启后端:pid 1999293(127.0.0.1:8808)未动,网页会话不会被踢。 复核(全部实测):公网 /web/ 200 且引用新 hash、新 asset 全 200、旧 index/Chat asset 404、 /healthz 200、CSP 未放宽(default-src 'self' + frame-ancestors 'none' 照旧)、 index.html → no-cache、带 hash 的 asset → immutable 长缓存; 拉线上 index-CDcUA_16.js 核对:「主题外观」在、「暂无新通知」为 0 次 —— 铃铛确实下线了。 待老板刷新(Ctrl/Cmd+Shift+R)确认:顶栏只剩 主题 / 刷新 / 账号,点调色盘能弹出主题菜单。

第十九轮(2026-09-13)日志筛选「不生效」真因 + 视频任务卡版式重写 来源:老板两点 ——「视频的列表显示不协调,优化下」「日志筛选文字图像和视频不生效」。

  • 日志筛选「不生效」是两个独立真因,已用上一版构建(frontend/dist = 线上 index-Gg1BF2WV.js) 在临时实例上逐个复现:
    1. 类型胶囊与「失败」胶囊不是互斥的(只 toggle 自己那个 state)。点过「失败」之后 result=fail 一直亮着,再点「图像/视频」就叠加成「类型=视频 + 结果=失败」→ 必然 0 条; 胶囊上没有计数、空列表也没有任何提示,表现就是「点了没反应,筛选坏了」。 实测(旧构建):点[视频] 1 行 → 再点[失败] 0 行 → 失败亮着时点[对话] 仍是 0 行。 修复:互斥(点类型清「失败」,点「失败」清类型;要叠加仍可用「结果」下拉)
      • 每个胶囊带条数(全部/对话/图像/视频/失败各几条第 0.5 秒就知道)
      • 空结果提示写明「已加载 {n} 条」并给「清空筛选」按钮。
    2. 关键词搜索的 appliedKw 是普通 let,不是 ref —— 不参与响应式追踪, filtered 这个 computed 不会重算:点「搜索」后列表纹丝不动,要等下一次自动刷新 (5s 一轮)才顺带把关键词应用上,一会儿又变,看着就是「文字筛选不生效」。 修复:改 ref + 边打边筛(watch(kw);200 条以内开销可忽略),搜索按钮/回车保留。
  • 类型归类改由服务端给权威 kind:_access.add 全部 14 处调用点带 kind (chat / image / video / media),前端不再靠 path 子串猜(端点一改名就静默失效); 旧条目没有 kind 时仍回落路径判断。日志行 Type 徽标同理。
  • 视频任务卡版式重写(原版「不协调」的来源):旧卡是「小缩略图 + 5 行 key/value + 折叠栏 + 独占一行的按钮」= 228px 高,缩略图下方空出 140px;状态还在胶囊(上游英文 completed)和正文(「已生成」)里说了两遍。现在:左 16:9 缩略图 + 右三行紧凑信息 —— ① 标题(2 行截断)+ 状态胶囊(只留 已生成 / 生成失败 / 生成中… 短词) ② 摘要行(服务 · 耗时/等待 · 场景;失败时整行变红显示失败原因,原来是藏在折叠里的) ③ 底部任务号 + 下载视频 / 原始返回 按钮(原始返回由 el-collapse 改为内联展开)。 进度条只在「生成中」出现(完成后那条满格绿条纯粹是根分隔线),卡片 228px → 112~140px, 缩略图 148×84 与视频比例一致,垂直居中不再留空。
  • 窄屏(≤768px):缩略图改为撑满卡片高度(108 宽)+ object-fit: cover, 与图像页缩略图口径一致;不再是一张 61px 高的小图、上下各空 45px。
  • 验证:日志筛选在临时实例逐项实测(全部 6 / 对话 3 / 图像 2 / 视频 1 / 失败 1,点空关键词出 提示并能一键清空);视频卡桌面与 390 宽实测(7 张卡:常规 112/119px、长标题 140px、 窄屏 151~175px,无横向溢出);vue-tsc 0 错、vite build 通过、后端单测 137 passed / 0 failed。
  • 上线(2026-09-13 17:44,老板批准):npm run build → 线上现役 index-Yy0kGuVA.js / index-DKyqf84q.css / Logs-N__ABTKT.js / Videos-Bzh1nuOL.js + Videos-BVOcHXwL.css; supervisorctl restart api-gateway:api-gateway_00 → pid 1999293(127.0.0.1:8808)。 复核:公网 /web/ 200 且引用新 hash、新旧 asset 分别 200 / 404、/healthz 200、CSP 头未放宽; 拉线上产物实测含胶囊计数与空结果提示(Logs)、新版卡片结构(Videos)与窄屏缩略拉伸规则(Videos CSS)。 注意:重启会踢掉所有网页会话,需重新登录。

版本号与发布纪律(★ 硬性,2026-09-29 老板立)

1. 每次改动都要把版本号往上加

改动规模 版本号动作 例
小改动(修 bug、调样式、小优化) 加小版本号 2.4.0 → 2.4.1
较大改动 / 大版本 加大版本号 2.4.1 → 2.5.0

唯一权威定义处:app/main.py 的

VERSION = "2.4.0"     # ← 只改这一处

它已被 FastAPI(version=...)、GET /、GET /healthz、POST /auth/login 的 gateway_version 共用(第三十三轮收敛为单一常量)——不要再在别处硬编码版本号。

别混淆:frontend/package.json 的 "version": "0.1.0" 与设计稿脚本里的 v2.4.0 (design/design/v2/build.py、design/design/v3/agents.py)是独立的东西,不随 app 版本走。

2. 发布流程(改完照这个顺序走)

改代码 → 跑测试(python tests/test_gateway.py 或 bash scripts/ci_check.sh)
       → 纯前端:npm run build(dist 即线上目录)
         后端/代码:supervisorctl restart api-gateway:api-gateway_00
       → 真机验证(线上 healthz / 页面 / 接口)
       → git commit
       → 推 Gitea(scripts/push_gitea.sh,仓库 Jidekin/api-gateway 分支 main)

「只要上生产就必须推」 是既有硬性规矩:保持"线上跑着的代码 = 仓库里的代码"。凡是重启上线(后端 restart)或 npm run build 覆盖 frontend/dist 的代码改动,验证通过后都必须推 Gitea; 纯注释/配置靠 hot_reload 生效的也照推。落地脚本 scripts/push_gitea.sh:日常免密—— 什么都不用带,它自己按「环境变量 GITEA_TOKEN → 参数 → GITEA_PASS → 本机文件 ~/.gitea_token(600)」 的顺序取凭据(token 是 2026-10-12 建的 Gitea API token,scope write:repository); 凭据只一次性内嵌进本次推送 URL,不写 .git/config、也不内置进仓库任何文件; 退出码 2=没凭据 / 3=工作区不干净 / 4=推送后远端≠本地 / 5=.git/config 出现明文。 仓库 https://git.wangjinding.com/Jidekin/api-gateway.git、分支 main (remote 名就叫 gitea)。三个项目分支已统一为 main (2026-10-12:api-gateway 原 master 改名 main,Gitea 默认分支同步改、旧 master 分支删除)。

测试

# 单元测试(mock 供应商,不依赖真实网络,覆盖配置/协议线/熔断/适配器/端点)
python tests/test_gateway.py
# 或
pytest tests/ -q

全量网关冒烟测试见 smoke_test.py(需网关已启动 + 真实 key)。

# 冒烟:健康 / 模型列表 / chat / batch / 错误格式(网关未起或无 key 时优雅 SKIP)
python smoke_test.py --url http://127.0.0.1:8808

# 活体检查:真实上游(Agnes / OpenCode Go / Dots AI)端到端行为校验,含三线直传与跨线 400、
# 流式 SSE、413、CORS 预检、图像生成等
python live_check.py --url http://127.0.0.1:8808

一行跑完所有门禁(单测 + i18n/SVG 文案体检 + 前端类型检查 + 语法编译):bash scripts/ci_check.sh

当前状态:单元测试 179 passed / 0 failed(python tests/test_gateway.py,不需要 pytest);冒烟 5/5 PASS;活体检查 14 PASS / 0 FAIL / 0 WARN。

模型清单每日同步(scripts/sync_models.py)

把网关的模型清单和上游官方文档对齐,避免文档新增 / 下线 / 改价之后配置慢慢走样。

# 只报告(默认,不写盘):退出码 0=无漂移 / 1=有漂移 / 2=抓取或解析失败
python scripts/sync_models.py
# 真落盘同步(新增补进去 / 下线删掉 / 价格与免费标记就地更新),并把报告追加到日志
python scripts/sync_models.py --apply --log logs/model-sync.log
  • 数据源:OpenCode Go 官方文档 https://opencode.ai/v2/docs/console/go/(Endpoints 表 + 价格表)、 Agnes 定价页 https://www.agnes-ai.cn/zh-Hans/docs/pricing(取「现价」列,不是划掉的刊例价)。
  • 写盘是文本级增删改:只动该动的行,data/gateway.yaml 里逐条实测的手写注释不会被冲掉; 走网关自带的 write_config(备份 + 原子替换 + 权限 600),落盘后回读校验,不通过就中止、不写盘。
  • 边界:协议线只加不砍(文档给的新线补上,逐条实测出来的线不动);PROTECTED 名单与被别名 / media 引用的模型 id 永不自动删(官方文档表收录有滞后,实测 deepseek-flash / omen-alpha 上游在服务、文档表还没补),只在报告里点名。
  • 免费标注(2026-09-24 老板要求:Agnes 也要标):配置里 free: true → 「免费」标签, 再加 free_limited: true → 「限时免费」标签;/v1/models 带出这两个字段,前端「模型与供应商」 页把标签放在模型名后面(左右间距统一交给行内 flex gap,别再加 margin,否则 14px vs 8px 不齐)。 判定源是官方措辞:OpenCode 价格表 Input/Output = Free;Agnes 定价页「### 当前优惠」小节里 的「当前(均)免费」→ 免费、「限时免费」→ 限时。注意 Agnes 视频 agnes-video-2.5 那条 bullet 里的「输入图片前 5 张免费」是计费公式的免费额度、不算模型免费,所以判定按 bullet 切块 + 只认严格措辞,且只认反引号里的完整 id(agnes-video-2.5 是 agnes-video-2.5-flash 的 子串,字符串包含会串味)。优惠到期 / 官方改口径时,同步会自动把标注整行撤掉。
  • 视频默认模型 agnes.media.video_model_name 不自动换:文档对视频模型没有「哪个最新 / 最好」的 机器可读标记(agnes-video-v2.0 当前免费、agnes-video-2.5 按输出分辨率计费、agnes-video-2.5-flash 限时免费),自动切会直接改变线上视频行为。脚本只做两件事:保证它不被自动删(media 引用的 id 受保护), 并在报告里列出文档的视频清单当候选(含 ✓ 文档里还在 / ✗ 已下线 标记)。换默认由人点模型名,改一行配置。
  • 定时:QwenPaw cron 每天 08:00(Asia/Shanghai)跑 --apply,简报投到控制台,报告同时追加到 logs/model-sync.log。

备注

  • 三家均为 OpenAI 兼容协议,统一 OpenAICompatAdapter,通过 base_url + media 区分
  • Agnes 图像/视频模型 ID 用点号(2.5),不是 25
  • 配置文件路径:data/gateway.yaml(唯一配置;GATEWAY_CONFIG 可覆盖)
  • hot_reload: true 时改 yaml 自动重载(默认开)
  • 限流为进程内令牌桶(per-key/per-route/per-provider QPS),高并发生产建议前置 Nginx 或加 Redis
  • 指标/日志为进程内内存态,重启清零;生产建议接 Prometheus(/metrics/prometheus)+ 文件持久化
  • Windows 无 make 时可手动执行 Makefile 里的对应命令
S
Description
No description provided
Readme
21 MiB
0 Stars 1 Watchers 0 Forks
Languages
Python 62.3%
Vue 23.1%
TypeScript 9.3%
CSS 2.3%
HTML 1.9%
Other 1.1%