New-API 安装与优化部署指南（基于 Docker Compose）

一、概述

New-API 是一个强大的 API 接口管理和分发系统。本文档介绍如何通过 Docker Compose 快速部署优化版的 New-API 服务，并将所有数据、日志统一存放到宿主机的指定目录，便于后续的备份与维护。

建议可以先在：https://github.com/QuantumNous/new-api/blob/main/README.zh_CN.md 查看官方部署文档。

1.1 环境说明

• • 部署方式：Docker Compose
• • New-API 镜像：基于官方源码二开版本 reg-hub.gzeport.com/library/new-api:v0.31.2-20260611
• • 数据库：PostgreSQL 15
• • 缓存：Redis 6.2-alpine
• • 数据统一存放目录：/AppHome/docker/newapi

1.2 使用前准备

在开始之前，请确保准备好以下内容：

1. 1. 宿主机环境
• • 已安装 Docker 和 Docker Compose
• • 具有足够的磁盘空间和内存
2. 2. 网络环境
• • 确保宿主机可以正常拉取 Docker 镜像（如需配置代理或国内镜像源请提前配置）
• • 开放所需端口（默认 3000）

二、部署前准备（环境初始化）

为了方便管理和数据持久化，我们将所有相关数据统一存放到 /AppHome/docker/newapi 目录下。

2.1 创建统一存储目录

# 确保宿主机目录存在mkdir -p /AppHome/docker/newapi

2.2 创建环境变量配置文件

在即将存放 docker-compose.yml 的同级目录下，创建 .env 文件，用于存放敏感信息。

cat > .env << 'EOF'POSTGRES_PASSWORD=123456      # ⚠️ 生产环境必须修改！REDIS_PASSWORD=123456         # ⚠️ 生产环境必须修改！POSTGRES_MAX_CONNECTIONS=100EOF

重要提示：

• • POSTGRES_PASSWORD 和 REDIS_PASSWORD 是数据库和缓存的密码。
• • 生产环境部署前，务必修改上述默认密码！

三、Docker Compose 部署

3.1 编写配置文件

关于镜像：本方案使用的是基于 New-API 官方源码 的二开版本镜像 reg-hub.gzeport.com/library/new-api:v0.31.2-20260611，相比官方版本新增了用户输入输出日志记录等功能。

在当前目录下创建 docker-compose.yml 文件，并填入以下内容：

version: '3.4'services:  new-api:    image: reg-hub.gzeport.com/library/new-api:v0.31.2-20260611  # 二开镜像    container_name: new-api    restart: always    command: --log-dir /app/logs    ports:      - "3000:3000"    volumes:      - /AppHome/docker/newapi/data:/data         # 应用数据目录      - /AppHome/docker/newapi/logs:/app/logs     # 应用日志目录    environment:      - SQL_DSN=postgresql://root:${POSTGRES_PASSWORD}@postgres:5432/new-api      - REDIS_CONN_STRING=redis://:${REDIS_PASSWORD}@redis:6379      - TZ=Asia/Shanghai      - LOG_CONTENT_ENABLED=true      - ERROR_LOG_ENABLED=true                    # 启用错误日志      - BATCH_UPDATE_ENABLED=true                 # 启用批量更新      - NODE_NAME=new-api-node-1                  # 节点名称，多实例部署时需修改      - STREAMING_TIMEOUT=300                     # 流模式超时(秒)      - LOG_USER_INPUT_MAX_RUNES=5000             # 日志中 user_input 字段的最大记录字符数，0 表示不限制    depends_on:      - redis      - postgres    networks:      - new-api-network    healthcheck:      test: ["CMD-SHELL", "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' || exit 1"]      interval: 30s      timeout: 10s      retries: 3      start_period: 60s                           # 启动等待时间  redis:    image: d.ajunyunwei.xyz/library/redis:6.2-alpine    container_name: redis    restart: always    command: >      redis-server      --requirepass ${REDIS_PASSWORD}    volumes:      - /AppHome/docker/newapi/redis:/data    networks:      - new-api-network  postgres:    image: d.ajunyunwei.xyz/library/postgres:15    container_name: postgres    restart: always    environment:      POSTGRES_USER: root      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}      POSTGRES_DB: new-api      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"    volumes:      - /AppHome/docker/newapi/postgres:/var/lib/postgresql/data  # PostgreSQL 数据持久化    networks:      - new-api-networknetworks:  new-api-network:    driver: bridge

3.2 启动服务

# 后台启动所有服务docker-compose up -d

3.3 验证安装

# 查看容器运行状态docker-compose ps# 查看 New-API 服务日志，确认是否启动成功docker-compose logs -f new-api

四、核心环境变量说明

本部署方案对 New-API 进行了一些优化配置，以下是核心环境变量的详细说明：

五、初始访问与配置

5.1 访问系统

服务启动成功后，可以通过浏览器访问 New-API 的 Web 界面：

• • 访问地址：http://<你的宿主机IP>:3000
• • 默认账号：root
• • 默认密码：123456

安全警告：首次登录后，请务必立即前往「设置」或「个人中心」修改默认的 root 密码！

5.2 目录结构说明

所有数据持久化在 /AppHome/docker/newapi 目录下，具体结构如下：

/AppHome/docker/newapi/├── data/       # New-API 应用程序产生的文件数据├── logs/       # New-API 的运行日志├── postgres/   # PostgreSQL 数据库的数据文件└── redis/      # Redis 缓存的持久化数据

备份时，只需打包备份整个 /AppHome/docker/newapi 目录即可。

六、常见问题排查

6.1 服务无法访问

问题现象：浏览器无法打开 http://<IP>:3000

排查步骤：

1. 1. 检查容器状态：

   docker-compose ps

   确认 new-api、postgres、redis 状态是否为 Up。
2. 2. 检查防火墙设置：确认宿主机的 3000 端口是否已开放。
3. 3. 检查应用日志：

   docker-compose logs --tail 100 new-api

   查看是否有数据库连接失败或其他报错信息。

6.2 数据库连接失败

问题现象：New-API 日志提示无法连接到 PostgreSQL 或 Redis。

排查步骤：

1. 1. 确认 .env 文件是否存在且密码配置正确。
2. 2. 检查数据库容器日志：

   docker-compose logs postgresdocker-compose logs redis

3. 3. 确认网络连通性，容器是否都在 new-api-network 网络中。

6.3 健康检查失败

问题现象：docker-compose ps 显示 new-api 状态为 unhealthy。

排查步骤：

1. 1. 可能是启动较慢，等待 60 秒（start_period）后再查看。
2. 2. 手动在宿主机执行健康检查命令测试：

   curl http://localhost:3000/api/status

   查看返回结果是否包含 "success":true。

七、参考资料

• • New-API 官方 GitHub 仓库：https://github.com/QuantumNous/new-api
• • 官方中文部署文档：https://github.com/QuantumNous/new-api/blob/main/README.zh_CN.md
• • 二开镜像仓库：reg-hub.gzeport.com/library/new-api:v0.31.2-20260611
• • Docker 官方文档：https://docs.docker.com/compose/