搞 AI 应用的开发者和运维应该对 New-API 不陌生了。一句话解释它就是一个大模型 API 统一网关把 OpenAI、Claude、Gemini、DeepSeek、智谱、Ollama 等各种各样的渠道接进来然后对外输出一套标准的 OpenAI 兼容接口统一管密钥、管额度、管日志、管用户权限。很多团队直接拿它当 AI API 网关用省掉了在每个业务系统里单独维护密钥和计费逻辑的重复劳动。这篇文章我会从零开始把 New-API 的在线部署和离线部署完整梳理一遍技术栈就锁定 MySQL Docker。无论你是在有外网的开发机上快速体验还是在内网服务器上闭门造车都能照着做。先说清楚New-API 本身用 Go 写的部署非常简单难点反而在数据层和容器编排上。MySQL 负责持久化渠道、令牌、日志、用户信息Docker 负责把应用和数据库隔离在同一套环境里Docker Compose 负责一键拉起这两个服务。把这个组合装明白了后续的升级、备份、迁机都变得很直观。下面直接进入正文。1. 部署前的整体思路与方案选型1.1 New-API 是什么为什么值得用New-API 是 one-api 的一个高活跃度分支在保留原有核心能力的基础上补了很多适合团队使用的功能。它的核心模型可以概括成三层第一层是“渠道”也就是上游的大模型服务比如 DeepSeek、通义千问、OpenAI甚至你本地起的 Ollama第二层是“令牌”类似 API Key给不同业务线、不同同事分配一个独立令牌第三层是“日志”所有请求都会留下轨迹方便看调用量、延迟和失败原因。我对这套东西最满意的地方是“模型映射”能力。比如你的业务代码里写死了gpt-4o但实际想用某个国产模型顶上不用改代码直接在渠道里做一个模型映射把gpt-4o指到deepseek-chat上。对上层应用来说它只认识一个 OpenAI 格式的接口后端换成什么模型完全不影响。这种解耦方式在多模型切换、灰度测试、成本控制的场景下特别好用。1.2 为什么数据库一定要用 MySQL而不是默认的 SQLiteNew-API 本身支持 SQLite本地快速玩玩用 SQLite 完全没问题但我强烈建议正式环境直接用 MySQL。原因有几个并发能力API 网关是高并发写入场景每个请求都要记录日志SQLite 的锁机制容易成为瓶颈。MySQL 在并发写入和查询上稳定太多。数据安全与备份MySQL 可以做到在线备份、主从同步、按时间点恢复SQLite 想在线备份还得费一番功夫。运维生态团队里会 MySQL 的人远比懂 SQLite 的人多出问题也好找人排查。数据迁移将来 New-API 要换机器、换部署方式MySQL 的数据文件或者 mysqldump 都容易操作。所以这篇文章的统一前提就是用 MySQL 8.0容器化方式运行和 New-API 一样都用 Docker 管理。1.3 在线和离线部署的差异点在哪在线环境部署的核心就是拉镜像、跑容器没什么磕绊。离线环境则完全换了一套玩法目标机器上不了 Docker Hub也没法直接用 apt/yum 在线装 Docker。因此离线部署的关键在于两件事第一提前在有网机器上拉好镜像、导成 tar 包第二提前准备好 Docker 和 Docker Compose 的离线安装包一起拷贝到内网服务器。很多人在离线部署时翻车不是 New-API 本身的问题而是卡在 Docker 装不上去、镜像加载不进去。所以下面我专门安排了一节把离线准备镜像、离线安装 Docker、离线加载镜像的路径捋顺。2. 环境准备与目标规划2.1 主机资源与端口规划先说主机要求。New-API 本身是 Go 写的内存占用不高MySQL 才是大头。个人测试用 1 核 2G 就够了生产环境建议 2 核 4G 以上磁盘至少给 10G。操作系统建议用 Ubuntu 20.04/22.04 LTS 或者 CentOS 7.9/Stream 8Windows 的 Docker Desktop 也能跑但服务器环境更推荐 Linux。端口规划上New-API 默认监听 3000 端口MySQL 默认 3306。部署时我给 MySQL 做了“屏蔽”——不把 3306 映射到宿主机只让容器内网访问这样避免数据库端口直接暴露。如果你需要从宿主机连接数据库排查问题可以在需要时临时加映射用完再关。目录规划同样重要我习惯把整个项目放在/opt/new-api下里面再分成数据目录和配置文件目录。数据目录单独挂载之后升级、备份都不动它。2.2 在线安装 Docker 和 Docker Compose在线环境的 Docker 安装没什么难度。Ubuntu 用户可以用官方脚本curl -fsSL https://get.docker.com | sh systemctl enable --now dockerCentOS 用户也可以先用官方脚本。装完验证一下docker version docker compose version新版 Docker 已经内置了docker compose插件老机器如果提示没有 compose可以单独装插件或者用docker-compose二进制放到/usr/local/bin/docker-compose并加执行权限。本文示例命令统一用docker compose空格形式如果你用的是老版本且只有docker-compose把命令中间的空格换成短横线即可。2.3 镜像选择与版本策略镜像选型是部署能否顺利推进的第一步。New-API 官方镜像在 Docker Hub 上有多个仓库我这边用过比较多的是calciumion/new-api版本标签建议直接看官方 GitHub Releases 页面选最新的稳定版不要无脑用latest。生产环境我习惯把版本号固定下来比如calciumion/new-api:v1.1.1这样升级和回滚都能精确控制。MySQL 镜像用mysql:8.0这个版本经过多年验证兼容性和稳定性都足够好。如果你所在机构有内网镜像仓库可以在线环境先把镜像推到私有仓库离线环境直接从内网仓库拉更加标准。如果没有就走后续的 tar 包方案。为了避免拉取 Docker Hub 太慢在线环境也可以配置国内的镜像加速器之后再拉取按自己网络实际情况来。3. 在线环境快速部署Docker Compose 一次成型3.1 编写 docker-compose.yml在线部署最舒服的方式就是 Docker Compose。我先把一份可以开箱即用的 compose 文件贴出来然后逐项解释关键配置。services: mysql: image: mysql:8.0 container_name: newapi-mysql restart: always environment: TZ: Asia/Shanghai MYSQL_ROOT_PASSWORD: change_root_password MYSQL_DATABASE: new-api MYSQL_USER: newapi MYSQL_PASSWORD: change_newapi_password command: - --character-set-serverutf8mb4 - --collation-serverutf8mb4_unicode_ci volumes: - ./mysql-data:/var/lib/mysql healthcheck: test: [CMD, mysqladmin, ping, -h, localhost] interval: 5s timeout: 5s retries: 20 new-api: image: calciumion/new-api:latest container_name: new-api restart: always depends_on: mysql: condition: service_healthy ports: - 3000:3000 environment: TZ: Asia/Shanghai SQL_DSN: newapi:change_newapi_passwordtcp(mysql:3306)/new-api?charsetutf8mb4parseTimeTruelocLocal SESSION_SECRET: please_change_this_secret LOG_LEVEL: info volumes: - ./new-api-data:/data注意新版 Docker Compose 已经可以不写version字段所以这里直接以services:开始。老版本如果要写就补一行version: 3.8放在最前面两种写法都行。3.2 关键配置逐条解释mysql服务里有几个细节必须说清楚。第一MYSQL_DATABASE和MYSQL_USER、MYSQL_PASSWORD这三个变量会在 MySQL 容器首次初始化数据目录时自动创建一个名为new-api的库并创建一个只拥有该库权限的用户newapi。这是最省心的方式你不需要提前连进去手动建库。第二command里强制指定了utf8mb4字符集和排序规则这是为了完整支持表情符号和多语言文本日志内容里可能会带上各种奇怪字符。第三我加了healthcheck让 MySQL 在完成初始化和就绪之前不被new-api视为可依赖服务。new-api服务里的核心环境变量是SQL_DSN。这个连接串的格式必须严格匹配用户名、密码、tcp(mysql:3306)里的mysql指向上面的 MySQL 服务名而不是127.0.0.1。在 Docker Compose 网络中服务名mysql可以被同一个网络下的new-api容器直接解析。parseTimeTrue和locLocal是 Go 的 MySQL 驱动处理时间字段的必要参数少了它们可能遇到时间格式问题。SESSION_SECRET是会话加密密钥一定要改成你自己的随机字符串别用示例里的值。这个值如果换成新的所有登录态会失效用户要重新登录。我踩过一次坑升级后忘了保留这个环境变量结果线上所有用户被强制踢下线。3.3 首次启动、初始化与创建管理员配置文件准备好后在/opt/new-api目录下执行docker compose up -d第一次启动会比想象中慢因为 MySQL 要在空白数据目录里做初始化。你可以用下面的命令观察日志docker compose logs -f mysql docker compose logs -f new-api看到 MySQL 日志里出现“ready for connections”New-API 日志里没有报错后打开浏览器访问http://你的服务器IP:3000。首次访问会引导你初始化管理员账号填一个邮箱和密码即可。第一次访问的注册行为是否开放其实由环境变量控制默认首次注册即可成为超级管理员建议初始化完成之后立刻进后台关闭“允许注册”避免暴露在公网时被陌生人注册。初始化完成后建议先做一个基础验证。在后台“令牌”页面创建一个新令牌然后命令行里用 curl 测试一下curl http://127.0.0.1:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的令牌 \ -d {model: deepseek-chat, messages: [{role: user, content: 你好}]}如果你还没有任何渠道这一步会报错提示没有可用渠道这是正常现象。下一步就是去“渠道”页面接一个上游模型。3.4 添加渠道以 DeepSeek 和本地 Ollama 为例添加 DeepSeek 很简单后台渠道类型选“DeepSeek”BaseURL 填官方 API 地址https://api.deepseek.com密钥填你在 DeepSeek 开放平台生成的 API Key模型列表填deepseek-chat,deepseek-reasoner。保存后刚才的 curl 测试就能通了。如果你的内网或本机跑着 Ollama比如本地已经用ollama run qwen2.5拉好了模型也可以在 New-API 里添加一个 Ollama 渠道。这里有个坑New-API 跑在 Docker 容器里它访问宿主机的 Ollama 不能直接写127.0.0.1。在 Windows/Mac 的 Docker Desktop 下可以用http://host.docker.internal:11434在 Linux 下建议直接用宿主机内网 IP比如http://192.168.1.100:11434。模型名填 Ollama 里实际的模型名如qwen2.5。这样你的业务系统只需要用 New-API 的地址就能间接调用本地模型不用去管 Ollama 的位置。3.5 在线部署时的升级与回滚在线环境升级 New-API 很流畅但前提是你要把数据备份做好。升级前先备份数据库docker exec newapi-mysql mysqldump -unewapi -pchange_newapi_password new-api backup_$(date %F).sql然后更新镜像并重启docker compose pull new-api docker compose up -d回滚的做法是在 compose 文件里把image改回旧版本号然后docker compose up -d。只要数据库没有做破坏性迁移旧版本基本都能正常连上。4. 离线环境部署全流程离线部署是很多内网项目的关键诉求。下面我按照“有网准备机 → 目标内网机”两段式流程来写保证每一步都能落地。4.1 在有网环境准备镜像和安装包先在任意一台能访问 Docker Hub 的 Linux 机器上拉取目标镜像并导出成 tar 包。docker pull calciumion/new-api:latest docker pull mysql:8.0 docker save -o new-api.tar calciumion/new-api:latest docker save -o mysql-8.0.tar mysql:8.0docker save会把镜像完整导出包括所有历史层所以 tar 包会比较大。MySQL 8.0 的镜像一般 500MB 左右New-API 大概几十到一百多 MB。你可以用gzip压缩一下再传gzip new-api.tar mysql-8.0.tar另外还要准备 Docker 本身的离线安装包。如果是 Ubuntu可以在有网机器上先下载所有需要的 deb 包再拷贝到内网安装更通用的做法是下载 Docker 官方静态二进制包。访问 Docker 官方 GitHub Releases下载对应架构amd64/arm64的docker-27.x.tgz同时把docker-compose插件二进制或者老版本docker-compose二进制也下载好。把这些文件和两个镜像 tar 包放到同一个传输目录用 scp 或者运维系统的文件分发通道传到内网目标机器。4.2 离线安装 Docker 与 Compose目标机器如果是 CentOS/Ubuntu可以优先尝试用系统自带的软件包离线安装方式。这里以静态二进制包为例兼容性最稳tar -xzf docker-27.x.tgz cp docker/* /usr/local/bin/然后写 systemd 服务文件让 Docker 进程由 systemd 托管。官方仓库里自带contrib/systemd目录下的 unit 文件拷贝到/etc/systemd/system/下即可。之后执行systemctl daemon-reload systemctl enable --now docker如果没有官方 systemd 文件也可以先手动启动dockerd 验证但生产环境还是建议用 systemd 托管不然重启后 Docker 起不来。Compose 插件的离线安装把之前下载的docker-compose二进制放到/usr/local/lib/docker/cli-plugins/docker-compose并加执行权限chmod x /usr/local/lib/docker/cli-plugins/docker-compose docker compose version如果放插件路径不生效直接把二进制复制为/usr/local/bin/docker-compose也可以用docker-compose命令调用。4.3 加载镜像并启动服务目标机器上先创建部署目录mkdir -p /opt/new-api cd /opt/new-api把之前准备的new-api.tar.gz、mysql-8.0.tar.gz解压后用docker load导入镜像gzip -d new-api.tar.gz mysql-8.0.tar.gz docker load -i new-api.tar docker load -i mysql-8.0.tar执行后可以用docker images确认两个镜像已在本地。接着把在线环境用的那份docker-compose.yml复制到/opt/new-api下注意修改 SQL_DSN 和管理密码。因为目标机器不会去 Docker Hub 拉镜像compose 文件里的 image 名字必须和你 load 进来的镜像名完全一致比如calciumion/new-api:latest和mysql:8.0。如果 Load 进来的镜像名是calciumion/new-api:latest但 compose 里写的是calciumion/new-api:latest那就没问题。如果之前是从私有仓库拉取的load 后名字可能会带内网仓库路径这时候要先把镜像重新打上 tag再跑 composedocker tag 内网仓库域名/calciumion/new-api:latest calciumion/new-api:latest最后启动docker compose up -d离线环境的启动流程和在线环境完全一样看日志、等 MySQL 初始化、访问页面初始化管理员。唯一容易碰壁的坑是MySQL 首次初始化时如果数据目录在 NFS 或特定挂载磁盘上可能因为权限问题失败。解决办法是给数据目录一个足够宽松的权限mkdir -p /opt/new-api/mysql-data chmod 777 /opt/new-api/mysql-data不过生产环境不建议一直用 777初始化完可以收紧权限改成当前运行容器进程的 UID 对应的属主。4.4 离线环境怎么升级离线升级不比在线难多少只是需要把“准备新镜像”这一步也搬到有网环境。流程是有网环境重新拉取新版本 New-API 镜像docker save导出。把新 tar 包传到内网机器docker load导入。修改 compose 文件里的 image 标签版本号docker compose up -d。如果升级失败再把旧镜像重新 load 并改回旧版本号启动即可回滚。所以离线环境最值钱的其实是那套 compose 文件和 mysql-data 数据目录。只要数据目录在换机器、换镜像都只是时间问题。5. 常见问题与排查技巧实录5.1 问题速查表我在部署和给朋友排查的过程中把高频问题整理成了下面的表格可以当速查手册用。问题现象可能原因解决办法new-api 容器反复重启SQL_DSN 连接串错误或 MySQL 还没就绪检查 SQL_DSN 密码、服务名看docker compose logs new-api页面提示数据库连接失败SQL_DSN 里写成 127.0.0.1Compose 环境内必须用服务名mysqlMySQL 容器启动后立刻退出数据目录权限不对或端口冲突删掉 mysql-data 重新初始化或检查端口占用访问 3000 端口超时宿主机防火墙未放行开放端口firewall-cmd --add-port3000/tcp或 ufw allow 3000日志全是乱码或时间不对容器时区没有设置给所有服务都加上TZ: Asia/ShanghaiWindows Docker Desktop 提示 virtualization not detected宿主机 BIOS 未开启虚拟化重启进 BIOS 开启 VT-x/AMD-V并启用 Hyper-V/WSL2添加 Ollama 渠道后调用报 connection refused容器内访问宿主机地址错误Linux 用宿主机 IPWin/Mac 用 host.docker.internal登录后台后点击某些页面白屏New-API 版本与浏览器缓存不兼容清缓存或无痕窗口重试升级到最新版本5.2 日志排查三板斧遇到问题先别急着重启按顺序做三道检查。第一道看 MySQL 日志确认数据库是否正常启动第二道看 New-API 日志重点看里面有没有带SQL_DSN、connect、refused字样的报错第三道进容器里手动连一下数据库docker exec -it newapi-mysql mysql -unewapi -pchange_newapi_password new-api -e select 1;能输出1说明数据库连接没问题问题出在应用层。两边都正常还是不行就把LOG_LEVEL环境变量改成debug重启 New-API 再试日志会详细很多。我在线上排查过几次类似问题80% 都是 SQL_DSN 写错或者 MySQL 数据目录权限不对。5.3 一个容易被忽略的数据安全细节New-API 的日志表会一直增长尤其是接入多个业务系统后每天可能产生几十万条请求日志。MySQL 数据目录如果不定期清理磁盘会逐渐打满。我习惯在后台日志页面定期清理老日志或者直接写一个定时任务删除 30 天前的日志表数据。如果业务上不需要长期审计可以用 cron 定期执行清理docker exec newapi-mysql mysql -unewapi -pchange_newapi_password new-api -e DELETE FROM logs WHERE created_at DATE_SUB(NOW(), INTERVAL 30 DAY);这种方式虽然简单粗暴但真的能让 MySQL 长期保持轻量。删除前记得确认下 New-API 的相关表结构不同版本表名可能有差异。我个人在实际操作中的体会是New-API 部署本身不难难的是把数据层和容器生命周期维护好。尤其离线环境很多团队把镜像和数据包拖进内网后就以为万事大吉真正跑起来才发现权限、服务名、时区、防火墙各种细碎问题。所以在一开始就把 compose 文件、数据目录、环境变量定义清楚后面会省很多事。最后再分享一个我养成的习惯每次部署或升级结束我都在/opt/new-api下额外保存一份和当前运行的 compose 文件完全一致的副本并在文件名里加上日期。如果真的把环境搞坏了直接照着旧配置恢复比临时回忆快得多。这套 MySQL Docker 的组合我用了很久无论是个人项目还是团队网关都跑得很稳定。
