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

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