企业官网建设流程全解析

很多做模型接入的朋友，迟早会遇到同一类问题：公司里买了火山方舟的按量计费额度，豆包、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 配置模型定价之前，先去火山方舟的计费页面确认三个数据：

确认后，把这些单价填入 new-api 渠道的模型价格里。注意 new-api 的价格单位通常是"每百万 token 的美元/元"换算后的数值，务必统一币种和基准，否则网页显示的价格和实际账单会差出一个汇率。

3. new-api 部署与渠道、令牌配置全流程

基础信息齐了，就可以实操了。我以 Docker Compose 方式为例，这是目前最省心的部署路径，升级维护都方便。

3.1 用 Docker Compose 快速部署网关

新建一个目录，写一份最小的docker-compose.yml：

services: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - "3000:3000" volumes: - ./data:/data environment: - TZ=Asia/Shanghai - SQL_DSN= # 默认使用内置 SQLite，生产建议改 MySQL - SESSION_SECRET=replace_with_a_long_random_string

这里两个环境变量值得留意。TZ=Asia/Shanghai影响日志和账单的时间口径，如果你和火山方舟账单按北京时间核对，这个必须设。SESSION_SECRET用于登录会话加密，不设置或者太短，重启后用户登录状态会失效；生产环境建议填一个 64 位随机字符串。

启动后访问http://localhost:3000，第一次打开会引导你创建管理员账号。接下来进入后台，先别急着配渠道，去"设置"里把系统名称、显示余额、用户注册等选项按团队需要调整。尤其是"允许用户注册"选项，默认如果开着，公网部署后任何人都可以来注册白嫖额度，务必改成仅管理员创建用户或关闭注册。

示例启动命令：

docker compose up -d docker compose logs -f new-api

看到日志输出监听端口正常后，后台就可以登录了。

3.2 添加火山方舟渠道：型号、密钥与模型映射

进入"渠道"页面，新建渠道。渠道类型选择火山方舟（VolcEngine Ark），然后填写参数：

提交后，点击"测试"按钮。如果返回正常，说明渠道通了。如果报 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 + 按量扣费"。两者的核心差别在于：

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 与账单核对

对账步骤听起来繁重，其实按以下流程走，十分钟内能完成：

1. 在火山方舟控制台导出上一自然日或上周的用量明细，记录各模型的输入、输出 token 数。
2. 在 new-api 日志页面，筛选对应时间范围和对应渠道的日志，记录网关记录的 prompt_tokens 和 completion_tokens。
3. 对比两边数字。

因为 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。

排查顺序是：

1. 在 new-api 后台渠道测试里，确认渠道密钥本身是否正确。用 curl 直接打一次火山方舟接口，排除网关干扰。
2. 如果渠道直连成功，检查请求是不是走了某个令牌，而令牌对应的渠道密钥为空或已过期。
3. 如果请求经过 sub2api，检查 sub2api 环境变量里配置的订阅串是否已经失效。

还有一个坑：new-api 的渠道里填写密钥时，不建议添加多余空格或换行。我见过一例从控制台复制时带上了\n，肉眼完全看不出来，却让所有请求都 401。

6.2 400 上下文超限与"最大上下文长度"报错

报错类似：

error: 400 this model's 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 与 econnreset

api 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-api，API Key 用 new-api 令牌。如果 Codex CLI 报 401，检查环境变量是否真的被读取，很多 CLI 工具会因为代理配置或工作目录不同而加载失败。

下面是一张汇总表，列了这几个高频报错的问题、原因和快速解法：

我在多次部署和长期运行的实践里，最大的体会是：网络和配置问题通常很快能解决，真正麻烦的是"绕过网关"和"计费对不上"这类管理问题。所以每次接入新渠道、发新令牌之前，我都会确认一遍：这个 Key 是否只存在于网关里？下游拿到的令牌是否设了额度上限？如果这两个答案是肯定的，这套按量计费系统才能算真正落地。

最后一个实操建议：把 new-api 的日志保留时间调长一点，至少保留 60 天。当月度账单出现争议时，你能从日志中精确到某一秒、某个模块、某个模型的 token 消费记录——这种颗粒度的溯源能力，在真正排查问题时比任何监控面板都管用。