v0.3.12

新增

渠道自动禁用可整体关闭，且默认关闭

• 全局：新增热配置 gateway.auto_disable_upstreams，默认 false —— 默认不自动禁用任何渠道，失败只记日志并照常重试 / 故障转移；需要熔断的部署到「系统设置 → 路由策略」里手动打开，改完即时生效。
• 渠道级：上游 extra.auto_disable=false（渠道表单「运行」区的「自动禁用」开关，列表显示「不自动禁用」标签），只对该渠道生效。
• 关闭后的语义 = 完全不熔断：不计连续失败、不冷却、不半开探活，不写 disabled_by='auto' / cooldown_until，候选链不再因熔断跳过该渠道。手动禁用仍优先级最高，凭证失效隔离（token 失效跳过 5 分钟）不受影响。
• 关掉开关时立即解除历史自动禁用状态：关闭全局会全量解除，关闭单个渠道只解除该渠道，渠道随即回到候选池。

内存相关参数改为用户可配置（默认值全部不变）

• gateway.max_body_mb（默认 100 MiB，系统设置「请求处理」）：单请求体上限。请求体整体读入内存后解析，调低可压低大 body（多图 base64）请求的内存峰值，代价是超大请求返回 413。仅启动时生效。
• gateway.argon2_memory_kib（默认 19456 KiB = 19 MiB，系统设置「流量控制」）：管理员密码 argon2 哈希的内存成本，即时生效，但只作用于新生成的哈希 —— 调低后需改一次密码才见效（登录校验按库里哈希自带的参数分配）。范围 8192–1048576。
• database.max_connections（默认 16，系统设置「日志与审计」）：PostgreSQL 连接池上限。启动类键，保存后下次启动生效；优先级 env NEXTAPI_DB_MAX_CONNECTIONS > UI > YAML。

本地构建镜像的实测对照（16 核宿主机、全新 PostgreSQL 数据卷，容器口径）：

场景	默认配置	调优（argon2 8 MiB / 请求体 16 MiB / 连接池 8）
空载	3.3 MiB	3.2 MiB
登录一次	22.5 MiB	3.3 MiB
登录三次	60.6 MiB	19.3 MiB
后台访问后	60.7 MiB	27.3 MiB

登录后内存偏高的原因是 argon2 的工作内存被 glibc 留在堆里（默认一次 19 MiB），调低该值即可显著降低常驻。

修复

• 请求体超限的 413 文案此前写死「请求体超过大小限制 100MiB」，现跟随生效的 gateway.max_body_mb 输出（如「…16 MiB」）。
• README 重写，并新增「性能与资源占用」一节（默认与调优两组实测数据、口径说明、启动耗时、镜像与空库体积）。
• 启动类配置键现在接受数字（此前只收字符串），数值键做整数与范围校验、落库仍存字符串；设置页数值控件正确回显字符串值。

验证

• 单测 453 → 457；cargo fmt --check、clippy（0 告警）、vue-tsc --noEmit、npm run build（含 check-api-paths）全绿。
• 端到端（真实进程 + 临时库）：UI 保存连接池 3 后并发 10 个请求，PostgreSQL 连接数停在 3；改密后库里哈希参数为 m=8192,t=2,p=1；上限 1 MiB 时 2 MiB 请求返回 413 请求体超过大小限制 1 MiB。
• 本地构建镜像按默认 / 调优两套配置复测内存（数据见上表与 README）。

镜像：ghcr.io/snnh/nextapi:0.3.12（多架构 amd64 / arm64，同时打 0.3 与 latest）

升级：docker compose pull && docker compose up -d

NextAPI v0.3.11

NextAPI v0.3.11

自托管 LLM 网关：四协议互转 · 多上游聚合路由 · 日志与成本统计 · 内嵌管理后台。单二进制（前端内嵌）部署，PostgreSQL 存储。

本说明描述当前版本的完整能力（已合并历次变更的最终形态）。

---

网关核心

• 四协议互转：OpenAI Chat Completions / OpenAI Responses / Anthropic Messages / Gemini 四者互转。透传优先（SSE 边转发边改写），上游不支持入口协议时按内部 IR 自动转换；转换后消息为空直接 fail-fast 返回 400（附降级线索），不把必然失败的请求发往上游。
• 聚合路由：模型通配匹配、优先级分组 + 加权随机、重试与故障转移、熔断（自动禁用 + 冷却 + 半开探活，冷却状态重启保留）。
• 鉴权与限额：网关 Key（SHA-256 哈希存储）、每 Key RPM/TPM 滑窗、token / 成本配额上限（fail-closed）。
• 模型同步：按上游协议拉取模型目录并对账托管路由；上游无目录接口时可手动批量输入模型 ID 生成路由。
• 上游凭证失效处理（全渠道通用）：识别（流式鉴权错误与 unary 401 两种形态都覆盖，模型门控类错误不误判）→ 隔离（冷却期内摘出候选，成功或换凭证自动解除）→ 可见（后台列表标签与详情）→ 恢复（一键重新授权）。对外统一回 502 upstream_auth_failed。
• Codex 渠道：粘贴 auth.json 接入，临期自动刷新 + 轮换回写；WebSocket 传输（默认 auto：WS 优先、失败回落 HTTP，另可强制 ws/http）；官方客户端指纹模拟（出站补齐官方形态请求头与请求体字段，入站真实值与用户覆盖优先）；支持服务端上下文压缩端点 POST /v1/responses/compact 直接转发。
• Devin 渠道：以 CLI 形式接入 Devin 官方协议并对内转发为标准接口；管理后台内置 PKCE 无头授权（开始授权 → 浏览器授权 → 粘贴授权码兑换凭证）；CLI 环境模拟默认开启（官方头提示词按模型重渲染、会话首条注入环境块，模板与变量可配置、可被请求头或 metadata 覆盖）；思维链与正文分别映射为 reasoning 与 output_text 事件。
• 图片生成：统一入口覆盖 OpenAI / Gemini / Dashscope 三种图片 API 形态（含异步任务的轮询与计费闭环）。

日志与统计

• 明细日志：30 天声明式分区（手动整分区清理，支持 dry-run 预览：截止时间、分区列表、行数、Token 与成本合计）；异步批量写库（有界队列 + WAL 兜底，幂等重放）；游标（keyset）浏览，深页分页不退化；详情按排障顺序分组；失败日志回填实际上游与降级标记，调试模式覆盖失败路径。
• 统计报表：Token 采用含缓存全量口径（输入未缓存 + 输出 + 缓存命中 + 缓存写入），与配额口径一致；提供缓存命中 Token 与命中率（输入侧口径）；趋势图支持请求数 / Token / 缓存命中 / 命中率 / 成本五种指标；维度明细与 CSV 导出含缓存列；模型排行（按总 Token / 请求数 / 成本 / 缓存命中 / 错误数排序，Top-N，点击模型名钻取到日志页）。
• 可观测：Prometheus /metrics（管理员鉴权，Token 计数器与报表同口径）；顶栏系统状态徽标（后端 / 数据库 / 异常上游 / 日志队列 / WAL / 媒体待回联）。

计价

• 双币种（CNY/USD）分段计价（按上下文长度、星期、时段分段），只统计不扣费；汇率支持手动与自动拉取（含内置兜底）。
• 计价模型名跟随上游实际模型名，路由改写模型名后不会漏计价；日志展示「入口名 → 上游名」。
• 价格表 XML / JSON 导入导出（XML 为可读缩进格式，导出文件可原样回传；支持本地文件导入）；定价页支持按「供应商 + 模型」分组与「按模型定价」一屏配置四种价格；参考定价一键填充；管理端可查未定价模型。

管理后台

• 内嵌 Vue 3 控制台九个页面（登录 / 仪表盘 / 密钥 / 上游 / 路由 / 模型 / 价格 / 日志 / 统计 / 系统设置），随二进制同源部署，支持任意子路径部署无需重新构建；提供反向代理诊断面板。
• 供应商预设一键接入（含国内主流平台与 OAuth 形态渠道），接入向导三步完成并可即时同步模型、为新模型批量建路由；API Key 创建/轮换后展示网关地址与调用示例。
• 安全：单管理员 + 可选 TOTP 二步验证；登录防爆破；登录有效期可配置（热参数）；敏感字段（上游 Key / OAuth token / 代理密码 / JWT 密钥）AES-256-GCM 落库、展示一律掩码；上游 Key 查看需密码二次验证（启用 TOTP 时还需动态码）并写审计。
• 易用性：高风险操作统一二次确认与防误触；表单内联校验与脏表单保护；列表搜索/分页；日志筛选同步 URL；仪表盘错误态与重试；移动端响应式（窄屏折叠次要列、操作收为下拉）。

安全与部署

• SSRF 防护（私网段拦截 + DNS 钉住）、请求体上限、受控下载流式限长。
• 单 Docker 镜像（前端内嵌）+ docker-compose（含 PostgreSQL）；启动自动迁移；系统设置热加载（UI 优先于配置文件）。
• GitHub 更新检查；多架构镜像（amd64 / arm64）随版本标签自动发布。

⚠️ 升级注意（Breaking）

• 统计 Token 口径：/api/stats/* 的总 Token 为含缓存全量（此前只计输入未缓存 + 输出）；Prometheus Token 计数器同步调整，基于该指标做阈值或环比的看板需重新校准。
• 默认监听端口为 3220（容器部署需映射 3220:3220；可用环境变量或配置回退旧端口）。
• Token 口径归一：日志与统计中的「输入 token」为未命中缓存的输入（缓存单独计列），修复了缓存 token 被重复计价与重复计配额的问题；历史数据不回填，上游原始数值保留在日志原始记录中。

升级方式

docker compose pull && docker compose up -d

升级前建议备份数据库；迁移在启动时自动执行（本次含汇总表补列与历史回填）。