NewAPI 部署教程：从零到能跑通的完整步骤与上线前必做的检查

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

先把结论说完：NewAPI 官方给了六种部署方式，但真正需要你做选择的只有两条主线——Docker Compose 用于生产，Docker 单容器用于个人和小规模；面板类（1Panel、宝塔）本质上是这两条的图形化包装，集群模式是 Compose 路线在多节点上的延伸。 部署本身不难，官方命令几行就跑起来了。真正会出事的是部署之后的两件事：官方文档里有一条醒目警告要求上生产前改掉所有默认密码，以及 README 里那段被很多教程略过的合规义务说明。这篇按官方原文把路线和检查项都列清楚。

本文所有命令与配置项均出自项目官方文档与仓库（QuantumNous/new-api），我们没有实际执行过这些命令，以官方文档当前版本为准。

六种部署方式，其实是两条主线

官方在安装部署章节列出的选项是这六个：

方式	官方给的适用场景
Docker Compose 部署	用 Compose 编排多个服务，适合生产环境
Docker 单容器部署	用镜像快速部署，适合个人使用
1Panel 部署	通过 1Panel 图形界面快速部署
宝塔面板部署	通过宝塔面板图形界面快速部署
集群部署模式	多节点分布式，用于高可用与负载均衡
本地开发部署	适合贡献代码与二次开发

按官方的描述反推，选择逻辑其实很清楚：

• 你要给团队或客户长期提供服务 → Compose。它能把网关、数据库、缓存这些编排在一起，配置沉淀在文件里而不是命令历史里
• 你自己一个人用，或者先跑起来看看 → 单容器。一条命令的事
• 你不熟悉命令行 → 1Panel 或宝塔。官方对这两个的描述都是”面向不熟悉命令行的用户”，说明它们解决的是操作门槛，不是能力差异
• 你需要多节点高可用 → 集群模式，这是 Compose 路线的延伸，不是另起炉灶
• 你要改代码 → 本地开发部署

需要提醒的是，选面板不等于可以跳过后面的安全与合规检查——图形界面只是把命令包装起来了，默认密码和合规义务一样都不会自动帮你处理。

路线一：Docker Compose（官方推荐用于生产）

官方 README 给的快速开始就是这条路线，三步：

# 克隆项目
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# 编辑 docker-compose.yml 配置
nano docker-compose.yml

# 启动服务
docker-compose up -d

注意中间那步不是可有可无的过场。官方把”编辑配置”单独列成一步，是因为仓库里的 docker-compose.yml 是一份模板，直接起会带着默认配置跑——这正是下一节要讲的问题所在。

仓库根目录还有一份 .env.example，环境变量的可选项在里面。官方另有专门的环境变量配置指南，把变量分成了数据库配置（含使用远程数据库的写法）、安全配置、Redis 缓存配置几组，其中 Redis 那组官方注明了可以用节点本地的 Redis，也可以整个省略。多机部署时这几组变量的取值是关键，README 里有单独的一节讲多机部署注意事项，走集群路线之前应该先读它。

路线二：Docker 单容器

官方给的命令分两种数据库形态。先拉镜像：

docker pull calciumion/new-api:latest

然后用 SQLite（这是默认形态）：

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

或者用 MySQL：

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

几个需要看懂而不是照抄的地方：

-v ./data:/data 是数据持久化。 官方在命令后面专门提示了这一条：它会把数据保存在当前目录的 data 文件夹里，你也可以改成绝对路径。这一行如果漏了，容器一删数据就没了。生产环境建议用绝对路径，避免因为工作目录不同而写到意外的位置。

SQL_DSN 里的连接串必须整体替换。 官方示例里的用户名、密码、地址、数据库名全都是占位性质的示例值，其中数据库名按你自己的命名规划改就行。尤其是密码——把示例密码原样带上生产是很多自建服务出事的起点。

TZ=Asia/Shanghai 影响的是日志与统计的时间显示。 如果你后面要看用量日志、按天做统计，时区不对会让所有时间对不上。

--restart always 决定宿主机重启后服务会不会自己回来。 个人用可能无所谓，长期服务必须有。

按官方说法，部署完成后访问 http://localhost:3000 即可使用。

上生产前必做（一）：改掉所有默认密码

官方的 Docker Compose 配置指南里有一条全大写的醒目提示，原文是要求在部署到生产环境之前更改所有默认密码。

这条提示值得单独拿出来说，因为它极容易被跳过：docker-compose.yml 是能直接跑起来的，跑起来之后一切正常，你不会收到任何关于默认密码的报错。等到问题暴露的时候，往往已经是数据库被人访问或者管理后台被人登录了。

对照检查的范围至少包括：数据库的 root 或应用账号密码、缓存服务如果启用了鉴权的密码、以及管理后台的初始管理员账号。这些位置分散在 Compose 文件和环境变量两处，改的时候两边都要过一遍。

上生产前必做（二）：那段被大多数教程略过的合规义务

README 里有一段 WARNING，内容是：把本项目作为面向公众的生成式 AI 服务或 API 转售服务运营时，使用者应先完成备案、内容安全、实名、日志留存、税务、支付和上游授权等合规义务。官方文档站另有独立的合规与可接受使用政策章节。

这段话的分量比它的篇幅大得多，因为它划出了两种截然不同的使用场景：

自用或团队内部使用——你把它当成一个统一接口层，公司内部几个项目共用一套渠道配置和额度管理，这是这类网关最常见也最没有争议的用法。

对外提供服务或转售 API——性质就变了。此时它不再只是一个技术组件，而是一项对公众提供的服务，上面那七项义务逐条都要落实。其中”上游授权”这一条尤其容易被忽略：你转售的是别人家的模型能力，你和上游供应商之间的协议允不允许你这么做，是一个需要事先确认的问题，而不是技术问题。

我们不提供任何合规建议，具体义务的认定与办理请以主管部门要求和专业意见为准。这里要说的只有一件事：这段警告是官方自己写在 README 里的，部署之前请把它读完，不要因为它出现在文档末尾就跳过去。

部署完之后，先搞清楚三个概念

跑起来只是开始。NewAPI 的日常使用围绕三个核心对象展开，先理解它们的关系，后面配置才不会乱：

• 渠道（Channels）——你接进来的上游，也就是各家模型服务
• API 令牌（API Tokens）——你发给使用方的凭证，用量与权限挂在它上面
• 用户分组（Group）——把使用方分类，不同分组可以对应不同的计费倍率

计费是这三者共同作用的结果，官方给出的公式是：

Quota = Group Ratio * Model Ratio * (Prompt Token Count + Completion Token Count * Completion Ratio)

也就是分组倍率 × 模型倍率 ×（输入 token + 输出 token × 补全倍率）。这些倍率在系统设置的运营设置里配置。这里不给任何具体倍率数值，因为那完全由你自己的部署决定，抄别人的必然是错的。

官方在排错说明里提到过一种情况：如果倍率或价格没有在”系统设置 - 运营设置 - 模型倍率设置”里配置好，调用会失败。所以部署完之后如果发现渠道通了但请求还是不成功，倍率配置是要检查的一项。

日志方面，官方把它分成了用量日志、任务日志和绘图日志三类，排查请求失败时按类别去看，比在一堆混合日志里翻要快。

小结

部署 NewAPI 本身是一条几分钟的路：选 Compose 还是单容器 → 改配置 → 起服务 → 访问端口。真正需要认真对待的是三件事：数据卷别漏、默认密码全改、对外提供服务前把那七项合规义务读完。

如果你还在判断要不要自建网关、还是直接用现成的聚合服务，站内的API 聚合与中转的横向对比从架构和成本两个角度讨论过这个选择；自建方案的安全面则可以参考API 中转的安全考量。至于接进来之后怎么控制各方用量，API 成本监控那篇讲的方法同样适用于自建网关。