New API 教程：从 Docker 部署到首次 API 调用
简答：New API 的入门流程可以压缩为四步：先用 Docker Compose 启动实例，再完成管理员初始化；随后添加已获授权的上游渠道，创建限制了模型和额度的 API 密钥，最后通过 /v1/models 与聊天接口验证调用。本文给出一条适合新手的完整路径，并区分测试部署与生产部署。
定义：New API 是用于统一管理和分发多种大模型接口的 AI 网关，可集中配置上游渠道、模型、API 密钥、分组、用量和路由。
先看结论：New API 应该怎么部署
如果你的目标是长期运行或团队内部使用，优先选择 Docker Compose；如果只是本地体验或短期测试，可以使用单容器。New API 文档说明，Docker Compose 可编排 New API、数据库和 Redis，单容器更适合个人使用或小规模场景；生产环境优先使用 PostgreSQL，SQLite 更适合本地体验和临时测试。详细部署方式可查看 Docker Compose 部署文档 和 Docker 部署文档。
| 场景 | 建议方式 | 重点注意事项 |
|---|---|---|
| 本地体验或临时测试 | Docker 单容器 | 使用数据卷保存 /data，不要把测试配置直接当作生产配置。 |
| 个人长期使用或小团队 | Docker Compose | 优先使用 PostgreSQL，并根据需要启用 Redis。 |
| 多节点或高可用 | 集群部署 | 需要统一会话密钥、加密密钥、数据库和 Redis 配置，本文不展开集群架构。 |
本文不覆盖：集群高可用设计、面板图形化安装、具体云厂商防火墙页面，以及面向公众运营时的计费和合规制度。
第一步：准备服务器和部署目录
部署前至少需要一台能够运行 Docker 的 Linux 服务器、一个用于保存数据的目录，以及可以访问服务器端口的管理方式。官方 Docker Compose 文档将 Linux 系统列为推荐环境，并要求预先安装 Docker 和 Docker Compose。
- 登录服务器并创建工作目录：
mkdir -p ~/new-api。 - 进入目录：
cd ~/new-api。 - 确认 Docker 可用：
docker --version。 - 确认 Compose 可用：
docker compose version。 - 如果你使用域名，先把域名解析到服务器；HTTPS 反向代理和证书配置应在服务能够稳定启动后再做。
不要直接复制网上带有固定密码的 Compose 文件。数据库密码、会话密钥和加密密钥应替换为你自己生成的随机值，并保存到受控位置。环境变量的用途和多节点注意事项可参考 环境变量配置指南。
第二步：用 Docker Compose 启动 New API
官方文档推荐优先使用项目中提供的 Compose 配置。如果你能正常访问代码仓库，可以执行下面的命令获取配置，再根据实际环境修改配置文件：
git clone https://github.com/QuantumNous/new-api.git。cd new-api。- 打开
docker-compose.yml，核对端口、数据库密码、数据卷和环境变量。 - 启动服务：
docker compose up -d。
启动后先检查服务状态：docker compose ps。如果状态异常，查看 New API 容器日志：docker compose logs --tail=100 new-api；数据库或 Redis 报错时，再分别查看对应服务日志。官方配置说明列出了 SQL_DSN、REDIS_CONN_STRING、SESSION_SECRET、CRYPTO_SECRET 和 TZ 等常用变量，具体值应以当前配置和部署方式为准，可参考 Docker Compose 配置说明。
服务正常启动后，官方文档给出的默认访问方式是 http://服务器IP:3000。首次访问会进入初始化页面，按页面提示设置管理员账号和密码。端口映射、镜像标签和当前 Compose 内容可能随版本变化，部署前应再次核对官方文档，不要把本文示例当成永久固定配置。
第三步：首次登录后完成三项配置
New API 的首次可用链路不是“容器启动就结束”，还需要依次完成渠道、模型和 API 密钥配置。官方快速开始文档将流程概括为部署实例、配置模型渠道、创建 API 令牌三步。
- 添加上游渠道：进入管理后台的“渠道”，选择对应的服务商类型，填写已经合法拥有或获授权的 API Key、Base URL 和可用模型。渠道文档说明，渠道是平台连接上游 AI 服务的核心配置单元，可设置模型列表、优先级、权重、模型映射和自动禁用等选项。详情见 渠道管理文档。
- 核对模型名称：模型名称必须与上游实际支持的名称一致。如果对外使用别名，应在模型映射中明确写出映射关系，不要凭记忆硬编码模型 ID。本文统一使用
<MODEL_ID>占位符，实际值请从对应上游的官方模型列表复制。 - 创建 API 密钥：进入“API 密钥”，为测试应用创建单独密钥，并按需设置额度、过期时间、模型限制、IP 限制和分组。官方 API 密钥文档明确说明，密钥等同于密码，不应提交到代码仓库、截图、日志或聊天工具；怀疑泄露时应立即删除并重新创建。详情见 API 密钥文档。
建议测试密钥只允许一个模型、一个分组和较小额度。确认请求成功后，再为不同应用分别创建密钥，这样更容易定位用量和撤销权限。
第四步：用两个请求完成端到端验收
验收时不要一上来就测试复杂客户端，先用模型列表请求验证地址和认证，再用一个最小聊天请求验证渠道、模型和令牌权限。New API 的 API 参考说明，其 AI 模型接口兼容 OpenAI API 格式，包含模型列表和聊天对话补全接口，可先按下面流程操作。
1. 验证 API 密钥与 Base URL：
base_url="http://服务器IP:3000"
api_key="替换为你创建的 API 密钥"
response_file="/tmp/new-api-models.json"
trap 'rm -f "$response_file"' EXIT
http_code=$(curl -sS -o "$response_file" -w '%{http_code}' "$base_url/v1/models" -H "Authorization: Bearer $api_key")
printf 'HTTP %s\n' "$http_code"
cat "$response_file"
这里把响应体写入文件，再单独输出 HTTP 状态码，便于区分认证失败、路由失败和响应格式问题。不要把 API Key 写进脚本仓库，也不要使用会完整打印请求头的调试参数。
2. 使用模型 ID 发起最小聊天请求：
model_id="<MODEL_ID>"
request_file="/tmp/new-api-chat.json"
trap 'rm -f "$response_file" "$request_file"' EXIT
printf '%s' '{"model":"'"$model_id"'","messages":[{"role":"user","content":"请只回复：连接成功"}]}' > "$request_file"
http_code=$(curl -sS -o "$response_file" -w '%{http_code}' "$base_url/v1/chat/completions" -H "Authorization: Bearer $api_key" -H 'Content-Type: application/json' --data-binary @"$request_file")
printf 'HTTP %s\n' "$http_code"
cat "$response_file"
如果第一个请求成功、第二个请求失败，优先检查模型名称、渠道模型列表、模型映射、分组权限和上游额度；如果第一个请求就失败，则先检查 Base URL、端口、反向代理和 API 密钥。
第五步：常见问题排查与上线前清单
401：通常先检查 Authorization: Bearer 格式、密钥是否复制完整、密钥是否已禁用或过期。若使用了反向代理，确认代理没有删除认证头。
403：检查该 API 密钥是否允许目标模型、分组或来源 IP。密钥限制和分组设置会影响渠道选择，不要只看密钥本身是否存在。
404：检查请求路径是否为实例地址下的 /v1/models 或 /v1/chat/completions，并确认 Base URL 没有重复拼接 /v1。
模型不存在或无法路由：检查渠道是否启用、模型是否勾选、模型映射是否正确，以及 API 密钥是否能访问对应分组。渠道管理文档说明，渠道可以配置模型列表和模型映射。
429、超时或流式中断：先查看 New API 日志和上游返回体，区分本地并发、上游限速、额度不足、网络超时和代理缓冲问题。本文不提供未核实的具体限速或重试次数；实际限制应以对应上游的官方文档和返回头为准。
- 是否使用数据卷保存
/data。 - 是否为测试和生产环境分开创建 API 密钥。
- 是否限制模型、分组、额度和过期时间。
- 是否保存数据库和配置备份。
- 是否在公开访问前配置 HTTPS、访问控制和日志审计。
- 是否在更新前查看变更记录并备份数据。更新前备份和兼容性检查可参考 系统更新指南。
New API 上游渠道只能连接部署方合法拥有或已获授权的账号、API Key、模型服务或企业合约。请遵守上游服务条款、平台规则、监管要求和内容安全要求；面向公众提供服务时，还应自行建立密钥管理、日志审计、滥用处置和数据保护流程。
常见问题
New API 是什么，和 API 网关有什么关系？
New API 可以理解为面向大模型接口的 API 网关和管理系统。它把上游渠道、模型、API 密钥、分组、用量和路由集中管理，并对外提供统一的模型调用接口。
New API 新手应该用 Docker 单容器还是 Docker Compose？
只做本地体验或临时测试时，单容器更直接；准备长期运行或团队内部使用时，优先 Docker Compose。官方文档还建议生产环境优先使用 PostgreSQL，SQLite 更适合测试。
部署 New API 后为什么能打开网页，却调用模型失败？
网页能打开只说明容器和基础路由可用，不代表上游渠道已经配置正确。请依次检查渠道 API Key、Base URL、模型列表、模型映射、分组权限、API 密钥限制和上游额度。
API 密钥应该怎么设置才更安全？
按应用或环境分别创建密钥，并尽量限制模型、分组、额度、过期时间和来源 IP。不要把完整密钥提交到代码仓库、日志、截图或聊天工具；疑似泄露时立即禁用或删除并重新创建。
New API 的模型 ID 应该填什么？
填写上游实际支持的模型 ID，或者填写你在渠道配置中明确设置的对外别名。不要照抄过时教程中的固定 ID，建议从当前上游官方模型列表复制；本文示例使用 <code><MODEL_ID></code> 占位符。
参考资料
- New API 文档：快速开始（docs.newapi.ai）
- New API 文档：Docker Compose 部署（docs.newapi.ai）
- New API 文档：Docker 部署（docs.newapi.ai）
- New API 文档：Docker Compose 配置说明（docs.newapi.ai）
- New API 文档：环境变量配置指南（docs.newapi.ai）
- New API 文档：渠道管理（docs.newapi.ai）
- New API 文档：API 密钥（docs.newapi.ai）
- New API 文档：系统更新指南（docs.newapi.ai）