logo

轻量AI网关new-api一键部署教程(Windows/Linux/Docker)

作者:渣渣辉2026.11.17 03:20浏览量:0

简介:一条 Docker 命令、几分钟时间,就能把 calciumion/new-api 跑成一个统一的 OpenAI 兼容网关,把多家大模型密钥收拢到一个入口后面。本文给出 Linux、Windows、Docker Compose 三种部署方式、部署后的必做配置、常见故障排查,以及网关搭好之后如何做模型选型与成本控制——如果你还在纠结接哪家的模型、哪家更划算,可以先看看[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article),它提供模型能力查询、价格与性能对比以及统一 API 接入方式,正好和网关的定位互补。

一、先搞清楚:new-api 到底解决什么问题

如果你自己接过模型 API,大概经历过这些麻烦:每家厂商一个 SDK、一套鉴权、一种返回格式;密钥散落在各个项目的环境变量里;某个渠道欠费或限流,业务直接报错;想知道这个月哪个功能烧了多少 Token,只能翻账单。

new-api 是 One API 的二次开发分支,定位是 轻量级 AI 大模型统一网关 :把市面上主流模型服务(OpenAI、Azure、Anthropic Claude、Gemini、百度文心千帆、DeepSeek、各类国内厂商以及 Ollama 等本地推理服务)统一转换成标准 OpenAI 接口格式对外暴露。对上,你的应用只认 POST /v1/chat/completions 一种写法;对下,网关负责密钥托管、渠道分组、加权随机负载均衡、失败自动重试与禁用、按令牌限流、调用日志与额度统计。

相比 One API,new-api 的常见改进集中在界面与接口覆盖面:原生支持 Claude Messages、Gemini 原生协议、Rerank、绘图与异步任务类接口,渠道配置和日志检索的交互也更顺手。对个人开发者、小团队来说,它的价值不是”更强的模型能力”,而是 把多模型这件事的工程复杂度压到接近零 。

二、Linux:Docker 一行命令起步

最推荐的部署方式,装好 Docker 后执行:

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

几个参数的含义:

  • -p 3000:3000:宿主机端口映射,8080 被占用就改成 -p 8080:3000;
  • -v /data/new-api:/data: 这条最重要 ,SQLite 数据库、日志、上传文件都在 /data 里,不挂载卷,容器一删数据全没;
  • --restart always:服务器重启后自动拉起。

启动后访问 http://服务器IP:3000,默认管理员账号 root、初始密码 123456。 第一件事就是改密码 ,因为这个网关里存着你所有上游厂商的密钥,等于把钱包放在了门口。

国内服务器拉镜像慢的话,给 Docker 配置镜像加速器再重试即可;ARM 架构机器(如部分云 ARM 实例、树莓派)建议先到项目 Releases 页确认对应架构的镜像 tag,不要盲目用 latest。

三、Windows:Docker Desktop 或免安装运行

方式一:Docker Desktop(推荐)

在 Windows 上安装 Docker Desktop 并启用 WSL2 后端,然后在 PowerShell 里执行与 Linux 完全相同的命令,只需把挂载路径换成 Windows 路径:

  1. docker run --name new-api -d --restart always `
  2. -p 3000:3000 `
  3. -e TZ=Asia/Shanghai `
  4. -v D:/new-api/data:/data `
  5. calciumion/new-api:latest

方式二:直接运行可执行文件

不想装 Docker 的话,项目 Releases 页面提供 Windows 可执行文件(具体文件名以 Releases 页为准),下载后在 PowerShell 中启动:

  1. .\new-api.exe --port 3000

这种方式数据默认落在同目录的 data 文件夹,注意不要把程序放在 C:\Windows 之类需要管理员权限的目录下,否则写数据库会失败。开机自启可以用任务计划程序配置。

四、进阶:Docker Compose + MySQL + Redis

单机 SQLite 足够个人使用,但如果并发上到几十 QPS、或者你希望多实例共享数据,就该换 MySQL/PostgreSQL 并打开 Redis 缓存:

  1. services:
  2. new-api:
  3. image: calciumion/new-api:latest
  4. container_name: new-api
  5. restart: always
  6. ports:
  7. - "3000:3000"
  8. environment:
  9. - TZ=Asia/Shanghai
  10. - SQL_DSN=root:yourpassword@tcp(mysql:3306)/new-api
  11. - REDIS_CONN_STRING=redis://redis:6379
  12. - MEMORY_CACHE_ENABLED=true
  13. - STREAMING_TIMEOUT=300
  14. volumes:
  15. - ./data:/data
  16. depends_on:
  17. - mysql
  18. - redis
  19. mysql:
  20. image: mysql:8.0
  21. restart: always
  22. environment:
  23. MYSQL_ROOT_PASSWORD: yourpassword
  24. MYSQL_DATABASE: new-api
  25. volumes:
  26. - ./mysql:/var/lib/mysql
  27. redis:
  28. image: redis:7
  29. restart: always

docker compose up -d 即可。从 One API 迁移的话,把旧实例的 one-api.db 或 MySQL 数据交给 new-api 做导入,渠道、令牌、用户和额度都能带过来,迁移前记得先停写、做一份数据库备份。

五、部署完成后必做的 5 件事

  1. 改管理员密码 ,并在「系统设置」里关闭开放注册(除非你确实要做公共服务)。
  2. 建渠道 :点「添加新的渠道」,选择类型、填 Base URL 和密钥、勾选可用模型。以百度智能云千帆为例,渠道类型选「百度文心千帆 V2」,密钥填在千帆控制台新建的 API Key,模型按需保留(如 deepseek-r1、ernie-4.0-turbo),提交后点「测试」确认连通。
  3. 建令牌 :在「令牌」页面创建 key(形如 sk-xxx),按需设置额度上限、过期时间、允许访问的模型与分组。业务代码里只认这个 key,上游真实密钥永远不出网关。
  4. 配好负载均衡与容错 :同一模型建多个渠道并设置不同权重,开启失败重试与自动禁用,单家厂商抖动时业务无感。
  5. 接反向代理 :Nginx 反代时务必关闭缓冲,否则流式输出会被攒成一坨才吐出来:
  1. location / {
  2. proxy_pass http://127.0.0.1:3000;
  3. proxy_http_version 1.1;
  4. proxy_set_header Connection "";
  5. proxy_buffering off;
  6. proxy_cache off;
  7. proxy_read_timeout 600s;
  8. }

安全提醒 :网关持有全部上游密钥,不要裸奔在公网上。至少配好 HTTPS、限制来源 IP 或加一层 Basic Auth,管理后台路径不要对外暴露。

六、客户端怎么接

网关对外就是标准 OpenAI 接口,任何支持自定义 Base URL 的工具都能直接连:

  • API 调用 :Base URL 填 http://你的域名/v1,路径 /chat/completions,密钥填网关生成的令牌。
  • Chatbox :添加自定义提供方,API 域名填网关地址(若直连千帆则为 https://qianfan.baidubce.com/v2),API 路径 /chat/completions,模型名填你在渠道里配置的模型。
  • One API / 其他网关级联 :把 new-api 当作上游渠道再接一层,实现多机房、多租户的分级分发。

七、常见故障排查

现象 常见原因 处理方式
端口无法访问 端口占用 / 安全组未放行 改映射端口,云服务器放行 3000
渠道测试失败 密钥错误、Base URL 多了或少了 /v1、模型名不匹配 先用 curl 直连厂商验证,再回填
401 鉴权失败 用了上游密钥而非网关令牌 客户端统一改用 sk- 开头的令牌
流式输出卡顿后一次性返回 反代开启了缓冲 关闭 proxy_buffering
重启后数据丢失 未挂载 /data 重建容器并挂载卷,从备份恢复
长文本请求超时 网关或反代超时过短 调大 STREAMING_TIMEOUT 与 proxy_read_timeout
日志/额度统计不准 未启用 Redis 或未开启批量更新 配置 Redis,检查计费相关设置

八、网关搭好之后:模型选型和成本才是长期问题

new-api 解决的是”怎么统一调”,但”该调哪个、调一次多少钱”它并不负责。实际项目里,同一类任务往往有多家模型可选,价格可能差出数倍,能力侧重也不同——长上下文、代码、推理、多模态各有强手。这时候更值得做的是先横向比较再落地上游:在词元所的大模型服务平台上可以查询不同模型的能力定位与适用场景,对比调用成本和性能表现,再决定网关里给哪个渠道更高权重。

一个实用的成本优化思路:把请求按难度分层。简单分类、抽取、改写走低价模型;复杂推理、长文档理解走旗舰模型;在网关里用不同令牌分组承载不同业务线,配合日志按模型、按令牌统计 Token 消耗,就能定位到真正烧钱的那个功能点。等用量结构清楚了,再回到百度智能云词元所做统一 API 接入和调用管理,会比一开始就锁死单一厂商更从容。

小结 :docker run 一条命令拿到一个 OpenAI 兼容的多模型入口,Linux 生产环境建议 Compose + MySQL + Redis 并挂载 /data,Windows 用 Docker Desktop 或可执行文件均可;部署后立刻改密码、建渠道、建令牌、配负载均衡与反代。网关负责”统一”,选型和成本控制交给更合适的工具,两者配合才是完整的 AI 基础设施。

发表评论

活动