1. 为什么我最后选了New-API一个统一管理大模型API的网关先说个背景。我手上有好几个大模型平台的调用额度日常开发又需要给不同项目分配不同的key每个项目单独去申请、单独记账、单独设限额实在太琐碎了。后来我发现很多人用的是New-API这个开源项目核心功能就是把这些上游渠道统一接入到一个网关里对外只暴露一个OpenAI格式的接口所有key的创建、配额、消费统计、模型路由都在这一个面板里完成。团队里其他人只需要拿我发出去的token就能调用我这边一键就能禁用某个token还能看到每个token的实时消耗管理成本一下子降下来了。如果你也在做类似的AI应用开发或者需要给团队内部统一发放大模型调用凭证那New-API基本就是为这个场景设计的。它的部署方式有很多种但用Docker部署是最省心的——不用手动装环境、不用担心依赖冲突一条命令拉起来就能跑后续升级也简单。这篇文章我就把我从零开始用Docker部署New-API的完整过程写出来包括环境准备、部署选型、配置细节、渠道接入和踩坑排查按我的操作顺序一条条讲清楚。如果你是第一次接触Docker照着做也能顺利跑起来。这里先声明一下整个部署过程我采用的是当前官方推荐的Docker镜像方案只涉及New-API本身的部署与配置不包含任何其他外部服务的接入指引。下面所有操作都在我自己的测试服务器上验证过你按步骤走基本不会出幺蛾子。2. 部署前要搞清楚的事Docker环境、端口和目录规划2.1 我用的服务器环境我部署New-API的服务器是一台2核4G内存的云主机系统是Ubuntu 22.04 LTS。说实话这个配置对New-API来说是绰绰有余的New-API本身是个Go语言写的Web服务资源占用很轻实际运行起来内存占用大概在几十MB到一百多MB之间主要看你接了多少渠道、日志量有多大。如果你已经有跑着其他服务的服务器把New-API塞进去也是完全可以的不需要单独开一台机器。Docker版本方面我用的是Docker 24.0版Docker Compose是v2.23。如果你还没装Docker可以参考官方文档装一下这里不展开。装完后docker --version和docker compose version能正常输出就说明环境没问题。2.2 端口规划先从3000端口说起New-API默认监听3000端口这也是它最方便的默认配置。默认端口的好处是你不需要额外记忆什么而且New-API的官方文档、各种教程都是拿3000端口举例的。但如果你服务器上已经有服务占用了3000端口那就需要把宿主机的端口映射改成别的比如8080映射到容器内的3000。我建议你在动手之前先想清楚这几个问题你打算用宿主机哪个端口来暴露New-API这个端口在你服务器的安全组/防火墙里是否放行了你是打算直接通过http://IP:端口访问还是打算后面套一层Nginx做域名反代我当时是打算后面用Nginx反代到子域名上所以宿主机端口就直接映射了一个比较不吵的端口然后Nginx把443端口转发到这个端口上。2.3 数据目录规划这一步千万别省New-API运行时会产生两类数据一类是数据库文件默认是SQLite数据库另一类是日志文件。这两样东西都必须在容器外面持久化保存否则你一旦升级容器或者误删容器所有配置、渠道、key就全丢了。我在服务器上建了一个专门的目录来放New-API的数据mkdir -p /opt/newapi/data cd /opt/newapi这里我把数据目录放在/opt/newapi/data下后面挂载的时候也统一以这个目录为准。这样做的目的是让所有和New-API相关的文件都在一个地方备份的时候直接打包这个目录就行了。关于SQLite和MySQL的选择我后面会专门讲这里先提一句单机部署、配置量不大、并发调用量可控SQLite完全够用。千万不需要为了看起来更专业一上来就搞个MySQL。我自己一开始就是直接SQLite跑的非常稳。3. 两种Docker部署方式对比docker run与docker compose3.1 官方镜像说明New-API官方提供的Docker镜像主要是calciumion/new-api在Docker Hub上可以搜到。这个镜像会跟随项目版本持续更新latest标签对应最新的稳定版。需要注意目前很多教程里提到的one-api镜像跟new-api是两个不同的项目New-API是在one-api基础上二次开发的分支项目功能上比原来的one-api多了一些新模型的支持和渠道类型所以如果你是想用新模型建议直接用new-api这个镜像。我部署的时候选择的是带tag的版本而不是latest因为latest在后续拉取时可能会拉到内容不同的镜像增加不确定性。你可以先去Docker Hub页面看一下当前最新版本号然后拉取固定版本。当然如果你图省事latest也不是不能用只是如果你有CI/CD或者需要严格版本管理的习惯固定tag会更好。3.2 用docker run直接跑最快速的上手方式如果你只是想快速跑起来看一下效果docker run一条命令就够了。我先把完整命令写出来然后逐段解释每个参数的意义docker run -d \ --name new-api \ --restart always \ -p 3000:3000 \ -e TZAsia/Shanghai \ -v /opt/newapi/data:/data \ calciumion/new-api:latest逐个参数来说-d后台运行容器。--name new-api给容器起个名字方便后面管理。--restart always非常关键。服务器一重启容器能自动拉起来。跑业务的容器我一般都会加这个参数不然机器重启一次服务就悄无声息地挂了太坑了。-p 3000:3000把宿主机的3000端口映射到容器内的3000端口。左边是宿主机端口右边是容器端口。-e TZAsia/Shanghai设置容器时区。不设的话默认是UTC时间日志时间和面板显示时间会跟你本地时间差8小时排查问题的时候很别扭。-v /opt/newapi/data:/data数据目录挂载。把宿主机目录和容器内的/data目录关联起来New-API的数据库和日志都会写到这个目录下。跑完之后docker ps看到容器状态是Up就可以打开http://服务器IP:3000访问了。3.3 用docker compose管理升级和迁移更方便docker run虽然快但如果你之后需要调整环境变量、增加挂载目录每次都要重新敲一长串命令很容易出错。我后来把部署方式改成了docker compose所有配置都写在一个docker-compose.yml文件里。给你看我的compose文件version: 3.8 services: new-api: image: calciumion/new-api:latest container_name: new-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai - SQL_DSN... volumes: - /opt/newapi/data:/data设定好之后启动命令就简单了cd /opt/newapi docker compose up -d之后不管是要重启还是查看日志docker compose restart docker compose logs -f升级的时候更方便只需要改一下镜像版本或者拉取latest然后docker compose up -d重新创建容器就行配置文件不用动。如果你开始只是用docker run跑着玩之后改成compose也简单先docker rm -f new-api删掉旧容器数据目录不变再用compose拉起来就完事了。3.4 端口映射的坑宿主机端口被占用了怎么办我有一次部署的时候发现3000端口已经被另外一个服务占了容器启动报端口冲突。解法很简单宿主机换个端口映射即可比如用-p 8000:3000访问地址就变成http://IP:8000。容器内部的3000端口不变因为New-API默认监听的是容器内的3000。这一点在很多新手那里容易绕晕你只需要记住一句话改成冒号左边是宿主机端口右边是容器端口容器内的端口是由应用本身决定的别动右边。如果你实在记不住还可以给容器指定环境变量PORT来改容器内监听端口但我不建议这么干没必要增加复杂度保持默认就好。4. 初始化配置从面板登录到关键系统设置4.1 首次访问与初始账号容器跑起来之后你通过浏览器访问http://IP:3000会看到New-API的登录页面。首次部署后系统会有一个初始管理员账号用户名是root密码是123456这个跟one-api的初始账号是一样的。登录后第一步一定要去修改密码别偷懒New-API是直接暴露在公网的话默认密码分分钟会被扫到。修改路径在面板右上角的头像菜单里个人设置中可以改密码。改完之后再顺手在后台把系统的一些基础配置过一遍。4.2 系统设置里的关键开关New-API的面板左边有个系统设置里面有不少开关和参数。我挑几个实际使用中比较关键的说一下第一登录注册相关的设置。如果你只是给自己或团队内部用强烈建议关闭允许注册。默认配置下部署完成后任何人都可以打开你的面板去注册账号如果又没有做额度限制很容易被人拿去白嫖。我在系统设置里把注册开关关掉后只有管理员能创建账号。第二充值/计费相关的设置。New-API自己带了完整的计费体系可以给每个token设置配额和倍率。如果你是按量转发给内部使用的建议打开按量计费模式这样每个token能被分配一个初始额度用完了就自动停止不怕超支。第三访问令牌的设置。说说令牌过期时间默认可能是永久有效但如果你给临时合作方发key建议勾选令牌有效期。这个后面讲token创建的时候我再细说。4.3 环境变量补充SQLite之外的数据库选择前面我一直说SQLite够用但如果你并发调用量很大或者你本来就有MySQL和Redis环境用MySQL Redis会安全一些。New-API通过环境变量支持外部数据库比如设置SQL_DSN来切换MySQL设置REDIS_CONN_STRING来连接Redis。不过我要给你一句实在话单机部署、日调用量在几十万次以内的应用SQLite根本不会成为瓶颈。SQLite的读写在单机上非常快而且它不需要额外维护数据库服务。我有个朋友拿New-API接了个日活几千人的小工具SQLite跑了好几个月没出过问题。所以除非你明确知道自己的瓶颈在哪里否则不要为了性能优化而上MySQL徒增运维负担。4.4 面板里那些容易忽略的小设置再说几个我后来发现很实用的小配置。在系统设置里的运营设置标签页可以设置网站公告、首页页脚之类的内容如果你要在团队内推广可以把使用说明写在这里大家一打开就能看见。还有一个模型价格的管理默认配置下不同模型的价格倍率可能不是你想要的值如果你们内部按模型计费这个需要在模型价格里逐条调好。这些设置看起来琐碎但如果你打算长期使用前期花十分钟把这些配置捋清楚后面能省很多事。别像我一开始那样直接拿默认配置开跑结果内部要按额度分摊费用的时候发现价格倍率全是乱的又回来一条条改。5. 渠道接入实战把上游大模型服务接到New-API5.1 渠道类型怎么选New-API支持很多种渠道类型包括OpenAI官方、Azure OpenAI、各种兼容OpenAI接口的服务商、以及本地部署的大模型服务等。在建立渠道前你要先明确一点——你的上游接口是哪个服务商、走的是什么协议格式。New-API的大部分渠道类型都是兼容OpenAI格式的所以你只需要看上游服务商提供的接口文档找到Base URL和API Key就行。我实际接过的渠道有几种OpenAI官方渠道Base URL就是https://api.openai.com/v1。Azure OpenAI渠道需要填的是你的Azure资源名、部署名、API版本等参数跟OpenAI官方的填法不太一样。各类第三方大模型API服务商只要它兼容OpenAI格式基本上填一个Base URL和Key就能通。面板左侧菜单进入渠道点击新建渠道。在这里填渠道名称你自己好认就行、渠道类型选OpenAI这种兼容类型、Base URL也就是上游接口地址、密钥上游给你发的API Key。如果是Azure这一类特殊的渠道页面上会有对应的额外字段跟着提示填就行。5.2 渠道测试是怎么工作的每填完一个渠道页面下方通常会有一个测试按钮点一下它会往这个渠道发一个模型请求看能不能通。New-API的渠道测试用的是渠道配置里默认的模型所以你在填渠道的时候还要注意设置好模型列表也就是这个渠道能转发哪些模型。这里容易踩的一个坑是很多第三方服务商的Base URL并不完全跟OpenAI官方一致后面可能不带/v1或者带了/v1/多一个斜杠。你先去读对方文档确认一般来说OpenAI格式的接口地址会带/v1但有些中转站会把/v1放在路径末尾也可以。如果测试不通优先去检查Base URL是不是拼错了。还有一个坑是密钥字段。有的人会把上游给的Key粘贴成带空格的或者复制时把末尾换行符也带上了这种小问题测试时经常报401或者404让人白折腾半天。要是测试失败第一件事就是去看看密钥有没有多余字符。5.3 模型映射与名称对齐渠道建好后你还得在模型配置里确认New-API暴露给你的下游使用者用什么模型名。比如你的上游渠道支持gpt-4o和gpt-4o-mini那这两个模型就会出现在渠道配置的模型列表里。New-API会把渠道的模型和面板内全局的模型关系做映射最终对外统一以OpenAI格式的/v1/chat/completions接口提供服务。有一个实际场景你的上游渠道叫claude-3-5-sonnet但你想让下游通过/v1接口调用时统一用claude-3.5-sonnet这个别名你可以在模型别名/映射里做设置。这种功能对于多渠道统一管理非常有用内部的模型命名规范和上游渠道实际的名字不一致时不用去改每个渠道直接做映射就行。5.4 多渠道路由与负载均衡New-API还支持同一种模型配置多个渠道调用时会按策略自动做负载均衡和故障转移。举个例子你有两家服务商都提供gpt-4o-mini那就建立两个渠道都加gpt-4o-mini到模型列表里然后面板会自动按权重分配请求。如果其中一个渠道挂了New-API会尝试把请求转发到另一个渠道下游无感知。这个功能我实际用起来非常香。我有两个上游key一个按量便宜但偶尔限流另一个稳定但价格高一点我把两者的权重设置成3:1大部分请求走便宜的渠道关键的请求万一失败自动落到备用的那个。虽然New-API默认的失败重试策略和超时时间可以根据实际场景调整但在渠道里设置优先级和权重是实现这种容灾效果的两个最关键参数。6. Token管理怎么给下游发key才安全6.1 什么是令牌Token在New-API里渠道Channel对应的是上游的各种API Key而令牌Token是你自己发放给下游使用者的访问凭证。下游拿着这个Token来请求你的New-API网关网关再去渠道那边换取真正的上游调用权限。这样做的好处是上游的Key永远不会暴露给下游使用者你随时可以吊销一个Token而不影响其他用户。令牌的创建位置在面板左侧的令牌菜单里。新建令牌时可以设置令牌名称给使用者起的名字方便自己记。过期时间可以设一个具体的失效日期。额度这个Token一共可以用多少额度按积分/余额计算。模型限制只允许该Token调用哪些模型不填则默认可用全部。IP限制限定Token只能从某些IP发出请求。6.2 给不同场景发不同权限的令牌我自己的实践是分层管理给长期项目发一个不限时但有明确额度的令牌给临时调试发一个几小时就过期的令牌给测试环境发一个只允许调用低价模型的令牌。这样做的好处是任何一个环节的Token泄漏了我都可以只吊销那一个其他环境完全不受影响。另外New-API的令牌在调用时用的是Authorization: Bearer sk-xxx这种OpenAI标准格式下游不需要关心任何New-API的内部配置直接按OpenAI官方文档写代码就行。这一点对我们做技术团队支持特别重要接入方的开发根本不需要学习新东西把Base URL换成你的New-API地址、把API Key换成你发的Token代码一行不用改。6.3 消费记录与告警New-API的每个Token调用都会产生一条日志包括请求的模型、消耗的额度、响应状态、耗时等。面板的日志页面可以按令牌筛选、按模型筛选甚至可以按关键词搜索请求内容。我一般每周会看一眼消费分布看看哪些模型消耗得最多再决定要不要调整权重或跟团队沟通一下使用情况。如果担心某个Token额度快用完New-API的系统设置里有通知功能可以对接Webhook或者邮件在一定阈值触发提醒。这个功能我建议打开不然某个Token额度用完的那一刻下游才发现临时充值、续期都很被动。7. 部署之后必做的四件事备份、升级、日志排查和反向代理7.1 数据备份一条命令打包整个目录因为数据和配置都放在/opt/newapi/data这个挂载目录里备份就变得极其简单。我写了个简单的crontab任务每天凌晨打包一次数据目录保留最近七天的备份tar -czf /backup/newapi-$(date %Y%m%d).tar.gz -C /opt newapi/data恢复的时候更简单把备份解压回/opt/newapi/data再docker compose restart就完事了。SQLite数据库文件是单文件存储的用它最大的好处就是冷备极其方便不像MySQL要搞逻辑导出复制文件就行。当然你如果用的是MySQL那备份逻辑就转到MySQL那一侧去这里不展开。7.2 容器日志排查遇到渠道测试失败怎么看日志渠道测试失败是New-API使用中遇到最多的一个问题。在面板里测试渠道时有时会显示一个很笼统的错误提示比如请求失败或者上游返回错误。这种时候最好的排查手段就是看容器日志docker logs -f new-api日志里会打出每次请求的详细信息包括请求的URL、上游返回的状态码、响应体的错误内容等。我遇到过一次渠道测试一直报401面板上只提示Invalid Authentication后来看容器日志才发现是上游返回的响应体里带了更多细节原来是密钥格式不对。所以遇到渠道问题先看日志别急着在面板里反复试。7.3 升级与回滚用compose一条命令搞定New-API的升级频率不算低特别是新模型出来的时候上游支持了某个新模型你可能会想升级到新版本来获得对应的渠道适配。升级的流程是先手动备份一次数据目录。docker compose pull拉取新镜像。docker compose up -d重新创建容器。docker compose logs -f观察启动日志是否正常。如果升级后发现问题回滚也很简单在compose文件里把镜像tag改回旧版本再执行docker compose up -d就行。由于数据目录挂载在外面升级和回滚都不影响你的渠道、令牌和日志数据这也是我一直强调Docker部署最省心的原因。7.4 反向代理与HTTPS如果你不想用IP加端口的方式访问想通过一个域名访问New-API那就在前面加一个Nginx反向代理。我的做法是server { listen 443 ssl; server_name api.example.com; ssl_certificate /etc/nginx/ssl/example.crt; ssl_certificate_key /etc/nginx/ssl/example.key; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }这里有几个需要注意的点一是proxy_pass指向的是宿主机上New-API映射的端口也就是3000二是必须把Host头传给后端否则有些依赖Host判断的功能会出问题三是如果你的New-API是通过http://IP:3000访问的那边面板里配置的系统地址应该填HTTPS的域名地址否则生成的分享链接、令牌链接都是IP加端口的。我还遇到过一种情况Nginx配置没问题但前端页面能打开接口请求却报跨域错误。这是因为New-API前端和后端在同源部署时一般没有跨域问题但你用反代时如果改了路径、加了别的层跨域就会出现。New-API环境变量里有一个ALLOW_ORIGINS可以设置允许的跨域来源如果你确实需要可以在启动时加这个环境变量。7.5 容器启动失败最常见的几个场景最后总结一下我遇到过的启动失败场景和对应解法方便你一上来就对症下药现象可能原因处理方法端口冲突宿主机3000已被占用改宿主机映射端口容器反复重启数据目录权限不对chmod -R 755 /opt/newapi/data无法写入SQLite宿主机目录不可写给目录改属主或加写权限日志时间差8小时没设置TZ环境变量加上-e TZAsia/Shanghai升级后配置全丢了之前没挂载数据目录找到旧容器数据恢复之后务必挂载每次在群里看到有人问为什么我升级之后渠道全部没了我基本都能猜到他是没挂载数据卷跑的新容器。这是个老生常谈但又极其常见的坑我在第2节里反复强调目录规划原因就在这里。8. 我的一些使用心得和小技巧New-API部署完真正用起来之后有几个细节是值得慢慢体会的。第一个是渠道故障自动转移的可靠性。我在上面提到过权重路由但这里要强调一下自动转移的能力依赖New-API的失败重试配置如果某个渠道超时很慢一个请求可能会卡住比较久才切换。你可以在系统设置里调整超时时间和重试次数让它更适合你的上游服务商的实际响应速度。我自己的经验是把超时时间调成比上游最慢情况稍微短一点能让故障转移的体感好很多。第二个是日志保留时间。默认情况下New-API会保留一段时间的日志时间长了日志文件会变得很大。如果磁盘空间紧张你可以在系统设置调整日志保留天数或者定期rm掉旧日志文件。这个字段好像叫日志保留天数设置短一点能省不少空间。第三个是令牌模型限制的实际用途。之前我总觉得模型限制没啥用后来有一次团队里的同事拿测试token调了最贵的大模型月底账单一出来我肉疼了半天。从那以后我给所有测试令牌都加了模型限制只允许调用便宜的模型。这个对成本控制是真的有效强烈建议你也配一下。第四个是关于面板里的按倍率计费。New-API的计费不是按美元/人民币直接算而是按一个抽象的积分体系通过设置模型倍率把不同模型的消耗折算成积分。你可以在系统设置里调整全局的积分到货币的兑换比例。这个设计初看有点绕但好处是所有上游的价格变动时你只需要改模型倍率不需要动下游的令牌配置。文章写到这儿部署、配置、使用的基本链路已经全走了一遍。我个人的体会是New-API这种网关类项目单看任何一步都不难难的是把它真正融入到团队的工作流里——怎么规划渠道、怎么分配token、怎么控制成本这些才是长期使用时真正影响体验的地方。而Docker的部署方式则保证了你随时可以干净地重来、快速地升级不至于被环境问题拖住脚步。希望对你有帮助。