干过AI应用底层调度的朋友应该能理解模型接口散落各处、每家的鉴权方式和计费标准还不一样光是维护一堆上游Key就够头疼。New-API这个项目简单说就是一个开源的LLM API网关和管理面板把OpenAI、Claude、Gemini以及国内外各种兼容OpenAI协议的服务聚合到一个入口再统一生成令牌、控制额度、做负载均衡和日志审计。这篇文章就围绕docker部署New-API讲透从环境检查、镜像选择、容器编排到初始化配置、生产环境的域名和数据库再到我实际踩过的坑给出一套能直接照着操作的方案。适合正在做AI应用开发、给团队搭模型网关或者单纯想把手里各种模型Key统一管起来的人。1. 为什么要自建New-API它到底解决了什么问题1.1 一个入口代替一堆Key先聊一个场景。你手里有OpenAI的Key有国内某家厂商的Key还可能买了第三方的中转服务。散着用的时候每个应用都要单独配置密钥、单独计费、单独处理限流。万一某个上游挂了所有依赖它的应用一起报错你只能挨个去改配置。New-API做的事情就是把这一堆东西全部收编到一个服务里上游叫“渠道”Channel你把各家Key填进去下游叫“令牌”Token你的应用只用这个令牌调接口对外暴露一个OpenAI兼容地址比如http://你的域名/v1应用端只需要改一个base_url和一个api_key其余全部由New-API转发和调度。这样分开之后上游Key到期、上游服务抽风、上游改了模型名都只影响New-API这边的渠道配置你的应用代码根本不用动。说白了它把模型供应商的差异和故障全部隔离在了网关这一层。1.2 New-API和one-api的关系很多人会问New-API是不是就是one-api换个皮New-API确实是在one-api基础上fork出来继续维护和增强的社区版本但功能上更激进一些。我自己对比下来的感受是one-api更新节奏相对稳定偏向“够用就好”New-API多了一些细粒度控制比如渠道的模型映射、令牌的模型限制、更详细的分组权限、以及一些UI上的调整New-API对上游新模型的支持通常更快社区也更活跃。所以如果你是从零开始搭或者准备长期维护我更建议直接用New-API尤其当你需要对接的不只是OpenAI官方还包括大量国产模型、开源模型服务的时候New-API的渠道类型覆盖会全很多。1.3 谁真正需要这套东西不是所有场景都需要上网关。如果你只是自己写个脚本调OpenAI一个Key直连就够了。但下面几类情况部署New-API几乎是刚需团队多人共用一个账号要给每个人独立Token、独立限额做SaaS应用要给不同客户分配不同套餐和调用次数有多家模型供应商想统一监控调用量和费用想把模型服务内网化统一做限流、缓存、审计。我见过不少公司一开始图省事直连后来账单、权限、故障处理全部乱成一团最后还是回来搭网关。早一点部署后面少很多麻烦。2. 部署前的准备环境、镜像与配置决策2.1 Docker环境检查先解决启动不了的问题在真正拉镜像之前先把Docker环境搞定。Windows上最常见的坑就是Docker Desktop启动时报virtualization support not detected或者直接提示Docker Desktop failed to start because virtualization support is not detected。这个报错的意思是宿主机没有开启虚拟化支持或者虚拟化组件不可用。排查顺序我建议是这样先到任务管理器—“性能”标签页看“虚拟化”是否显示“已启用”。如果显示未启用需要进BIOS打开Intel VT-x或者AMD-VWindows 10/11家庭版默认没有Hyper-V需要先装WSL2Windows Subsystem for Linux。Docker Desktop新版依托WSL2运行WSL2没装好就会报虚拟化错误如果你实际是在虚拟机里跑Docker Desktop还要在虚拟机设置里打开“嵌套虚拟化”否则即使宿主机开了VT-x虚拟机内部依然检测不到。Linux环境下相对简单uname -r看内核版本一般3.10以上就行然后安装docker-ce、启动服务、设置开机自启。装完之后执行sudo systemctl enable docker sudo systemctl start docker docker version能打印出Client和Server两段信息说明Docker守护进程已经正常运行。2.2 镜像选择与版本策略New-API官方镜像名是calciumion/new-apiGitHub上的项目名也叫new-api。镜像的tag策略我一般遵循latest最新版适合尝鲜但我不建议生产直接用因为未知风险多一些vX.Y.Z具体版本号生产环境首选出了问题好回滚beta相关tag只在测试环境玩。拉镜像的时候注意架构x86服务器直接docker pull calciumion/new-api:latestARM机器比如树莓派或者某些国产ARM服务器要确认镜像是否支持对应架构。大部分情况下官方镜像都是多架构的但如果你在ARM上拉取后无法运行先检查一下是不是架构不匹配。2.3 部署形态单容器还是docker-compose部署New-API有两条路快速验证版一条docker run命令容器起来了就能用适合先看看界面和功能。数据默认写在容器的/data目录里通过volume挂载到宿主机。生产推荐版用docker-compose编排把环境变量、端口、volume、重启策略、日志限制全部写进YAML文件可追踪、可复现。尤其是你后面还要加Redis、MySQL、Nginx反代的时候compose把所有服务串在一起管理比一堆裸容器清爽得多。我自己实际部署过几十套强烈建议从一开始就用compose哪怕只是单台服务器。因为你后续一定会改配置docker run的命令又长又容易漏参数而compose文件是声明式的一眼就能看清整个服务的最终形态。2.4 数据库选型SQLite还是MySQLNew-API默认使用SQLite数据文件存放在/data目录里。SQLite的好处是零依赖、部署简单、单文件备份方便坏处是并发写性能有限不适合大规模多实例部署。我的建议分这么几种情况日请求量几百到几千的团队内部使用SQLite完全够别自己给自己找麻烦要做高可用、横向扩展或者需要接入监控系统上MySQL/PostgreSQL如果你本来就有现成的MySQL实例直接用外部数据库也不复杂只要设置SQL_DSN环境变量即可。有一点要提醒SQLite和MySQL之间切换不是无缝的改之前先备份实际数据尤其是令牌和渠道配置。虽然这些数据也能重新录入但日志和历史调用数据丢了就真没了。3. 完整部署实操从拉取镜像到服务上线3.1 快速验证版一条命令跑起来先跑一个最小可用实例看看效果。在Linux服务器或者Windows PowerShell里执行docker run --name new-api -d \ --restart always \ -p 3000:3000 \ -e TZAsia/Shanghai \ -v /home/ubuntu/new-api/data:/data \ calciumion/new-api:latest解释一下这里的几个关键点--restart always容器异常退出或者服务器重启后自动拉起属于自托管服务的基本操作不加这个后面机器一重启服务就失联-p 3000:3000宿主机端口到容器端口映射。New-API默认监听容器的3000端口这个端口在较新版本里通过环境变量可以改但默认值一直保持3000跟one-api一致-e TZAsia/Shanghai设置时区。不设的话容器默认UTC日志时间和账单时间都是错的排查问题的时候能把你绕晕-v /home/ubuntu/new-api/data:/data数据目录挂载。SQLite数据库文件、日志、图片上传都在这底下。路径可以自由改但宿主机目录权限要给对否则容器内写不进去。跑起来之后先看容器状态docker ps | grep new-api docker logs -f new-api日志里出现监听端口成功的提示浏览器访问http://服务器IP:3000就能看到登录页。第一次部署你不需要急着输账号密码默认没有初始管理员账号需要你访问一次首页后根据界面提示注册/初始化管理员账号。3.2 docker-compose生产级部署快速验证没问题之后再上正式配置。下面这个compose文件是我常用的基础模板单机部署直接用version: 3.8 services: new-api: image: calciumion/new-api:v0.2.0 container_name: new-api restart: always ports: - 3000:3000 environment: - TZAsia/Shanghai - SESSION_SECRETyour_long_random_string - LOG_LEVELinfo - SQL_DSN - REDIS_CONN_STRING volumes: - ./data:/data - ./logs:/app/logs logging: driver: json-file options: max-size: 50m max-file: 3几点说明SESSION_SECRET是会话签名密钥不设置系统也能跑但会警告。生产环境务必设置成一个足够长的随机字符串否则有会话伪造风险LOG_LEVEL控制日志详细程度排查问题时临时改成debug平时用infologging限制日志文件大小避免容器无限写日志把磁盘撑爆。这个配置经常被忽略但它很关键./data和./logs目录建议手动创建并设置为当前用户可写不然有些系统上volume挂载会因权限问题失败。启动方式mkdir -p data logs docker-compose up -ddocker-compose会自动拉取镜像并启动容器之后再修改配置只需要docker-compose up -d3.3 关键环境变量与参数解析除了上面提到的基础变量还有几个环境变量值得提前知道省得后面改起来手忙脚乱变量作用我的建议TZ容器时区设为Asia/ShanghaiSESSION_SECRET会话签名密钥26位以上随机字符串SQL_DSN外部数据库连接串留空则用SQLiteREDIS_CONN_STRINGRedis连接串并发高时建议配置BATCH_UPDATE_ENABLED批量更新开关true时降低DB压力BATCH_UPDATE_INTERVAL批量更新间隔秒默认15按需调整LOG_LEVEL日志级别生产info调试debug有几个变量不是官方文档里第一位写的但实际调优时会用到BATCH_UPDATE_ENABLED和BATCH_UPDATE_INTERVAL控制日志和用量统计的批量写入请求量大的时候可以有效减少数据库压力。我遇到过SQLite模式下频繁写日志导致锁库的情况打开批量更新之后情况明显好转Redis配置后可以缓存部分系统数据并提供更可靠的限流能力生产环境建议加上。3.4 首次启动与健康检查容器启动到服务可用之间有一段初始化时间尤其第一次启动需要建表。你可能会看到浏览器一直转圈不要急着重启容器先看日志docker logs --tail 100 new-api看到类似server started或者监听端口已生效的日志再刷新页面。如果容器一直重启大概率是端口冲突、数据目录权限、或者环境变量配置错误先docker logs看最后几十行再动手。日常检查健康状态可以直接请求接口curl http://127.0.0.1:3000/api/status返回含success字样的JSON说明服务正常。这个接口也可以配到监控系统里做健康探活比单纯检查容器状态要实在得多。4. 初始化与核心配置渠道、令牌与模型4.1 首次登录与基础设置浏览器访问http://服务器IP:3000第一次打开会让你初始化管理员账号。这一步千万别跳过也千万别用弱密码。管理员权限极大能看所有调用日志、能改所有渠道密码泄露等于模型账单任人刷。登录之后进“系统设置”建议先把这几项配置好网站名称显示在页面左上角改成你的业务名回调地址这个很关键如果后面要对接支付或者微信通知回调地址必须是公网可访问的地址用户注册团队内部使用建议直接关闭注册由管理员创建用户默认用户额度根据你的成本和业务需求设置默认值最好别设太大。这里有个经验如果你准备对接GitHub或者企业微信登录先把回调地址里填上真实域名再测试否则OAuth会一直跳转失败白白浪费时间。4.2 配置模型渠道登录之后重点就是“渠道”页面。点击添加渠道出来一张表单核心字段有类型选你对接的服务商比如OpenAI、Azure OpenAI、Claude、Gemini、各类国产模型服务名称随便填个方便识别的前缀比如openai-prod-01API地址渠道服务的Base URLAPI密钥上游服务的Key模型列表这个渠道能提供哪些模型。填完之后点“测试”系统会发一个真实请求去验证。测试通过再保存否则渠道状态一直是不可用。有一个容易忽略的点同一个上游Key你可以建多个渠道把模型列表拆开。比如一个渠道只放gpt-4o另一个渠道放gpt-4o-mini配合后面要说的模型重定向可以达到更细粒度的流量调度。4.3 创建访问令牌与权限控制渠道配置好后下一步就是创建下游令牌。用户页—我的令牌点添加令牌关键配置包括额度这个令牌总共可以用多少额度模型限制允许使用哪些模型不填默认全部IP限制允许的来源IP可以填多个过期时间令牌有效期分组令牌所属分组配合渠道分组实现分流。令牌生成之后价值就是sk-后面一串字符串只在创建时完整显示一次记得马上复制保存。我自己第一次部署时没注意直接关了页面结果只能删掉重新生成倒也不麻烦但给团队新人发密钥时务必强调这件事。创建完令牌应用侧接入就非常简单了base_url填http://你的服务器IP:3000/v1api_key填刚创建的令牌模型名填需要用的模型。我自己测试时最常用的命令curl http://127.0.0.1:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的令牌 \ -d { model: gpt-4o-mini, messages: [{role: user, content: 你好}] }如果返回正常的choices内容说明整个链路已经打通。4.4 模型重定向与多模型分流New-API有个很实用的功能叫“模型重定向”能把一个模型名映射到另一个模型名。举个例子你在应用里写死了gpt-4o想切换到某个国产模型不用改应用代码在New-API里建一条重定向规则把gpt-4o指到国产模型实际名称即可。这个功能的另一个用法是负载均衡同一个模型建多个渠道系统按权重或顺序轮流分发请求。渠道页可以设置渠道权重权重高的渠道会被优先使用。配合渠道分组还可以把VIP用户分到更稳定的渠道组普通用户走成本更低的渠道组。5. 生产环境再进一步域名、HTTPS与Redis5.1 用Nginx做反向代理并启用HTTPS裸奔的IP加端口方式只适合内网测试。生产环境我建议至少做到域名访问、HTTPS加密、以及可能的路径代理。用Nginx反代New-API的配置核心部分如下server { listen 80; server_name api.example.com; 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_set_header X-Forwarded-Proto $scheme; } }端口只有80的话可以通过HTTP访问。真正线上建议用certbot或者Caddy自动申请证书Caddy配置更简单一句reverse_proxy就能自带HTTPS。我个人比较懒新项目直接用Caddyapi.example.com { reverse_proxy 127.0.0.1:3000 }Caddy会自动申请和续期证书。如果你用Nginx就用certbot自动续期。域名和HTTPS搞定之后记得去系统设置里把系统地址改成https://api.example.com否则OAuth回调、图片URL生成都会基于旧的IP地址。5.2 Redis配置与限流并发量上来以后强烈建议加Redis。环境变量配置Redis连接串REDIS_CONN_STRINGredis://default:passwordlocalhost:6379/0配置Redis之后系统可以用Redis做计数缓存、限流统计减少对数据库的实时压力。New-API还支持Redis做分布式限流多实例部署时这个是必需品。不过我踩过一个坑Redis版本太老会导致连接协议不兼容。建议Redis版本用5.0以上连接串里指定db编号时注意别跟其他业务共用一个db免得互相污染数据。另外Redis里保存的缓存数据对一致性要求不高就算Redis故障系统也会降级回数据库模式不会直接挂掉但响应会变慢。所以监控里要留意Redis连接状态。5.3 定时任务与日志管理New-API内部有定时任务会自动检测渠道可用性。这个功能在系统设置里可以看到相关选项。定时任务跑起来后上游挂了New-API会在日志里标记渠道状态下游请求会尽量避开异常渠道。日志方面容器日志默认输出到stdout通过docker的logging配置限制大小。但如果你想长期保留访问日志建议挂载宿主机目录或者直接接入ELK之类的日志平台。日志字段里能看到每次请求的模型、上游渠道、令牌部分脱敏、耗时、额度消耗排障和追责都靠这个。5.4 备份与恢复备份这事最好在部署第一天就设好而不是等到出事故才想起来。对于SQLite模式备份最简单docker exec new-api cp /data/new-api.db /data/backup-$(date %Y%m%d).db这只能算临时快照。正经做法是定时任务每天备份并同步到异地或者对象存储。如果是MySQL模式直接用mysqldump之类常规办法即可。恢复的时候注意先停掉New-API容器再恢复数据库否则运行中的实例可能会把内存里的状态写回覆盖恢复的文件。6. 常见问题与排查实录6.1 Docker Desktop启动失败virtualization support not detected这个报错Windows用户几乎都会遇到。Docker Desktop failed to start because virtualization support is not detected说明Docker检测不到可用的虚拟化层。我的排查顺序确认CPU虚拟化已经在BIOS开启任务管理器虚拟化显示“已启用”确认Windows功能里“适用于Linux的Windows子系统”和“虚拟机平台”两个功能已开启用命令wsl --status检查WSL2发行版是否正常不正常就重装WSL如果你在VMware/VirtualBox里跑Windows给虚拟机设置里勾选“虚拟化Intel VT-x/EPT”之类的嵌套虚拟化选项。这一串检查做完绝大部分Docker Desktop都能正常启动。如果你的电脑是Win10家庭版没有Hyper-V选项走的完全是WSL2路线那WSL2装好基本就解决了。6.2 镜像下载慢docker pull拉New-API镜像慢常见原因是默认从国外镜像仓库拉取。解决办法是给Docker配置镜像加速器。Linux下编辑/etc/docker/daemon.json{ registry-mirrors: [ https://docker.m.daocloud.io ] }重启Docker后再次拉取速度通常能快很多。注意不要一次配太多加速器选择一两个稳定的就行。拉镜像的时候可以加上参数--platform linux/amd64指定平台有时也能避免不必要的等待。6.3 容器反复重启容器一直Restarting第一步一定是看日志而不是猜docker logs new-api --tail 50经常出现的原因端口被占宿主机3000端口已存在其他进程换一个宿主端口映射比如-p 3001:3000数据目录权限不对容器内以特定用户运行宿主机挂载目录没有写权限日志会报权限错误数据库文件损坏如果之前强制kill过容器SQLite文件可能损坏把/data/new-api.db改个名再启动让它重新初始化这算下策但能救急配置文件错误检查环境变量里有没有特殊字符、引号没闭合。日志是排查的唯一真相来源。凡是容器异常先docker logs比到处百度有用得多。6.4 数据库连接失败使用了外部MySQL后容器启动失败常见原因是New-API容器地址里的MySQL是host.docker.internal或者宿主机IP但MySQL的用户权限只允许本地访问。解决办法MySQL用户授权时绑定%或者具体内网IP段确认MySQL的bind-address不是只监听127.0.0.1如果MySQL也在Docker里跑让New-API和MySQL在同一个docker网络内用服务名连接。命令行里测试外连MySQL时先手动验证一下连接串能不能通mysql -h 宿主机IP -P 3306 -u newapi -p能正常进去再填New-API的SQL_DSN。6.5 令牌鉴权失败401或403请求New-API返回401常见原因其实很直接令牌复制少了字符或者多了空格令牌已被删除或者过期令牌的IP限制里没有包含当前来源IP请求头格式不对Authorization: Bearer sk-xxx中间必须有空格。403则多半是令牌额度用完了或者令牌的模型限制里没包含当前请求的模型。去后台看日志里面会有鉴权失败的具体原因不要只看HTTP状态码猜。6.6 回调地址问题对接OAuth、支付回调时一直失败大部分情况是系统设置里的“回调地址”用的还是服务器内网地址外部服务根本访问不到。回调地址必须是公网可达的HTTPS地址。没有真实域名前可以先临时用IP加端口测试但生产一定要域名。6.7 时区问题如果你看到日志时间比本地时间晚了8小时说明容器没设置TZ环境变量。New-API在部分功能上对用户设置的时区是敏感的。创建容器时加上-e TZAsia/Shanghai重启后日志时间和统计时间就正常了。7. 最后的实际经验体会部署New-API本身并不复杂真正花时间的往往是把网络打通、权限设计好、备份机制建起来。我个人在多次部署中的体会是先用docker run跑通最小实例再逐步过渡到compose和外部依赖是容错率最高的一条路线。还要说一个很多人容易忽略的小技巧升级New-API之前先到GitHub看Release Notes。有一次我升级后某个模型渠道类型变了旧配置不能直接用回滚才解决。所以生产环境升级前一定做好备份并保留上一版镜像的tag不要全依赖latest。这个项目后续还有很多可扩展空间比如多实例部署配合负载均衡、用Redis做分布式限流、接入已有的监控系统都是一步步加上去的。先把基础版本跑稳再按实际需要慢慢扩展是这条路最务实的走法。