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. 宿主机环境
   • 已安装 Docker 和 Docker Compose
   • 具有足够的磁盘空间和内存
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=100
EOF

重要提示：
– 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-network

networks:
  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. 检查容器状态：

“`bash
docker-compose ps
“`
确认 `new-api`、`postgres`、`redis` 状态是否为 `Up`。
2. 检查防火墙设置：
确认宿主机的 3000 端口是否已开放。
3. 检查应用日志：
“`bash
docker-compose logs –tail 100 new-api
“`
查看是否有数据库连接失败或其他报错信息。

6.2 数据库连接失败

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

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

“`bash
docker-compose logs postgres
docker-compose logs redis
“`
3. 确认网络连通性，容器是否都在 `new-api-network` 网络中。

6.3 健康检查失败

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

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

“`bash
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/