直接聊结论New-API 是目前管理 AI 大模型接口绕不开的一个开源项目。它把 OpenAI、Claude、Gemini、DeepSeek、智谱、通义这类几十家模型渠道集中到一个面板里统一管理你要做的只是在后台添加渠道、生成令牌然后所有客户端拿着同一个 base_url 和一个令牌去请求就行。不用再每个项目单独配 Key额度、倍率、日志、分组全都能在一个界面里看明白。这篇文章不扯虚的专门讲怎么把 New-API 跑起来。默认你至少听过 Docker但不要求精通。我会把在线和离线两套方案完整写出来包括 MySQL 的配置细节、docker-compose 怎么写、镜像怎么导出导入、内网机器怎么装、渠道和令牌怎么配最后附上我踩过的坑和排查思路。无论是自己折腾玩还是帮公司内网搭一套统一网关这篇文章都够用。1. 先搞清楚 New-API 到底在解决什么问题1.1 一句话解释 New-API 是什么New-API 是开源项目 one-api 的一个深度二次开发分支本质上是一个 API 网关加管理系统。你手头可能有好几个模型平台的 Key比如 OpenAI 的、Claude 的、国产模型的分散在各个账号里。开发的时候每种模型都要单独接 SDK测试的时候每个 Key 都要单独配环境变量对账的时候更是全靠手工非常痛苦。New-API 的做法很直接把后端所有渠道统一接进来对外只暴露一个 OpenAI 兼容接口。也就是说不管你后端接的是哪家模型客户端永远只需要知道一个地址加一个令牌。这个思路相当于给所有模型接口装了一个交换机所有请求先到交换机再由它转发到真正的上游渠道。1.2 部署方案选型为什么是 Docker MySQLNew-API 本身是个 Go 项目发布物是一个单一二进制文件理论上直接跑二进制也能启动。但实际部署我几乎无脑选 Docker原因有三点。第一环境隔离。Go 项目虽然静态编译但跑起来还是要考虑系统依赖、端口占用、日志目录权限这些问题。Docker 容器里面一把梭宿主机只需要有 Docker 环境。第二版本管理方便。镜像标签对应版本号升级就是拉新镜像重启容器回滚就是重新指定旧标签。这对生产环境来说太重要了我在线上升级翻车过直接改回旧镜像秒恢复。第三离线部署友好。内网机器不能访问公网的情况下二进制方案需要手动带上一堆依赖Docker 镜像只需要 docker save 带进去即可后面第三节单独讲。数据库选型这里要稍微展开一下。New-API 默认支持 SQLite单机自己玩直接 SQLite 足够。但只要是正经使用场景比如多个人共用、数据量大、需要定时备份我建议一步到位上 MySQL。原因也很现实SQLite 在并发写入时会有锁竞争日志表数据量大了之后读写都会变慢而且备份恢复不方便。MySQL 8.0 用 Docker 启动也就一两分钟的事没有理由不选。我遇到过一些朋友图省事直接 SQLite结果跑了一个月请求日志几万条后台页面打开都有延迟。换 MySQL 之后体感完全不一样。所以这篇文章的默认方案就是 MySQL 8.0 New-API 最新稳定版两个容器通过 Docker Compose 统一编排。2. 在线环境部署从拉取镜像到首次启动2.1 部署前的环境检查清单在线部署看着简单但很多人一上来就 docker compose up -d然后报一堆错其实大部分问题出在准备工作上。我建议先把以下三项检查做完再动手。Docker 版本。New-API 镜像基于 Linux 容器对 Docker 版本要求不高但 Docker Compose 插件请确保存在。新版 Docker Desktop 默认自带 compose 插件可以用 docker compose version 确认。如果是老版本可能需要单独安装 docker-compose。端口占用情况。New-API 默认监听 3000 端口MySQL 默认 3306 端口。这两个端口如果被其他程序占了容器会起不来或者端口映射失败。启动之前先跑一下lsof -i :3000 lsof -i :3306如果有输出说明端口被占用需要先停掉对应进程或者后面改端口映射。磁盘空间。镜像本身加起来一两个 GBMySQL 的数据文件会随使用时间增长日志表如果开了记录功能增长更快。建议至少预留 20GB 空间避免运行两个月后磁盘写满导致 MySQL 崩溃。这个坑我踩过磁盘满了之后 MySQL 容器直接进入只读模式查了半天才发现是硬盘满了。2.2 编写 docker-compose.yml每个参数都说清楚新建一个工作目录比如 ~/new-api在里面创建 docker-compose.yml。下面这份配置我实测可跑直接抄作业没问题version: 3.8 services: mysql: image: mysql:8.0 container_name: newapi-mysql restart: always environment: MYSQL_ROOT_PASSWORD: change_me_root_password MYSQL_DATABASE: newapi MYSQL_USER: newapi MYSQL_PASSWORD: change_me_db_password volumes: - ./mysql-data:/var/lib/mysql ports: - 3306:3306 command: --default-authentication-pluginmysql_native_password new-api: image: calciumion/new-api:latest container_name: new-api restart: always depends_on: - mysql environment: SQL_DSN: newapi:change_me_db_passwordtcp(mysql:3306)/newapi?charsetutf8mb4parseTimeTruelocLocal TZ: Asia/Shanghai ports: - 3000:3000 volumes: - ./new-api-logs:/app/logs这里有几个关键点需要解释清楚。SQL_DSN 是 New-API 连接 MySQL 的核心配置格式是 用户名:密码tcp(数据库容器名:端口)/数据库名?参数。其中 mysql 不是 IP而是 Docker Compose 网络内的服务名Compose 会自动做 DNS 解析所以 new-api 容器里可以直接通过 mysql 这个主机名连到 MySQL 容器。如果你手动分开启动容器这个位置就要改成 MySQL 所在机器的 IP。charsetutf8mb4 必须保留。MySQL 8 默认字符集虽然是 utf8mb4但连接串里显式指定可以避免某些驱动默认使用 latin1 导致中文和 emoji 乱码。AI 接口返回的内容里经常有各种特殊符号这一行省掉后面必定后悔。default-authentication-pluginmysql_native_password 是给 MySQL 8.0 加的兼容参数。MySQL 8 默认的 caching_sha2_password 认证方式在部分旧版客户端和驱动下会有兼容问题显式指定 native 认证最省心。如果你用 MySQL 5.7这一行不需要加。端口映射这里3306 端口要不要暴露给宿主机需要想清楚。如果只是 New-API 容器内部连数据库其实不需要映射 3306可以把 ports 删掉只留 internal。但为了方便用 Navicat 之类的工具连进去看数据、排查问题我建议还是暴露出来生产环境再按需收紧。2.3 启动容器并验证服务状态配置写好之后切换到 docker-compose.yml 所在目录执行docker compose up -d第一次执行会拉取两个镜像网络正常情况下几分钟内完成。之后用 docker compose ps 查看状态两个容器都应该是 Up 状态。接着验证 New-API 是否正常监听curl http://localhost:3000/api/status如果返回一段 JSON里面有 success 和 version 字段说明服务已经起来了。此时打开浏览器访问 http://服务器IP:3000会看到 New-API 的登录页面。第一次访问时页面会提示注册第一个注册的账号会自动成为管理员。这一步很多人忽略以为注册完就是个普通用户后来要改系统设置找不到入口。务必记住第一个注册的人就是管理员。MySQL 这边的验证也很重要不要等到日志写满才发现连不上。进入容器确认数据库和账号是否正常docker exec -it newapi-mysql mysql -unewapi -pchange_me_db_password -e SHOW DATABASES;能看到 newapi 这个库就说明数据库侧没问题。到这里在线部署的核心流程已经走完比想象中简单。3. 离线环境部署内网机器也能一键跑起来3.1 离线部署的整体思路内网部署最大的问题是环境隔离机器不能访问外网docker pull 拉不了镜像docker compose up 直接卡死在拉取阶段。但思路其实很简单在一台能联网的机器上把需要的镜像和安装包全部准备好再通过 U 盘或内网文件服务器拷贝到目标机器上。具体要准备三样东西New-API 镜像、MySQL 镜像、Docker 安装包。如果你是 Windows 内网机器可能还要准备 Docker Desktop 安装包。离线环境里最先要解决的问题不是镜像而是 Docker 本身。目标机器没有 Docker 的话镜像再齐全也白搭。3.2 在联网机器上导出镜像和下载安装包先准备镜像文件。在任意一台能联网、装有 Docker 的机器上执行docker pull mysql:8.0 docker pull calciumion/new-api:latest docker save -o mysql-8.0.tar mysql:8.0 docker save -o new-api.tar calciumion/new-api:latest这里有个细节docker save 和 docker export 的区别。save 保存的是镜像的完整结构包括层信息、标签、启动配置load 回来之后可以直接用原标签启动。export 是导出容器的文件系统相当于把运行中的容器打包成一个普通文件load 回来还需要手动配置启动参数。离线部署一定要用 save load不要用 export。Docker 安装包方面Linux 机器建议下载官方静态二进制包比如 docker-27.x.x.tgz解压后放到 /usr/local/bin 就能用不依赖系统包管理器。Ubuntu/Debian 机器也可以下载对应的 deb 包但静态二进制更省事一个包拷贝过去解压就行。如果目标机器是 Windows情况复杂一些。Docker Desktop 的安装包是 exe 格式直接拷贝过去双击安装即可。但 Windows 上跑 Docker 依赖 WSL2 或者 Hyper-V目标机器需要在 BIOS 里开启虚拟化支持。这一步在离线环境里如果没提前确认很容易卡住。下面会详细说。3.3 目标机器导入镜像并启动以常见的内网 Linux 服务器为例。先把 Docker 安装好tar -xzf docker-27.x.x.tgz cp docker/* /usr/local/bin/然后启动 Docker 守护进程。用 systemd 管理的机器可以直接写一个 service 文件或者简单点直接后台执行 dockerd。验证一下docker version能正常输出版本号就说明 Docker 环境就绪。接下来把镜像文件上传到目标机器执行导入docker load -i mysql-8.0.tar docker load -i new-api.tar导入完成后用 docker images 确认两个镜像标签是否正确。镜像没问题之后把 2.2 节那份 docker-compose.yml 原样拷贝过去所有的环境变量保持不变然后 docker compose up -d。这里要注意一点离线机器上 Docker Compose 插件可能不存在。如果 docker compose 命令报错先装 compose 插件或者直接把两个容器用 docker run 手动启动。手动启动的命令如下效果和 compose 一样docker network create newapi-network docker run -d --name newapi-mysql \ --network newapi-network \ -e MYSQL_ROOT_PASSWORDchange_me_root_password \ -e MYSQL_DATABASEnewapi \ -e MYSQL_USERnewapi \ -e MYSQL_PASSWORDchange_me_db_password \ -v $(pwd)/mysql-data:/var/lib/mysql \ --restart always \ mysql:8.0 --default-authentication-pluginmysql_native_password docker run -d --name new-api \ --network newapi-network \ -e SQL_DSNnewapi:change_me_db_passwordtcp(newapi-mysql:3306)/newapi?charsetutf8mb4parseTimeTruelocLocal \ -e TZAsia/Shanghai \ -p 3000:3000 \ -v $(pwd)/new-api-logs:/app/logs \ --restart always \ calciumion/new-api:latest注意网络一定要自己创建并把两个容器放到同一个网络里否则 new-api 容器解析不到 newapi-mysql 这个主机名。Windows 离线部署多说一句。安装 Docker Desktop 时如果提示 virtualization support not detected先重启进 BIOS 打开 Intel VT-x 或 AMD-V。有些办公电脑出厂默认关闭虚拟化这是离线部署最常见的卡点。另外 Docker Desktop 首次启动会初始化 WSL2 内核这个组件在离线环境也需要提前下载好 wsl_update_x64.msi 并安装否则 Docker Desktop 会一直卡在 starting 界面。3.4 离线环境下的版本选择和依赖陷阱离线部署有个容易被忽略的问题镜像版本一旦固定后面想升级就得重新走一遍 save 和 load 流程。所以离线环境一定要选择稳定的版本不要用 latest 标签。latest 是指向最新版的动态标签你在一台机器上 pull 到的 latest 和另一台机器上 pull 到的可能是不同版本这会导致离线环境复现困难。建议的做法是在联网机器上先 docker images 查看镜像的完整 ID然后再 docker tag 打一个明确版本的标签docker tag calciumion/new-api:latest calciumion/new-api:v0.1.0 docker save -o new-api-v0.1.0.tar calciumion/new-api:v0.1.0这样离线机器上导入的镜像就有明确的版本号标记后续排查问题也知道自己在跑哪个版本。另外要注意MySQL 镜像的数据目录版本敏感。同一套 mysql-data 目录在 MySQL 8.0 不同小版本之间基本能兼容但如果你原来用的是 MySQL 5.7想升级到 8.0直接挂载旧数据目录会报错。离线升级数据库这类操作一定要先备份数据再用 mysqldump 导出再导入不要直接替换数据目录。4. 初始化配置渠道、令牌、模型一个都不能少4.1 登录后台先做这三件事部署完成后打开浏览器进入后台第一步是注册管理员账号。注意这个页面的注册不像普通网站是开放给所有人的第一个注册的账号自动成为管理员拥有全部权限。我用 New-API 搭建过好几个环境这个坑几乎每次都有人踩注册完发现自己是普通用户后台很多菜单看不到必须手动修改数据库或重新部署才能解决。登录进去之后先不要急着加渠道按顺序处理以下几项。第一在设置-运营设置里修改系统名称和站点地址站点地址影响分享链接和部分回调功能。第二在设置-模型设置里确认是否启用模型映射默认值按需调整。第三顺手把系统管理员的密码改掉或者绑定邮箱避免初始密码遗忘导致进不去后台。注意如果是内网部署站点地址建议直接写内网访问地址比如 http://192.168.1.100:3000。写公网地址反而会让后端生成的链接在内网环境不可访问。4.2 添加渠道以 OpenAI 兼容接口为例这是核心操作。点击左侧渠道菜单然后添加渠道会看到一个渠道配置表单。以国内最常见的 OpenAI 兼容第三方平台为例类型选 OpenAI名称随便填比如某某中转代理地址填第三方平台提供的 base_url注意结尾不要带 /v1密钥填你在第三方平台申请的 API Key模型列表填该渠道支持的模型名逗号分隔比如 gpt-4o,gpt-4o-mini,claude-3-5-sonnet填写完之后点测试系统会发一个测试请求过去。如果返回正常说明渠道连通。如果测试失败大概率是以下三个原因代理地址格式不对尾部多了 /v1密钥里带了多余的空格或其他不可见字符模型名和渠道侧实际支持的名称不一致。我自己在配渠道时踩过最典型的坑是代理地址问题。有些平台文档里写的是 https://api.xxx.com/v1New-API 表单里也要求填 base_url不填 /v1两者叠加导致请求路径变成 https://api.xxx.com/v1/v1/chat/completions必然 404。理解了这个机制以后不管对接什么平台都不会再犯。4.3 创建令牌并接入客户端渠道配好后还要创建一个令牌才能真正对外提供服务。在令牌菜单里添加令牌设置好额度倍率比如 1 表示按原价 1 倍计费不限模型的话模型倍数留空即可。令牌生成之后会显示一串 sk- 开头的字符串这个就是客户端要用的 API Key。客户端接入时base_url 填写 New-API 的地址加 /v1比如 http://192.168.1.100:3000/v1api_key 填写刚才生成的令牌。以 Python 的 openai 库为例from openai import OpenAI client OpenAI( api_keysk-你的令牌, base_urlhttp://192.168.1.100:3000/v1 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)请求发出后去 New-API 后台的日志菜单里查看记录。能看到请求详情、消耗额度、响应耗时说明整条链路已经打通。到这一步New-API 的核心部署和接入流程就算真正完成了。5. 常见问题与排查技巧实录5.1 容器一直重启日志刷屏新部署的环境最常见的问题就是 new-api 容器起来了又挂循环重启。先看日志docker logs new-api --tail 200如果日志里出现 failed to connect to database 或 access denied说明 SQL_DSN 连接串有问题。重点检查数据库密码是否正确、MySQL 容器是否有 newapi 这个库、用户名是否有权限。如果想快速验证可以进 MySQL 容器手动用连接串里的账号密码登录一下能登录说明数据库侧没问题问题大概率出在环境变量转义上。SQL_DSN 里密码如果包含特殊字符比如 、:、/ 等需要做 URL 编码否则连接串解析会错位。我建议部署时直接用纯字母数字的密码省去转义的麻烦。数据库密码这种内部系统的密码也没有必要设置过分复杂不暴露公网就行。5.2 日志表增长过快导致数据库膨胀New-API 默认会记录所有请求日志高并发环境下日志表增长非常快。我跑过一个日请求量上万的环境没做任何处理一个月后数据库占了 40 多 GB。后台设置-日志设置里可以配置日志保留天数建议按需设置 7 到 30 天把超期日志自动清理打开。如果日志已经膨胀得很厉害可以直接去 MySQL 里手动清理docker exec -it newapi-mysql mysql -unewapi -pchange_me_db_password newapi -e DELETE FROM logs WHERE created_at DATE_SUB(NOW(), INTERVAL 7 DAY);清理之后执行 OPTIMIZE TABLE logs 释放表空间。这个操作在线环境不会有太大影响但建议在低峰期执行。5.3 渠道测试通过但客户端请求报 404这个问题的根源几乎都是 base_url 路径不对。客户端请求经历的过程是客户端访问 New-API 的 /v1/chat/completionsNew-API 再请求上游渠道的对应路径。如果客户端 base_url 写成了 http://ip:3000没带 /v1请求会打到 New-API 的根路径而不是 OpenAI 兼容接口路径自然 404。另外如果你用的是 One API 生态的其他客户端比如某些开源前端项目注意区分它期望的 base_url 是带 /v1 还是不带。以 New-API 为例兼容 OpenAI 协议的统一都是 base_url 加 /v1。这一条记住就不用反复试错了。5.4 问题排查速查表现象可能原因处理方式容器一直重启SQL_DSN 连接串错误检查密码、数据库名、特殊字符转义端口无法访问容器没起来或端口映射不对docker compose ps 查看状态宿主机防火墙放行 3000后台日志空白渠道配置错误或密钥无效渠道页点测试看具体报错信息请求报 401令牌错误或已过期重新生成令牌确认客户端填的是令牌而非渠道密钥数据库连接超时MySQL 容器内存不足查看 docker stats增加宿主机内存或限制 MySQL 内存参数页面加载慢请求日志表过大清理日志配置自动留存天数离线导入镜像报错用的是 export 导出文件必须用 docker save docker load5.5 容器内时区问题的处理部署在内网或云服务器上如果宿主机的时区不是 Asia/ShanghaiNew-API 后台显示的时间可能跟本地时间差好几个小时。解决方式就是 compose 文件里那两个环境变量 TZAsia/Shanghai 和 MySQL 连接串里的 locLocal缺一不可。MySQL 容器里也需要同步设置时区可以在 environment 里加 TZAsia/Shanghai或者在 MySQL 配置里指定 default-time-zone 08:00。5.6 Docker 侧的内存和重启策略New-API 作为常驻服务restart: always 是必须的否则机器重启后服务不会自动拉起。内存方面New-API 本身占用很小200MB 以内但 MySQL 8.0 默认内存占用偏大1G 内存的小机器跑起来会有点吃力。如果 VPS 内存只有 1G建议给 MySQL 容器加内存限制deploy: resources: limits: memory: 512M不过要注意限制过小会导致 MySQL 频繁 OOM。生产环境优先保证 2G 以上内存小内存机器能用但体验不好。最后分享一个我的习惯每次配置文件改完、容器启动成功之后先把 docker-compose.yml 复制一份到备份目录。这个文件本身就是项目的一个核心交付物丢了就得重新回忆所有配置。另外 MySQL 数据目录 mysql-data 也建议定期压缩备份用 cron 脚本每天打一次 tar 包成本很低但崩溃恢复时能救命。踩过几次数据目录损坏的坑之后我才意识到配置文件和数据的备份和大模型网关本身一样重要。
New-API部署实战：用Docker+MySQL统一管理AI大模型接口
直接聊结论New-API 是目前管理 AI 大模型接口绕不开的一个开源项目。它把 OpenAI、Claude、Gemini、DeepSeek、智谱、通义这类几十家模型渠道集中到一个面板里统一管理你要做的只是在后台添加渠道、生成令牌然后所有客户端拿着同一个 base_url 和一个令牌去请求就行。不用再每个项目单独配 Key额度、倍率、日志、分组全都能在一个界面里看明白。这篇文章不扯虚的专门讲怎么把 New-API 跑起来。默认你至少听过 Docker但不要求精通。我会把在线和离线两套方案完整写出来包括 MySQL 的配置细节、docker-compose 怎么写、镜像怎么导出导入、内网机器怎么装、渠道和令牌怎么配最后附上我踩过的坑和排查思路。无论是自己折腾玩还是帮公司内网搭一套统一网关这篇文章都够用。1. 先搞清楚 New-API 到底在解决什么问题1.1 一句话解释 New-API 是什么New-API 是开源项目 one-api 的一个深度二次开发分支本质上是一个 API 网关加管理系统。你手头可能有好几个模型平台的 Key比如 OpenAI 的、Claude 的、国产模型的分散在各个账号里。开发的时候每种模型都要单独接 SDK测试的时候每个 Key 都要单独配环境变量对账的时候更是全靠手工非常痛苦。New-API 的做法很直接把后端所有渠道统一接进来对外只暴露一个 OpenAI 兼容接口。也就是说不管你后端接的是哪家模型客户端永远只需要知道一个地址加一个令牌。这个思路相当于给所有模型接口装了一个交换机所有请求先到交换机再由它转发到真正的上游渠道。1.2 部署方案选型为什么是 Docker MySQLNew-API 本身是个 Go 项目发布物是一个单一二进制文件理论上直接跑二进制也能启动。但实际部署我几乎无脑选 Docker原因有三点。第一环境隔离。Go 项目虽然静态编译但跑起来还是要考虑系统依赖、端口占用、日志目录权限这些问题。Docker 容器里面一把梭宿主机只需要有 Docker 环境。第二版本管理方便。镜像标签对应版本号升级就是拉新镜像重启容器回滚就是重新指定旧标签。这对生产环境来说太重要了我在线上升级翻车过直接改回旧镜像秒恢复。第三离线部署友好。内网机器不能访问公网的情况下二进制方案需要手动带上一堆依赖Docker 镜像只需要 docker save 带进去即可后面第三节单独讲。数据库选型这里要稍微展开一下。New-API 默认支持 SQLite单机自己玩直接 SQLite 足够。但只要是正经使用场景比如多个人共用、数据量大、需要定时备份我建议一步到位上 MySQL。原因也很现实SQLite 在并发写入时会有锁竞争日志表数据量大了之后读写都会变慢而且备份恢复不方便。MySQL 8.0 用 Docker 启动也就一两分钟的事没有理由不选。我遇到过一些朋友图省事直接 SQLite结果跑了一个月请求日志几万条后台页面打开都有延迟。换 MySQL 之后体感完全不一样。所以这篇文章的默认方案就是 MySQL 8.0 New-API 最新稳定版两个容器通过 Docker Compose 统一编排。2. 在线环境部署从拉取镜像到首次启动2.1 部署前的环境检查清单在线部署看着简单但很多人一上来就 docker compose up -d然后报一堆错其实大部分问题出在准备工作上。我建议先把以下三项检查做完再动手。Docker 版本。New-API 镜像基于 Linux 容器对 Docker 版本要求不高但 Docker Compose 插件请确保存在。新版 Docker Desktop 默认自带 compose 插件可以用 docker compose version 确认。如果是老版本可能需要单独安装 docker-compose。端口占用情况。New-API 默认监听 3000 端口MySQL 默认 3306 端口。这两个端口如果被其他程序占了容器会起不来或者端口映射失败。启动之前先跑一下lsof -i :3000 lsof -i :3306如果有输出说明端口被占用需要先停掉对应进程或者后面改端口映射。磁盘空间。镜像本身加起来一两个 GBMySQL 的数据文件会随使用时间增长日志表如果开了记录功能增长更快。建议至少预留 20GB 空间避免运行两个月后磁盘写满导致 MySQL 崩溃。这个坑我踩过磁盘满了之后 MySQL 容器直接进入只读模式查了半天才发现是硬盘满了。2.2 编写 docker-compose.yml每个参数都说清楚新建一个工作目录比如 ~/new-api在里面创建 docker-compose.yml。下面这份配置我实测可跑直接抄作业没问题version: 3.8 services: mysql: image: mysql:8.0 container_name: newapi-mysql restart: always environment: MYSQL_ROOT_PASSWORD: change_me_root_password MYSQL_DATABASE: newapi MYSQL_USER: newapi MYSQL_PASSWORD: change_me_db_password volumes: - ./mysql-data:/var/lib/mysql ports: - 3306:3306 command: --default-authentication-pluginmysql_native_password new-api: image: calciumion/new-api:latest container_name: new-api restart: always depends_on: - mysql environment: SQL_DSN: newapi:change_me_db_passwordtcp(mysql:3306)/newapi?charsetutf8mb4parseTimeTruelocLocal TZ: Asia/Shanghai ports: - 3000:3000 volumes: - ./new-api-logs:/app/logs这里有几个关键点需要解释清楚。SQL_DSN 是 New-API 连接 MySQL 的核心配置格式是 用户名:密码tcp(数据库容器名:端口)/数据库名?参数。其中 mysql 不是 IP而是 Docker Compose 网络内的服务名Compose 会自动做 DNS 解析所以 new-api 容器里可以直接通过 mysql 这个主机名连到 MySQL 容器。如果你手动分开启动容器这个位置就要改成 MySQL 所在机器的 IP。charsetutf8mb4 必须保留。MySQL 8 默认字符集虽然是 utf8mb4但连接串里显式指定可以避免某些驱动默认使用 latin1 导致中文和 emoji 乱码。AI 接口返回的内容里经常有各种特殊符号这一行省掉后面必定后悔。default-authentication-pluginmysql_native_password 是给 MySQL 8.0 加的兼容参数。MySQL 8 默认的 caching_sha2_password 认证方式在部分旧版客户端和驱动下会有兼容问题显式指定 native 认证最省心。如果你用 MySQL 5.7这一行不需要加。端口映射这里3306 端口要不要暴露给宿主机需要想清楚。如果只是 New-API 容器内部连数据库其实不需要映射 3306可以把 ports 删掉只留 internal。但为了方便用 Navicat 之类的工具连进去看数据、排查问题我建议还是暴露出来生产环境再按需收紧。2.3 启动容器并验证服务状态配置写好之后切换到 docker-compose.yml 所在目录执行docker compose up -d第一次执行会拉取两个镜像网络正常情况下几分钟内完成。之后用 docker compose ps 查看状态两个容器都应该是 Up 状态。接着验证 New-API 是否正常监听curl http://localhost:3000/api/status如果返回一段 JSON里面有 success 和 version 字段说明服务已经起来了。此时打开浏览器访问 http://服务器IP:3000会看到 New-API 的登录页面。第一次访问时页面会提示注册第一个注册的账号会自动成为管理员。这一步很多人忽略以为注册完就是个普通用户后来要改系统设置找不到入口。务必记住第一个注册的人就是管理员。MySQL 这边的验证也很重要不要等到日志写满才发现连不上。进入容器确认数据库和账号是否正常docker exec -it newapi-mysql mysql -unewapi -pchange_me_db_password -e SHOW DATABASES;能看到 newapi 这个库就说明数据库侧没问题。到这里在线部署的核心流程已经走完比想象中简单。3. 离线环境部署内网机器也能一键跑起来3.1 离线部署的整体思路内网部署最大的问题是环境隔离机器不能访问外网docker pull 拉不了镜像docker compose up 直接卡死在拉取阶段。但思路其实很简单在一台能联网的机器上把需要的镜像和安装包全部准备好再通过 U 盘或内网文件服务器拷贝到目标机器上。具体要准备三样东西New-API 镜像、MySQL 镜像、Docker 安装包。如果你是 Windows 内网机器可能还要准备 Docker Desktop 安装包。离线环境里最先要解决的问题不是镜像而是 Docker 本身。目标机器没有 Docker 的话镜像再齐全也白搭。3.2 在联网机器上导出镜像和下载安装包先准备镜像文件。在任意一台能联网、装有 Docker 的机器上执行docker pull mysql:8.0 docker pull calciumion/new-api:latest docker save -o mysql-8.0.tar mysql:8.0 docker save -o new-api.tar calciumion/new-api:latest这里有个细节docker save 和 docker export 的区别。save 保存的是镜像的完整结构包括层信息、标签、启动配置load 回来之后可以直接用原标签启动。export 是导出容器的文件系统相当于把运行中的容器打包成一个普通文件load 回来还需要手动配置启动参数。离线部署一定要用 save load不要用 export。Docker 安装包方面Linux 机器建议下载官方静态二进制包比如 docker-27.x.x.tgz解压后放到 /usr/local/bin 就能用不依赖系统包管理器。Ubuntu/Debian 机器也可以下载对应的 deb 包但静态二进制更省事一个包拷贝过去解压就行。如果目标机器是 Windows情况复杂一些。Docker Desktop 的安装包是 exe 格式直接拷贝过去双击安装即可。但 Windows 上跑 Docker 依赖 WSL2 或者 Hyper-V目标机器需要在 BIOS 里开启虚拟化支持。这一步在离线环境里如果没提前确认很容易卡住。下面会详细说。3.3 目标机器导入镜像并启动以常见的内网 Linux 服务器为例。先把 Docker 安装好tar -xzf docker-27.x.x.tgz cp docker/* /usr/local/bin/然后启动 Docker 守护进程。用 systemd 管理的机器可以直接写一个 service 文件或者简单点直接后台执行 dockerd。验证一下docker version能正常输出版本号就说明 Docker 环境就绪。接下来把镜像文件上传到目标机器执行导入docker load -i mysql-8.0.tar docker load -i new-api.tar导入完成后用 docker images 确认两个镜像标签是否正确。镜像没问题之后把 2.2 节那份 docker-compose.yml 原样拷贝过去所有的环境变量保持不变然后 docker compose up -d。这里要注意一点离线机器上 Docker Compose 插件可能不存在。如果 docker compose 命令报错先装 compose 插件或者直接把两个容器用 docker run 手动启动。手动启动的命令如下效果和 compose 一样docker network create newapi-network docker run -d --name newapi-mysql \ --network newapi-network \ -e MYSQL_ROOT_PASSWORDchange_me_root_password \ -e MYSQL_DATABASEnewapi \ -e MYSQL_USERnewapi \ -e MYSQL_PASSWORDchange_me_db_password \ -v $(pwd)/mysql-data:/var/lib/mysql \ --restart always \ mysql:8.0 --default-authentication-pluginmysql_native_password docker run -d --name new-api \ --network newapi-network \ -e SQL_DSNnewapi:change_me_db_passwordtcp(newapi-mysql:3306)/newapi?charsetutf8mb4parseTimeTruelocLocal \ -e TZAsia/Shanghai \ -p 3000:3000 \ -v $(pwd)/new-api-logs:/app/logs \ --restart always \ calciumion/new-api:latest注意网络一定要自己创建并把两个容器放到同一个网络里否则 new-api 容器解析不到 newapi-mysql 这个主机名。Windows 离线部署多说一句。安装 Docker Desktop 时如果提示 virtualization support not detected先重启进 BIOS 打开 Intel VT-x 或 AMD-V。有些办公电脑出厂默认关闭虚拟化这是离线部署最常见的卡点。另外 Docker Desktop 首次启动会初始化 WSL2 内核这个组件在离线环境也需要提前下载好 wsl_update_x64.msi 并安装否则 Docker Desktop 会一直卡在 starting 界面。3.4 离线环境下的版本选择和依赖陷阱离线部署有个容易被忽略的问题镜像版本一旦固定后面想升级就得重新走一遍 save 和 load 流程。所以离线环境一定要选择稳定的版本不要用 latest 标签。latest 是指向最新版的动态标签你在一台机器上 pull 到的 latest 和另一台机器上 pull 到的可能是不同版本这会导致离线环境复现困难。建议的做法是在联网机器上先 docker images 查看镜像的完整 ID然后再 docker tag 打一个明确版本的标签docker tag calciumion/new-api:latest calciumion/new-api:v0.1.0 docker save -o new-api-v0.1.0.tar calciumion/new-api:v0.1.0这样离线机器上导入的镜像就有明确的版本号标记后续排查问题也知道自己在跑哪个版本。另外要注意MySQL 镜像的数据目录版本敏感。同一套 mysql-data 目录在 MySQL 8.0 不同小版本之间基本能兼容但如果你原来用的是 MySQL 5.7想升级到 8.0直接挂载旧数据目录会报错。离线升级数据库这类操作一定要先备份数据再用 mysqldump 导出再导入不要直接替换数据目录。4. 初始化配置渠道、令牌、模型一个都不能少4.1 登录后台先做这三件事部署完成后打开浏览器进入后台第一步是注册管理员账号。注意这个页面的注册不像普通网站是开放给所有人的第一个注册的账号自动成为管理员拥有全部权限。我用 New-API 搭建过好几个环境这个坑几乎每次都有人踩注册完发现自己是普通用户后台很多菜单看不到必须手动修改数据库或重新部署才能解决。登录进去之后先不要急着加渠道按顺序处理以下几项。第一在设置-运营设置里修改系统名称和站点地址站点地址影响分享链接和部分回调功能。第二在设置-模型设置里确认是否启用模型映射默认值按需调整。第三顺手把系统管理员的密码改掉或者绑定邮箱避免初始密码遗忘导致进不去后台。注意如果是内网部署站点地址建议直接写内网访问地址比如 http://192.168.1.100:3000。写公网地址反而会让后端生成的链接在内网环境不可访问。4.2 添加渠道以 OpenAI 兼容接口为例这是核心操作。点击左侧渠道菜单然后添加渠道会看到一个渠道配置表单。以国内最常见的 OpenAI 兼容第三方平台为例类型选 OpenAI名称随便填比如某某中转代理地址填第三方平台提供的 base_url注意结尾不要带 /v1密钥填你在第三方平台申请的 API Key模型列表填该渠道支持的模型名逗号分隔比如 gpt-4o,gpt-4o-mini,claude-3-5-sonnet填写完之后点测试系统会发一个测试请求过去。如果返回正常说明渠道连通。如果测试失败大概率是以下三个原因代理地址格式不对尾部多了 /v1密钥里带了多余的空格或其他不可见字符模型名和渠道侧实际支持的名称不一致。我自己在配渠道时踩过最典型的坑是代理地址问题。有些平台文档里写的是 https://api.xxx.com/v1New-API 表单里也要求填 base_url不填 /v1两者叠加导致请求路径变成 https://api.xxx.com/v1/v1/chat/completions必然 404。理解了这个机制以后不管对接什么平台都不会再犯。4.3 创建令牌并接入客户端渠道配好后还要创建一个令牌才能真正对外提供服务。在令牌菜单里添加令牌设置好额度倍率比如 1 表示按原价 1 倍计费不限模型的话模型倍数留空即可。令牌生成之后会显示一串 sk- 开头的字符串这个就是客户端要用的 API Key。客户端接入时base_url 填写 New-API 的地址加 /v1比如 http://192.168.1.100:3000/v1api_key 填写刚才生成的令牌。以 Python 的 openai 库为例from openai import OpenAI client OpenAI( api_keysk-你的令牌, base_urlhttp://192.168.1.100:3000/v1 ) resp client.chat.completions.create( modelgpt-4o, messages[{role: user, content: 你好}] ) print(resp.choices[0].message.content)请求发出后去 New-API 后台的日志菜单里查看记录。能看到请求详情、消耗额度、响应耗时说明整条链路已经打通。到这一步New-API 的核心部署和接入流程就算真正完成了。5. 常见问题与排查技巧实录5.1 容器一直重启日志刷屏新部署的环境最常见的问题就是 new-api 容器起来了又挂循环重启。先看日志docker logs new-api --tail 200如果日志里出现 failed to connect to database 或 access denied说明 SQL_DSN 连接串有问题。重点检查数据库密码是否正确、MySQL 容器是否有 newapi 这个库、用户名是否有权限。如果想快速验证可以进 MySQL 容器手动用连接串里的账号密码登录一下能登录说明数据库侧没问题问题大概率出在环境变量转义上。SQL_DSN 里密码如果包含特殊字符比如 、:、/ 等需要做 URL 编码否则连接串解析会错位。我建议部署时直接用纯字母数字的密码省去转义的麻烦。数据库密码这种内部系统的密码也没有必要设置过分复杂不暴露公网就行。5.2 日志表增长过快导致数据库膨胀New-API 默认会记录所有请求日志高并发环境下日志表增长非常快。我跑过一个日请求量上万的环境没做任何处理一个月后数据库占了 40 多 GB。后台设置-日志设置里可以配置日志保留天数建议按需设置 7 到 30 天把超期日志自动清理打开。如果日志已经膨胀得很厉害可以直接去 MySQL 里手动清理docker exec -it newapi-mysql mysql -unewapi -pchange_me_db_password newapi -e DELETE FROM logs WHERE created_at DATE_SUB(NOW(), INTERVAL 7 DAY);清理之后执行 OPTIMIZE TABLE logs 释放表空间。这个操作在线环境不会有太大影响但建议在低峰期执行。5.3 渠道测试通过但客户端请求报 404这个问题的根源几乎都是 base_url 路径不对。客户端请求经历的过程是客户端访问 New-API 的 /v1/chat/completionsNew-API 再请求上游渠道的对应路径。如果客户端 base_url 写成了 http://ip:3000没带 /v1请求会打到 New-API 的根路径而不是 OpenAI 兼容接口路径自然 404。另外如果你用的是 One API 生态的其他客户端比如某些开源前端项目注意区分它期望的 base_url 是带 /v1 还是不带。以 New-API 为例兼容 OpenAI 协议的统一都是 base_url 加 /v1。这一条记住就不用反复试错了。5.4 问题排查速查表现象可能原因处理方式容器一直重启SQL_DSN 连接串错误检查密码、数据库名、特殊字符转义端口无法访问容器没起来或端口映射不对docker compose ps 查看状态宿主机防火墙放行 3000后台日志空白渠道配置错误或密钥无效渠道页点测试看具体报错信息请求报 401令牌错误或已过期重新生成令牌确认客户端填的是令牌而非渠道密钥数据库连接超时MySQL 容器内存不足查看 docker stats增加宿主机内存或限制 MySQL 内存参数页面加载慢请求日志表过大清理日志配置自动留存天数离线导入镜像报错用的是 export 导出文件必须用 docker save docker load5.5 容器内时区问题的处理部署在内网或云服务器上如果宿主机的时区不是 Asia/ShanghaiNew-API 后台显示的时间可能跟本地时间差好几个小时。解决方式就是 compose 文件里那两个环境变量 TZAsia/Shanghai 和 MySQL 连接串里的 locLocal缺一不可。MySQL 容器里也需要同步设置时区可以在 environment 里加 TZAsia/Shanghai或者在 MySQL 配置里指定 default-time-zone 08:00。5.6 Docker 侧的内存和重启策略New-API 作为常驻服务restart: always 是必须的否则机器重启后服务不会自动拉起。内存方面New-API 本身占用很小200MB 以内但 MySQL 8.0 默认内存占用偏大1G 内存的小机器跑起来会有点吃力。如果 VPS 内存只有 1G建议给 MySQL 容器加内存限制deploy: resources: limits: memory: 512M不过要注意限制过小会导致 MySQL 频繁 OOM。生产环境优先保证 2G 以上内存小内存机器能用但体验不好。最后分享一个我的习惯每次配置文件改完、容器启动成功之后先把 docker-compose.yml 复制一份到备份目录。这个文件本身就是项目的一个核心交付物丢了就得重新回忆所有配置。另外 MySQL 数据目录 mysql-data 也建议定期压缩备份用 cron 脚本每天打一次 tar 包成本很低但崩溃恢复时能救命。踩过几次数据目录损坏的坑之后我才意识到配置文件和数据的备份和大模型网关本身一样重要。
