New API Docker 部署教程：从 Compose 安装到 API 调用

更新于 2026-10-31 · poloapi.cyou

简答：部署 New API Docker，优先使用官方仓库自带的 Docker Compose：克隆 QuantumNous/new-api，先修改 PostgreSQL、Redis 示例密码和 SESSION_SECRET，再执行 docker compose up -d。服务启动后访问服务器的 3000 端口完成管理员初始化，随后配置渠道、模型和 API Token，并用 /v1/models 验证调用链路。

定义：New API 是一个开源 AI 网关和模型 API 管理系统，可通过 Docker 部署，并提供 OpenAI 兼容的统一模型接口。

先看最短可执行流程：生产环境优先 Docker Compose

本文站点是独立的 AI API 接入指南，不是 New API 官方站。以下内容仅根据截至 2026-10-31 核验到的官方文档、官方仓库和官方配置文件整理。

如果你已经有 Linux 服务器、Docker 和 Docker Compose，先执行下面的主流程。不要直接使用仓库里的示例密码把服务暴露到公网。

1. git clone https://github.com/QuantumNous/new-api.git
2. cd new-api
3. 编辑 docker-compose.yml，修改 PostgreSQL 密码、Redis 密码、连接字符串，并设置持久化的 SESSION_SECRET。
4. docker compose up -d
5. docker compose ps 查看服务状态。
6. docker compose logs -f new-api 查看应用日志。
7. 访问 http://服务器IP:3000，按初始化页面创建管理员账户。

官方仓库自带的 Compose 配置默认会启动 New API、PostgreSQL 和 Redis；官方文档同时说明，Docker Compose 更适合生产环境，单容器更适合个人使用或小规模测试。查看官方安装方式说明。查看官方 docker-compose.yml

最小成功判定：三个服务处于运行状态、浏览器可以打开 3000 端口的初始化页面，并且初始化后能够登录后台。之后还需要配置至少一个渠道、可用模型和 API Token，才能完成真实 API 调用。

部署前准备与方案选择

官方 Docker 文档将 PostgreSQL列为生产环境优先数据库，MySQL保持兼容，SQLite适合本地评估和临时测试。Redis用于缓存等场景；是否使用以及如何配置，应以当前 Compose 文件和环境变量文档为准。查看官方 Docker 部署说明

部署前至少准备：一台能够运行 Docker 的 Linux 服务器、可用的 Docker Compose 命令、用于持久化数据的目录、需要开放的服务端口，以及后续用于 HTTPS 反向代理的域名。本文不虚构最低 CPU、内存或带宽要求；资源是否足够，应结合启用的数据库、并发量、日志量和实际监控判断。

修改 Compose 配置：密码、密钥和数据持久化

官方仓库的示例配置包含数据库和 Redis 的示例密码。部署到公网前，至少检查以下项目：

• PostgreSQL 密码：修改 POSTGRES_PASSWORD，并同步修改 New API 服务中的 SQL_DSN，否则应用无法连接数据库。
• Redis 密码：修改 Redis 服务的 --requirepass 参数，并同步修改 REDIS_CONN_STRING。
• SESSION_SECRET：生成持久化随机值，例如 openssl rand -hex 32，写入 New API 服务的环境变量。多节点部署时，各节点必须使用一致的会话密钥。
• 数据挂载：保留官方配置中的 PostgreSQL 数据卷，以及 New API 的 ./data:/data 和日志挂载，避免容器删除后丢失数据。
• 端口暴露：官方示例将容器 3000 端口映射到主机 3000 端口。若后续使用反向代理，可考虑只让反向代理对外提供 HTTPS，再限制应用端口的公网访问。

可以用下面的命令生成密钥，然后复制结果到 Compose 文件：

• openssl rand -hex 32
• docker compose config：检查 Compose 文件能否被解析。

不要把真实密码、API Key 或 SESSION_SECRET提交到公开代码仓库，也不要把包含密钥的完整日志直接发到论坛。官方仓库明确要求生产部署前替换数据库和 Redis 示例密码，并设置持久化随机 SESSION_SECRET。查看官方仓库部署说明

启动、查看状态与首次初始化

完成配置后，在 new-api 目录执行：

1. docker compose pull：拉取 Compose 文件中指定的镜像。
2. docker compose up -d：后台启动服务。
3. docker compose ps：查看服务状态。
4. docker compose logs --tail=100 new-api：查看 New API 最近 100 行日志。
5. docker compose logs -f new-api：持续跟踪应用日志。

首次访问 http://服务器IP:3000 时，官方文档说明系统会自动进入初始化页面。按照页面提示创建管理员账户和密码，完成后再登录后台。若页面打不开，先不要急着改配置，按“端口—容器状态—应用日志—防火墙”顺序排查。

初始化完成后，基本业务顺序是：添加上游模型渠道和凭据，填写可用模型并测试渠道；配置模型和分组；创建给客户端使用的 API Token；确认该 Token 有权访问对应分组和模型。官方快速开始文档也将部署、配置渠道、创建 Token 和发起首次 API 调用列为连续步骤。查看官方 Quick Start

部署完成后，用 OpenAI 兼容接口做最小验证

下面示例中的 NEW_API_KEY、your-enabled-model 和域名都是占位符。请替换为后台实际创建的 Token 和已启用模型，不要把真实 Token 写进文章、截图或公开日志。

先列出当前 Token 能访问的模型：

• export NEW_API_KEY='替换为后台创建的API Token'
• curl --fail-with-body http://服务器IP:3000/v1/models -H "Authorization: Bearer ${NEW_API_KEY}"

如果响应是可解析的模型列表，说明 Base URL、Token 和基础路由至少已经连通。再发起一个最小聊天请求：

• curl --fail-with-body http://服务器IP:3000/v1/chat/completions -H "Authorization: Bearer ${NEW_API_KEY}" -H "Content-Type: application/json" -d '{"model":"your-enabled-model","messages":[{"role":"user","content":"你好"}]}'

New API 官方文档说明，其 AI 模型接口兼容 OpenAI API 格式；常见客户端的 Base URL通常填写 https://你的域名/v1，认证使用 Authorization: Bearer API_TOKEN。如果客户端要求完整路径，才按客户端说明补充 /chat/completions。查看官方 API 调用示例

Python OpenAI SDK的关键配置如下：

• from openai import OpenAI
• client = OpenAI(api_key="你的API_TOKEN", base_url="https://你的域名/v1")
• response = client.chat.completions.create(model="your-enabled-model", messages=[{"role":"user","content":"你好"}])

若 /v1/models 能返回列表，但聊天请求失败，优先检查模型 ID是否确实出现在该 Token可访问的模型列表中，以及渠道测试、分组和模型映射是否完成。

域名、HTTPS 与安全配置

直接使用 http://服务器IP:3000适合首次初始化和局域网测试，不建议把管理后台和 API 长期以明文 HTTP 暴露到公网。生产环境通常应由 Caddy、Nginx 或其他反向代理接收 HTTPS，再转发到 New API 的 3000 端口。反向代理配置需要保留长连接、流式响应和 WebSocket升级能力；具体写法取决于代理软件和你的域名结构，不能把某一份配置无条件套用到所有环境。

使用 HTTPS 控制台时，官方仓库说明可以设置 SESSION_COOKIE_SECURE=true，并填写精确的 SESSION_COOKIE_TRUSTED_URL，例如 https://api.example.com。该值应是完整的 HTTPS Origin，不应添加路径或通配符。若使用代理，还应按实际代理网络配置 TRUSTED_PROXIES。

• 域名 DNS解析指向服务器公网地址。
• 防火墙和云安全组仅开放必要端口。
• 数据库和 Redis端口不要无必要映射到公网。
• HTTPS 配置完成后，再把客户端 Base URL改为 https://你的域名/v1。
• 后台密码、数据库密码、Redis 密码和 API Token分别管理，避免复用。

官方仓库还提醒，生产部署应持久化并备份数据库和挂载数据；如果使用多节点，数据库和认证相关密钥需要按文档保持一致。查看官方生产配置提示

升级与备份：不要只执行拉取镜像

官方系统更新指南建议升级前先备份数据库和重要配置文件，查看 GitHub Releases的更新内容，并确认现有插件、集成或自定义配置兼容。生产环境不要把 latest 当作固定版本号：官方仓库说明该标签会随着发布变化，升级前应核对版本、迁移和兼容性。

Docker Compose常见升级流程是：

1. 备份 PostgreSQL 数据、docker-compose.yml、域名代理配置和必要的环境变量。
2. 查看项目发布说明，确认是否有数据库迁移或破坏性变更。
3. docker compose pull
4. docker compose down
5. docker compose up -d
6. docker compose ps 和 docker compose logs --tail=200 new-api 验证升级结果。

除非你已经确认数据已备份并且理解卷操作后果，不要随意执行带有 -v 的停止命令，因为删除卷可能导致数据库数据丢失。查看官方系统更新指南

常见故障排查：按证据分流

排错时建议保留脱敏后的请求方法、路径、HTTP 状态码、响应体摘要和容器日志时间，不要上传 API Key、Cookie、Authorization头或完整数据库连接字符串。状态码只能说明某一层的现象，不能单独证明一定是某个组件导致。

常见问题

New API Docker 部署应该用 Docker Compose 还是单容器？

官方文档推荐 Docker Compose用于生产环境，因为它可以编排 New API、数据库和 Redis；单容器更适合个人使用、本地评估或小规模测试。正式部署前仍需修改示例密码、设置持久化 SESSION_SECRET并做好数据备份。

New API Docker 启动后访问哪个地址？

官方 Docker示例默认把容器的 3000 端口映射到主机 3000端口，因此通常访问 http://xn--ip-fr5c86lx7z:3000/。若前面配置了 HTTPS反向代理，则应访问你的 HTTPS域名，具体路径和端口以代理配置为准。

为什么 New API 初始化页面打不开？

先执行 docker compose ps确认服务是否运行，再执行 docker compose logs --tail=200 new-api查看启动错误；随后检查主机端口映射、防火墙、云安全组和 DNS。若容器反复重启，优先处理日志中显示的数据库连接或环境变量错误。

New API 的 API Base URL应该怎么填？

OpenAI兼容客户端通常填写部署地址加 /v1，例如 https://api.example.com/v1；认证使用 New API后台创建的 API Token。若客户端要求完整接口路径，再根据该客户端说明补充 /chat/completions等路径。

升级 New API Docker前要备份什么？

至少备份 PostgreSQL数据库、New API挂载的数据目录、docker-compose.yml、环境变量、反向代理配置和域名证书相关配置。升级前还要查看官方发布说明并确认兼容性，不要未经确认执行 docker compose down -v。

相关阅读

• 先了解 New API 的定位与使用场景
• 继续排查 API 返回 403 权限错误
• 查看 404 模型不存在的核验方法
• 排查 API 流式输出中断

参考资料

1. New API 官方文档：Quick Start（docs.newapi.ai）
2. New API 官方文档：Installation & Deployment（docs.newapi.ai）
3. New API 官方文档：Docker Deployment（docs.newapi.ai）
4. QuantumNous/new-api 官方 GitHub 仓库
5. 官方 docker-compose.yml 配置
6. 官方 README：部署、配置与 API 调用
7. New API 官方文档：Using API and Playground（docs.newapi.ai）
8. New API 官方文档：System Update Guide（docs.newapi.ai）