乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > New API 说明与使用文档(token中转站二)

New API 说明与使用文档(token中转站二)

当前时间： 2026-03-30 19:23:03 更新时间： 2026-03-30 分类：软件教程 评论(0)

New API 说明与使用文档(token中转站二)

1. 项目概述

New API 是一个基于 One API 进行二次开发的开源大模型网关与AI资产管理系统。它旨在解决开发者在调用多个AI服务商（如OpenAI、Claude、Gemini等）时面临的接口不统一、权限管控复杂、计费统计困难等问题，提供一站式的AI服务管理解决方案。

项目地址：

1
https://github.com/QuantumNous/new-api.git

1.1 核心功能

  • • 多模型统一接入：兼容 OpenAI、Claude、Gemini、Midjourney、Suno 等30+主流模型接口，并支持自定义模型
  • • 接口格式转换：内置格式转换引擎，可自动实现不同厂商接口协议之间的互转
  • • 智能路由与高可用：支持加权随机、失败自动重试、优先级调度等策略
  • • 精细化权限与计费：支持令牌分组、用户配额管理、按量计费、在线充值等商业化运营功能
  • • 可视化监控：提供现代化的管理界面、多语言支持及详细的数据统计看板

2. 环境准备

2.1 系统要求

  • • 操作系统：Linux（推荐 Ubuntu 20.04/22.04、CentOS 7+）、macOS、Windows（需安装 Git Bash 或 WSL2）
  • • 运行环境：Node.js（≥18.0）、Git
  • • 数据库：SQLite（默认）、MySQL（≥5.7.8）或 PostgreSQL（≥9.6）
  • • 硬件：最低 2GB 内存，推荐 4GB 以上

2.2 安装 Node.js

Ubuntu/Debian：

1
2
3
4
5
6
7
8
9
# 添加 NodeSource 仓库curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -# 安装 Node.jssudo apt-get install -y nodejs git# 验证安装node --version  # 应显示 v18.x.x 或更高npm --version

CentOS/RHEL：

1
2
3
4
5
# 添加 NodeSource 仓库curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash -# 安装 Node.jssudo yum install -y nodejs git

macOS：

1
2
# 使用 Homebrew 安装brew install node git

3. 安装部署

3.1 下载项目代码

1
2
3
4
5
6
7
8
# 克隆项目仓库git clone https://github.com/QuantumNous/new-api.git# 进入项目目录cd new-api# 切换到稳定版本（可选）git checkout main

3.2 安装依赖

1
2
# 安装项目依赖npm install

3.3 数据库配置

选项一：使用 SQLite（适合小规模部署）

  • • SQLite 无需额外配置，数据文件会自动创建在项目目录中

选项二：使用 MySQL（推荐生产环境）

  1. 1. 安装 MySQL（Ubuntu示例）：
1
2
3
sudo apt-get install mysql-serversudo systemctl start mysqlsudo mysql_secure_installation
  1. 1. 创建数据库和用户：
1
2
3
4
CREATE DATABASE new_api;CREATE USER 'newapi'@'localhost' IDENTIFIED BY 'your_password';GRANT ALL PRIVILEGES ON new_api.* TO 'newapi'@'localhost';FLUSH PRIVILEGES;

3.4 配置文件设置

复制并编辑环境变量配置文件：

1
2
3
4
5
# 复制示例配置文件cp .env.example .env# 编辑配置文件vim .env

关键配置项说明：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 服务器配置PORT=3000                           # 服务监听端口NODE_ENV=production                 # 运行环境# 数据库配置（二选一）# SQLite 配置SQL_DSN=file:./data/new-api.db      # SQLite 数据库文件路径# MySQL 配置（如果使用 MySQL）# SQL_DSN=root:your_password@tcp(127.0.0.1:3306)/new_api?charset=utf8mb4&parseTime=True&loc=Local# Redis 配置（推荐，用于缓存和会话）REDIS_CONN_STRING=redis://localhost:6379/0# 安全密钥（务必修改为随机字符串）SESSION_SECRET=your_random_string_here_min_32_charsCRYPTO_SECRET=your_crypto_secret_here_min_32_chars# 系统配置TZ=Asia/Shanghai                    # 时区设置DEBUG=false                         # 调试模式（生产环境设为 false）

生成随机密钥的方法：

1
2
# 使用 openssl 生成 32 位随机字符串openssl rand -base64 32

3.5 创建必要目录

1
2
3
4
5
# 创建数据目录（SQLite 使用）mkdir -p data# 创建日志目录mkdir -p logs

4. 运行与部署

4.1 直接运行（测试环境）

1
2
3
4
5
# 开发模式运行npm run dev# 生产模式运行npm run start

4.2 使用 PM2 管理进程（推荐生产环境）

PM2 可以确保服务持续运行，并在异常退出时自动重启。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 全局安装 PM2npm install -g pm2# 启动 New APIpm2 start bin/www --name "new-api"# 设置开机自启pm2 savepm2 startup# 常用 PM2 命令pm2 status              # 查看运行状态pm2 logs new-api        # 查看日志pm2 restart new-api     # 重启服务pm2 stop new-api        # 停止服务

4.3 验证部署

启动成功后，访问 http://你的服务器IP:3000，应能看到 New API 的登录页面。

首次访问需要完成初始化设置：

  1. 1. 设置管理员邮箱和密码
  2. 2. 完成系统初始化

5. Nginx 反向代理配置（可选但推荐）

使用 Nginx 作为反向代理可以提供 HTTPS 支持和负载均衡能力。

5.1 安装 Nginx

1
2
3
4
5
# Ubuntu/Debiansudo apt-get install nginx# CentOS/RHELsudo yum install nginx

5.2 配置 Nginx

创建配置文件 /etc/nginx/sites-available/new-api：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
server {    listen 80;    server_name api.yourdomain.com;  # 替换为你的域名    # 如果需要 HTTPS，添加 SSL 配置    # listen 443 ssl http2;    # ssl_certificate /path/to/cert.pem;    # ssl_certificate_key /path/to/key.pem;    client_max_body_size 50M;  # 允许上传大文件    location / {        proxy_pass http://127.0.0.1:3000;        proxy_http_version 1.1;        proxy_set_header Upgrade $http_upgrade;        proxy_set_header Connection 'upgrade';        proxy_set_header Host $host;        proxy_cache_bypass $http_upgrade;        proxy_set_header X-Real-IP $remote_addr;        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;        proxy_set_header X-Forwarded-Proto $scheme;    }}

启用配置并重启 Nginx：

1
2
3
4
5
sudo ln -s /etc/nginx/sites-available/new-api /etc/nginx/sites-enabled/sudo nginx -t  # 测试配置sudo systemctl restart nginx#或者使用sudo nginx -s reload #热刷新

6. 高级配置与优化

6.1 使用 MySQL 数据库

如果选择 MySQL，在 .env 文件中配置：

1
SQL_DSN=username:password@tcp(127.0.0.1:3306)/new_api?charset=utf8mb4&parseTime=True&loc=Local

初始化数据库结构：

1
2
# 运行数据库迁移npm run migrate

6.2 使用 Redis 提升性能

1
2
3
4
5
6
7
8
9
10
# 安装 Redissudo apt-get install redis-server  # Ubuntu/Debiansudo yum install redis              # CentOS/RHEL# 启动 Redissudo systemctl start redissudo systemctl enable redis# 在 .env 中配置REDIS_CONN_STRING=redis://localhost:6379/0

6.3 设置日志轮转

创建 /etc/logrotate.d/new-api：

1
2
3
4
5
6
7
8
/home/your_user/new-api/logs/*.log {    daily    missingok    rotate 30    compress    notifempty    copytruncate}

6.4 防火墙配置

1
2
3
4
5
6
7
8
9
10
11
# Ubuntu/Debian (ufw)sudo ufw allow 22/tcpsudo ufw allow 80/tcpsudo ufw allow 443/tcpsudo ufw enable# CentOS/RHEL (firewalld)sudo firewall-cmd --permanent --add-service=sshsudo firewall-cmd --permanent --add-service=httpsudo firewall-cmd --permanent --add-service=httpssudo firewall-cmd --reload

7. 使用指南

7.1 初始化配置

  1. 1. 登录系统：访问 http://你的IP:3000，使用管理员账户登录
  2. 2. 添加渠道：
    • • 进入后台 → 渠道管理 → 添加渠道
    • • 选择模型类型（OpenAI、Claude 等）
    • • 填写 API Key 和接口地址
    • • 测试连通性后保存
  3. 3. 创建令牌：
    • • 进入 令牌管理 → 创建令牌
    • • 设置令牌名称、额度限制、可用模型
    • • 保存生成的令牌

7.2 API 调用示例

配置完成后，使用统一网关调用 AI 服务：

API 地址：http://你的IP:3000/v1/chat/completions

请求头：

1
2
Authorization: Bearer your_token_hereContent-Type: application/json

调用示例（curl）：

1
2
3
4
5
6
7
8
9
curl -X POST http://localhost:3000/v1/chat/completions \  -H "Authorization: Bearer your_token" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt-4o",    "messages": [      {"role": "user", "content": "Hello!"}    ]  }'

8. 维护与监控

8.1 查看日志

1
2
3
4
5
# PM2 日志pm2 logs new-api# 应用日志tail -f logs/combined.log

8.2 数据库备份

SQLite：

1
2
3
4
5
# 简单备份cp data/new-api.db data/new-api.db.backup# 定时备份脚本0 2 * * * cp /path/to/new-api/data/new-api.db /backup/new-api-$(date +\%Y\%m\%d).db

MySQL：

1
2
3
4
5
# 备份mysqldump -u root -p new_api > new_api_backup.sql# 恢复mysql -u root -p new_api < new_api_backup.sql

8.3 更新升级

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 进入项目目录cd /path/to/new-api# 备份配置cp .env .env.backup# 拉取最新代码git pull# 安装新依赖npm install# 运行数据库迁移npm run migrate# 重启服务pm2 restart new-api

9. 常见问题排查

Q：启动失败，提示端口被占用？

1
2
3
4
5
6
# 查看端口占用lsof -i :3000# 或netstat -tlnp | grep 3000# 修改 .env 中的 PORT 配置

Q：无法访问管理页面？

  • • 检查防火墙是否开放端口：sudo ufw status 或 sudo firewall-cmd --list-all
  • • 确认 Node.js 服务正常运行：pm2 status
  • • 检查 Nginx 配置是否正确

Q：数据库连接失败？

  • • 确认数据库服务运行：systemctl status mysql 或 systemctl status postgresql
  • • 验证数据库连接字符串格式是否正确
  • • 检查数据库用户权限

Q：API 调用返回 401 错误？

  • • 确认使用的令牌是否有效
  • • 检查令牌的模型权限设置
  • • 验证渠道配置是否正确

Q：日志中出现内存溢出错误？

1
2
3
# 增加 Node.js 内存限制# 编辑 PM2 配置文件或使用：pm2 start bin/www --name "new-api" --node-args="--max-old-space-size=2048"

10. 总结

通过本指南，你已成功在裸机环境中部署了 New API 系统。相比 Docker 部署，裸机部署虽然步骤稍多，但提供了更灵活的系统集成能力，便于进行深度定制和性能优化。

关键优势：

  • • 无需 Docker 环境，减少虚拟化开销
  • • 可直接访问系统资源和调试工具
  • • 便于集成到现有的监控、日志和运维体系

如需进一步了解系统功能、API 详细文档或参与社区讨论，请访问项目 GitHub 仓库和官方文档。