new-api

环境要求

• 64 位系统（amd64 / arm64），不支持 32 位架构
• 已安装 Docker 与 Docker Compose（官方推荐 Compose 方式部署）
• 数据库：本地 SQLite（Docker 需挂载 /data 目录）或远程 MySQL ≥ 5.7.8 / PostgreSQL ≥ 9.6
• 已合法获得上游厂商的 API Key / 账号，用于配置渠道

安装与启动步骤

1. 1拉取官方镜像

   从 Docker Hub 拉取 README 中标注的最新镜像 calciumion/new-api:latest，确认本地可用。

   docker pull calciumion/new-api:latest

   复制

2. 2编辑 Compose 配置

   按 README 快速开始，复制并编辑 docker-compose.yml，修改端口、挂载与镜像标签。

   nano docker-compose.yml

   复制

3. 3挂载数据目录

   用 SQLite 时容器必须挂载 /data 目录到宿主机，否则容器重建后数据全部丢失。

4. 4设置环境变量

   至少设置 SESSION_SECRET；用远程库填 SQL_DSN，用 Redis 填 REDIS_CONN_STRING。

5. 5启动服务

   在 docker-compose.yml 所在目录后台启动容器；多节点部署须保证 SESSION_SECRET 一致。

   docker compose up -d

   复制

6. 6查看运行状态

   检查容器是否处于运行状态，并查看日志确认无数据库、密钥类报错。

   docker compose ps

   复制

关键配置

如何确认成功

执行 docker compose ps 或 docker ps，容器状态为 Up/running，且日志中没有数据库连接失败或 SESSION_SECRET 相关报错。

常见问题

注意事项

• 仅用于合法授权的 AI API 网关、多模型管理与私有部署场景，上游 Key 需合法获取。
• 本地 HTTP 开发代理场景下 SESSION_COOKIE_SECURE 保持 false 或未设置，可关闭刷新/登出的 OriginGuard。
• 多机部署时数据库是登录会话的权威来源，Redis 会话仅为短 TTL 缓存，独立 Redis 节点间存在同步延迟。
• 更多环境变量与配置说明见官方文档 docs.newapi.pro 的环境变量页面。