很多做模型接入的朋友迟早会遇到同一类问题公司里买了火山方舟的按量计费额度豆包、DeepSeek 这些模型确实好用可一旦要分给多个项目组、多个机器人、多个后端服务共用就立刻乱成一团——有人拿着 Key 到处拷账单分不清是哪条业务线花的某个子模块超量了还会拖垮整个账号。这个问题的解法就是标题里那套组合new-api 做统一网关sub2api 处理订阅转 API火山方舟承担模型与计费。简单说new-api 把火山方舟的按量 Key 收进来变成一条 OpenAI 兼容的公共 API 入口向下分发子令牌sub2api 则负责把只有订阅形态的额度转成标准 API让 new-api 也能納入管理。这套方案适合三类人要给团队发 API Key 的后端负责人、跑自动化任务和 Agent 的个人开发者、以及想对多个模型统一计费和管理的中小型团队。下面我直接把从部署到排障的完整过程展开包括我实测下来最容易忽视的细节和几个高频报错的根因。1. 先弄清楚三件事的分工统一网关、订阅转换与模型平台在动手部署之前我建议先花五分钟理解这套架构里的三个角色分别承担什么因为后面所有配置项的取舍都来自这里。1.1 new-api不止是API 转发而是一套权限与计费体系new-api 是一款开源的多模型 API 管理网关核心能力是把不同厂商的模型渠道收拢成一个入口对外提供标准的 OpenAI 兼容接口。类似开源项目 one-api 的增强版它在渠道管理、令牌生命周期、分组配额、模型定价这几个维度上做得更细。在实际使用里它解决的最痛问题有三个。第一是密钥安全不用再把火山方舟的原始 Key 发给每个开发而是生成多个带前缀的子令牌比如sk-abcdef1234。子令牌可以在 new-api 后台随时吊销某个实习生把 Key 贴到公开仓库你只需要把那一个令牌删掉不影响主渠道。第二是成本归因每个令牌挂在一个分组下分组有自己的倍率和余额月底拉日志就能看到哪个组花了多少钱。第三是协议统一new-api 对外暴露的是 OpenAI 兼容的/v1/chat/completions端点下游无论是 Dify、Chatbox、Codex CLI 还是自研 Python 脚本都按同一个格式接入不需要为每家模型厂商分别适配。1.2 sub2api为什么已经统一了还需要一层转换这里有个前置问题你手里的模型访问凭证不一定是API Key形态。有些渠道、有些额度包、有些第三方聚合服务给你的是一个订阅串sub token它可能是一长串带特定前缀的字符串也可能绑定了固定的 Base URL 和套餐剩余量而不是标准的 OpenAPI 凭据。直接把它填进 new-api 的标准渠道字段通常会失败因为 new-api 渠道要求的是可调用的 API Key Base URL。sub2api 就是解决这个中间层问题的。它把订阅串本地转换成一个 OpenAI 兼容 API 服务让你在http://127.0.0.1:某个端口上得到一个标准接口这个接口背后消费的是订阅额度。转换完成之后new-api 再把这个本地接口当成普通渠道加入网关订阅额度就被纳入了统一的令牌、分组和计费体系。所以这套组合的完整链路是火山方舟按量计费 Key │ ▼ [sub2api 转换层]仅当持有订阅形态额度时需要 │ ▼ new-api 统一网关渠道 / 模型 / 令牌 / 分组 / 计费 │ ▼ 下游应用Chatbox、Dify、Codex CLI、自研脚本1.3 火山方舟在其中的角色与按量计费的前提火山方舟是火山引擎的大模型服务平台托管了豆包系列以及 DeepSeek 等开源模型的推理服务提供 OpenAI 兼容接口。它在这套架构里是真正的模型和账单来源。按量计费模式的特殊之处在于费用发生在模型平台侧而配额发生在网关侧。如果团队任何一个人绕过网关直接调用火山方舟这笔费用就从网关的统计里凭空消失月底对账必然对不上。所以使用这套组合的一个前提纪律是所有请求必须从 new-api 入口走原始渠道 Key 只配置在网关里不发给任何人。想清楚了这个边界后面配置时就会自然知道哪些字段该藏、哪些令牌该发。2. 接入火山方舟前必须确认的四件事很多人在 new-api 里添加火山方舟渠道失败并不是配置步骤错了而是前置信息没确认好。这里我把接入前必须弄清楚的细节列出来照着逐项核对后面基本一次过。2.1 开通服务与获取 API Key首先要有火山引擎账号然后在控制台找到**方舟Ark**服务开通大模型推理能力。获取 API Key 的入口通常在API Key 管理里创建后你会得到一串以sk-开头的字符串。注意保存完整控制台不会二次展示完整 Key。这里有一个容易被忽略的坑火山方舟有两种鉴权方式一种是直接用 API Key 作为 Bearer Token另一种是基于 AK/SK 的签名鉴权。new-api 的火山方舟渠道一般使用的是前一种也就是把 API Key 直接填进渠道的密钥字段。如果你在火山控制台看到的是一对 AK/SK别搞混了——那是用来调用其他火山引擎服务的签名凭证不是模型接口的 API Key。2.2 模型 ID 的两种形态底座模型与推理接入点火山方舟的模型标识与 OpenAI 不太一样。你需要在控制台中找到模型列表豆包系列通常有类似doubao-seed-1-6-250615这样的模型 ID。另外如果你创建过推理接入点那么模型 ID 会是ep-开头的接入点 ID例如ep-20240516xxxx-abcde。在 new-api 渠道配置里模型名称填什么决定了用户请求时写什么。我的建议是模型 ID 填稳定的底座模型名同时在 new-api 的模型映射里给它一个更短、更统一的别名比如把doubao-seed-1-6-250615映射成doubao-seed。这样下游应用的代码里只出现一个稳定别名火山方舟那边即使调整了版本号你只需要改映射表下游不用动。2.3 Base URL 和接口兼容性火山方舟的 OpenAI 兼容接口 Base URL 是https://ark.cn-beijing.volces.com/api/v3。注意v3不能漏。填入 new-api 渠道时不要在末尾多加斜杠也不要写成完整的/v1/chat/completions路径——网关会自动拼接。接口兼容性方面火山方舟支持/chat/completions和/embeddings但部分高级参数可能不支持比如logprobs。如果你的下游应用依赖这些高阶参数建议在接入前先用 curl 实测一遍免得部署完才发现参数传不透。2.4 按量计费的计费口径与最小单位按量计费模式下费用按输入 token 输出 token积累不过不同模型的计费单价差异很大有的模型还区分命中缓存和未命中的输入价格。进入 new-api 配置模型定价之前先去火山方舟的计费页面确认三个数据项目需要确认的内容输入单价每百万 token 多少元是否区分缓存命中价格输出单价每百万 token 多少元计费粒度是否按 token 数四舍五入到千位确认后把这些单价填入 new-api 渠道的模型价格里。注意 new-api 的价格单位通常是每百万 token 的美元/元换算后的数值务必统一币种和基准否则网页显示的价格和实际账单会差出一个汇率。3. new-api 部署与渠道、令牌配置全流程基础信息齐了就可以实操了。我以 Docker Compose 方式为例这是目前最省心的部署路径升级维护都方便。3.1 用 Docker Compose 快速部署网关新建一个目录写一份最小的docker-compose.ymlservices: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - 3000:3000 volumes: - ./data:/data environment: - TZAsia/Shanghai - SQL_DSN # 默认使用内置 SQLite生产建议改 MySQL - SESSION_SECRETreplace_with_a_long_random_string这里两个环境变量值得留意。TZAsia/Shanghai影响日志和账单的时间口径如果你和火山方舟账单按北京时间核对这个必须设。SESSION_SECRET用于登录会话加密不设置或者太短重启后用户登录状态会失效生产环境建议填一个 64 位随机字符串。启动后访问http://localhost:3000第一次打开会引导你创建管理员账号。接下来进入后台先别急着配渠道去设置里把系统名称、显示余额、用户注册等选项按团队需要调整。尤其是允许用户注册选项默认如果开着公网部署后任何人都可以来注册白嫖额度务必改成仅管理员创建用户或关闭注册。示例启动命令docker compose up -d docker compose logs -f new-api看到日志输出监听端口正常后后台就可以登录了。3.2 添加火山方舟渠道型号、密钥与模型映射进入渠道页面新建渠道。渠道类型选择火山方舟VolcEngine Ark然后填写参数字段填写内容渠道名称建议写volc-ark-按量主账号之类方便月底识别密钥粘贴火山方舟的sk-API KeyAPI 地址Base URLhttps://ark.cn-beijing.volces.com/api/v3模型先填入你确认好的模型 ID比如doubao-seed-1-6-250615模型映射按需设置别名例如doubao-seed - doubao-seed-1-6-250615启用勾选提交后点击测试按钮。如果返回正常说明渠道通了。如果报 401优先怀疑密钥复制不完整或选择的渠道类型不对如果报 404大概率是 Base URL 路径不对尤其是少了v3。模型映射这个功能我多说一句。它的正向作用前面讲了——为客户提供稳定别名反向映射也很有用用户请求里写doubao-seed网关自动翻译成火山方舟的完整模型 ID。当火山方舟某天把底座模型升级成doubao-seed-1-6-250716你只需要在映射表改目标 ID而下游请求完全不用变更。3.3 创建令牌与分组给下游和团队成员发 Key渠道配好只是第一步真正给人和程序用的是令牌。进入令牌页面创建一个新令牌选定分组、设置过期时间和额度上限。这里有几个实践建议给每个下游应用单独建一个令牌比如chatbox-prod、dify-worker、codex-cli。出现问题可以精准吊销不误伤其他服务。给每个成员单独建令牌额度上限设为该成员本月预算。他超了额度网关会自动拒绝请求而不是账单爆了才发现。分组按环境或团队划分如prod、dev、external。每个分组设置不同的倍率比如外部合作方倍率设为 2内部研发设为 1。创建完成后new-api 会给一个完整令牌样子是sk-开头的一长串。这个字符串只显示一次务必马上保存。下游调用示例curl http://localhost:3000/v1/chat/completions \ -H Authorization: Bearer sk-your-new-api-token \ -H Content-Type: application/json \ -d { model: doubao-seed, messages: [{role: user, content: 你好}] }3.4 校验连通性用会话级请求验证全链路很多人在渠道测试通过后就认为万事大吉结果下游客户端接入时报错。问题往往出在三个地方下游把 Base URL 写成了http://localhost:3000/v1/chat/completions多了完整路径、model参数用了不存在的别名、或者 Bearer Token 填成了渠道密钥而不是令牌。我建议走一遍最原始的全链路校验先在 new-api 后台完成渠道测试然后用 curl 带令牌调一次确认 200 响应后再接入 Chatbox 或 Dify 这类客户端。上面那段 curl 就是标准模板第一个请求直接决定后面排查的走向——如果 curl 通而客户端不通问题一定在客户端的 Base URL 和模型名配置。4. 什么时候要上 sub2api订阅转 API 的实际用法接下来是容易让人困惑的 sub2api 部分。先强调一个判断标准如果火山方舟给你的是标准 API Key完全可以跳过 sub2api。只有当你的额度是订阅形态或者你的上游只能提供一个订阅串而你希望把它变成可控、可分发的 API 时才需要这一层转换。4.1 订阅与 API 的形态差异所谓订阅形态常见于这类场景你购买了一个聚合模型服务的月度订阅服务商给你一个订阅链接或订阅令牌它的特征是套餐 用量上限 到期时间。API 形态则是Key Base URL 按量扣费。两者的核心差别在于维度API Key 形态订阅形态鉴权Bearer Token订阅串可能还需附带独立 Base URL计费按 token 用量结算套餐额度到期重置或耗尽终止下游接入标准 OpenAI 格式直接可用往往需要转换层才能变成标准接口sub2api 的价值就是把第二列转成第一列的样子它读取订阅串本地起一个标准 OpenAI 兼容服务下游看到的是一个普通 API。这样订阅额度背后的特殊协议、鉴权方式、套餐规则都被封装在转换层里对 new-api 和下游完全透明。4.2 sub2api 的工作原理一个本地转换进程sub2api 本质上是一个跑在服务器上的服务进程。它接收两个核心输入订阅串和服务端口。启动后它会监听类似0.0.0.0:8080的端口并暴露/v1/chat/completions等 OpenAI 兼容端点。当请求进来时sub2api 负责三件事一是把 OpenAI 格式的请求转成上游订阅服务能识别的协议二是带着订阅串向上游发起真实模型调用三是把上游返回的流式/非流式响应还原成 OpenAI 格式。等到订阅套餐额度耗尽sub2api 会返回 429 或 401 让调用方感知而不是让你在应用里处理一堆订阅特有的错误码。部署方面如果你拿到的 sub2api 是 Docker 镜像通常一行命令就能起服务docker run -d \ --name sub2api \ -e SUB_TOKEN你持有的订阅串 \ -p 8080:8080 \ your-sub2api-image具体镜像名和环境变量要以你实际使用的 sub2api 项目 README 为准不同实现有差异但架构思路是一致的一个进程、一个端口、一个订阅串对外提供 OpenAI 兼容 API。4.3 与 new-api 的两种集成方式sub2api 转换出的本地 API 要怎么并入 new-api取决于你的网络拓扑和令牌策略。第一种方式是直接作为 new-api 的渠道。在 new-api 中新建渠道渠道类型选 OpenAI 兼容Base URL 填http://host.docker.internal:8080或http://127.0.0.1:8080取决于 new-api 容器与 sub2api 进程是否在同一台宿主机密钥填一个任意占位符即可因为鉴权已经被 sub2api 接管。模型名填订阅套餐对应的模型范围随后 new-api 就会像调度火山方舟一样调度这个订阅通道。第二种方式是作为普通上游单独暴露。如果你不想让 new-api 参与这部分流量可以直接把http://127.0.0.1:8080发给自己的脚本用。但这样一来调度、计量、令牌管理都脱离了网关等于重新引入混乱所以我一般不建议这么做。我的实际偏好是第一种。唯一要注意的是容器网络模式new-api 跑在容器里sub2api 跑在宿主机时容器内不能直接用127.0.0.1访问宿主机得用宿主机在 Docker 网络中的网关地址如果用network_mode: host启动 new-api那就没有这个问题。4.4 订阅转换层的典型报错与原因我在接入过程中见过几类报错集中提一下。unexpected status 401 unauthorized: incorrect api key provided是最常见的。这个报错出现在 sub2api 向上游发起请求时说明它读取的订阅串或令牌已经失效、过期或者环境变量根本没传进去。注意如果你自己的 new-api 令牌也是sk-开头别把二者搞混——sub2api 的报错里带上游服务商返回的 key 片段往往能快速定位。配置错误: claude provider 缺少 base_url 配置这类报错我曾经在 sub2api 依赖了 Claude provider 支持但没填 Base URL 时遇到。很多转换层为了兼容多模型会内置多个 provider 模板如果你订阅的套餐用的是 Claude 协议而配置文件里没有对应 provider 的 Base URL就会出现这个 400。解法是找到 sub2api 的配置文件补上对应 provider 的 Base URL 字段然后重启服务。订阅转 API 层稳定之后它的故障对外表现为 new-api 渠道的连续性体验问题。因为订阅额度不像按量 API 那样细粒度和可靠我一般会把这类渠道加权重或者单独分组避免它影响核心生产流量。5. 按量计费的钱怎么管额度、账单与预警按量计费的好处是不用买资源包、按实际用量结算坏处是费用账单天然滞后等账单出来再发现异常往往已经跑了好几天。我的经验是建立三层防线。5.1 火山方舟侧的成本确认首先火山方舟控制台能看到按模型分组的用量明细包括输入 token、输出 token、缓存命中 token 和对应金额。这里建议确认一个关键指标请求量最大的模型是哪个因为按量计费中 90% 的成本通常来自一个主力模型。对于生产项目我会每周从控制台导出一份用量明细按模型维度看趋势。如果某个模型 token 量突然翻倍先确认是不是上线了新功能如果不是去看看 new-api 日志里谁在反复调用——多半是有服务在重试循环。5.2 new-api 侧的计费模型new-api 的计费与上游账单是两套体系它内部通过模型价格 分组倍率 渠道倍率计算消耗的用户额度。关键在于new-api 里的额度是虚拟额度不代表真实人民币只有当你把模型价格和维护倍率设置精确它才能近似真实成本。具体到火山方舟按量计费我在渠道里维护模型价格时会以火山控制台页面公示的单价为准。以豆包某个模型为例假设输入和输出单价分别为每百万 token 若干元我在 new-api 渠道的模型列表里填入换算后的输入价和输出价并保持币种一致。5.3 做一次实际对账从日志提取 token 与账单核对对账步骤听起来繁重其实按以下流程走十分钟内能完成在火山方舟控制台导出上一自然日或上周的用量明细记录各模型的输入、输出 token 数。在 new-api 日志页面筛选对应时间范围和对应渠道的日志记录网关记录的 prompt_tokens 和 completion_tokens。对比两边数字。因为 new-api 会做模型映射和可能的请求改写两边 token 数存在少量差异是正常的但如果同一个模型的 token 数差出 10% 以上就要排查是否有请求从网关绕过或者 new-api 侧有多渠道同时为该模型提供服务导致统计分散。我遇到过一种特殊情况同一个模型同时配置了火山方舟按量渠道和 sub2api 订阅渠道两边都在服务请求导致火山方舟账单低、new-api 日志高。这时候需要在渠道上做好流量分配让同一个模型只走同一个上游。5.4 限额与预警的三道防线第一道防线在火山方舟按量计费可以设置账户级限额提醒比如月消费达到预算的 80% 时短信/邮件通知。第二道防线在new-api给每个令牌设置额度上限令牌超限直接拒绝请求给分组设置倍率和额度团队内谁超了谁买单。第三道防线是运维监控用 Prometheus 抓 new-api 的请求指标或者每天定时拉取平台日志做用量汇总异常量直接在群里报警。三层都做好按量计费才能真正放心。只靠第一道防线等于把全团队的预算交给一个月度汇总短信中间这些天的超额是无法感知的。6. 实战报错排查从 401 API Key 到上下文超限最后把接入过程中最常见的高频报错集中成一个排查节。这些报错在搜索词里反复出现说明不是个例。理解了根因你以后再遇到就能少走弯路。6.1 401 incorrect api key第一关卡报错文案通常是unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****注意最后那一段sk-svcac****这是请求实际携带的 Key 前缀。它提示了两件事一是这个请求最终访问的上游确实是火山方舟或其他兼容服务二是携带的 Key 不是上游认可的 Key。排查顺序是在 new-api 后台渠道测试里确认渠道密钥本身是否正确。用 curl 直接打一次火山方舟接口排除网关干扰。如果渠道直连成功检查请求是不是走了某个令牌而令牌对应的渠道密钥为空或已过期。如果请求经过 sub2api检查 sub2api 环境变量里配置的订阅串是否已经失效。还有一个坑new-api 的渠道里填写密钥时不建议添加多余空格或换行。我见过一例从控制台复制时带上了\n肉眼完全看不出来却让所有请求都 401。6.2 400 上下文超限与最大上下文长度报错报错类似error: 400 this models maximum context length is 1048576 tokens. However...这是请求的输入 token 数超过了模型上限。1M token 的上下文已经很大了经常超限的人几乎都是因为代码把整本文档、整个网页全文直接塞进了 system 或 user 消息里。处理方案分两层应用层要做 prompt 裁剪和分段可以按 token 数对历史消息做摘要再用滑动窗口只保留最近 N 轮。网关层可以在 new-api 里对模型设置上下文参数或者利用提示词压缩策略。根治的办法是让下游应用统计 token 而不是只数字符——中文场景尤其明显一个汉字可能对应 1 到 2 个 token字符数乘以 0.6 只是一个粗糙估算不可靠。6.3 streaming 连接断开connection lost 与 econnresetapi error: connection lost mid-response. the response above may be incomplete.这个报错说明在流式输出过程中客户端与 new-api 之间或 new-api 与上游之间连接被中断了。常见原因有三个客户端超时设置太短模型还没输出完客户端主动断开。new-api 到上游的网络链路不稳定尤其是 sub2api 这类本地转换层没有做超时调优时。上游服务端主动断开常见于长文本生成时负载过高。对应解法客户端 SDK 的 timeout 和 read timeout 调大比如 120 到 300 秒new-api 渠道里如果有超时重试相关参数打开重试但次数别太多sub2api 进程所在主机的 TCP keepalive 和连接池也要检查。实测下来econnreset在跨地域调用时高发把 new-api 和模型服务部署在同一区域能显著降低概率。6.4 配置类错误缺失 Base URL 与组织被禁用配置错误: claude provider 缺少 base_url 配置这类报错通常出现在你选择了一个依赖特定 provider 模板的渠道或转换层却没有给该 provider 配置 Base URL。验证方法是回到配置面板看渠道类型与实际上游协议是否匹配。比如你订阅的服务走的是 Claude 兼容协议但 new-api 渠道选成了 OpenAI 兼容就会出现这种情况。this organization has been disabled. an organization admin can re-enable则是账号层面的问题。出现这个要么是上游组织被管理员停用要么是欠费导致服务冻结。这不是你改配置能解决的直接去平台侧联系管理员或充值。6.5 下游客户端的接入姿势Chatbox 与 Codex CLI如果你把 new-api 的入口地址发给团队成员让他们在 Chatbox 里配置只需要两个字段API 地址填http://new-api-host:3000密钥填令牌。模型名填你在 new-api 里配置好的模型别名即可。很多人在这里把 API 地址填成了https://ark.cn-beijing.volces.com/api/v3等于绕过网关直连火山方舟——虽然也能用但计费归因和额度管理就废了必须纠正。Codex CLI 接入第三方 API 时配置方式也类似把环境变量里的 Base URL 指向 new-apiAPI Key 用 new-api 令牌。如果 Codex CLI 报 401检查环境变量是否真的被读取很多 CLI 工具会因为代理配置或工作目录不同而加载失败。下面是一张汇总表列了这几个高频报错的问题、原因和快速解法报错特征根因方向快速解法401 incorrect api key密钥错误/过期/空格用 curl 直测上游重新配置渠道密钥400 maximum context length输入 token 超限裁剪 prompt滑动窗口减少历史消息connection lost / econnreset超时太短或网络不稳调大 timeout减少重试同区域部署400 missing base_urlprovider 模板配置不全补全对应 provider 的 Base URLorganization disabled上游冻结/欠费联系平台侧处理我在多次部署和长期运行的实践里最大的体会是网络和配置问题通常很快能解决真正麻烦的是绕过网关和计费对不上这类管理问题。所以每次接入新渠道、发新令牌之前我都会确认一遍这个 Key 是否只存在于网关里下游拿到的令牌是否设了额度上限如果这两个答案是肯定的这套按量计费系统才能算真正落地。最后一个实操建议把 new-api 的日志保留时间调长一点至少保留 60 天。当月度账单出现争议时你能从日志中精确到某一秒、某个模块、某个模型的 token 消费记录——这种颗粒度的溯源能力在真正排查问题时比任何监控面板都管用。