Skip to content

README.zh_CN.md

Latest commit

 

History

History
502 lines (370 loc) · 19.9 KB

README.zh_CN.md

File metadata and controls

502 lines (370 loc) · 19.9 KB
Raw

new-api

New API

🍥 新一代大模型网关与AI资产管理系统

简体中文 | 繁體中文 | English | Français | 日本語

license release docker AtomGit G-Star

QuantumNous%2Fnew-api | Trendshift
Featured｜HelloGitHub AtomGit G-Star

快速开始 • 主要特性 • 部署 • 文档 • 帮助

📝 项目说明

Important

  • 本项目仅面向合法授权的 AI API 网关、组织内部鉴权、多模型管理、用量统计、成本核算和私有化部署场景。
  • 使用者必须合法取得上游 API Key、账号、模型服务或接口权限，并遵守上游服务条款及适用法律法规。
  • 使用者应确保其使用方式符合上游服务条款及适用法律法规。
  • 面向公众提供生成式人工智能服务时，使用者应遵守《生成式人工智能服务管理暂行办法》等监管要求，自行完成所在司法辖区要求的备案、许可、内容安全、实名、日志留存、税务和上游授权等合规义务。

🤝 我们信任的合作伙伴

排名不分先后

Cherry Studio Aion UI 北京大学 UCloud 优刻得 阿里云 IO.NET

🙏 特别鸣谢

JetBrains Logo

感谢 JetBrains 为本项目提供免费的开源开发许可证

🚀 快速开始

使用 Docker Compose（推荐）

# 克隆项目
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# 编辑 docker-compose.yml 配置
nano docker-compose.yml

# 启动服务
docker-compose up -d
使用 Docker 命令 
# 拉取最新镜像
docker pull calciumion/new-api:latest

# 使用 SQLite（默认）
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

# 使用 MySQL
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

💡 提示： -v ./data:/data 会将数据保存在当前目录的 data 文件夹中，你也可以改为绝对路径如 -v /your/custom/path:/data

🎉 部署完成后，访问 http://localhost:3000 即可使用！

Warning

将本项目作为面向公众的生成式 AI 服务或 API 转售服务运营时，使用者应先完成备案、内容安全、实名、日志留存、税务、支付和上游授权等合规义务。

📖 更多部署方式请参考 部署指南

📚 文档

📖 官方文档 | Ask DeepWiki

快速导航：

分类 链接
🚀 部署指南 安装文档
⚙️ 环境配置 环境变量
📡 接口文档 API 文档
❓ 常见问题 FAQ
💬 社区交流 交流渠道

✨ 主要特性

详细特性请参考 特性说明

🎨 核心功能

特性 说明
🎨 全新 UI 现代化的用户界面设计
🌍 多语言 支持中文、英文、法语、日语
🔄 数据兼容 完全兼容原版 One API 数据库
📈 数据看板 可视化控制台与统计分析
🔒 权限管理 令牌分组、模型限制、用户管理

💰 授权用量与成本管理

  • ✅ 合法授权场景下的内部充值与额度分配（易支付、Stripe）
  • ✅ 组织内按次、按量或缓存命中成本核算
  • ✅ 支持 OpenAI、Azure、DeepSeek、Claude、Qwen 等模型的缓存计费统计
  • ✅ 面向内部管理或企业客户的灵活计费策略配置

🔐 授权与安全

  • 😈 Discord 授权登录
  • 🤖 LinuxDO 授权登录
  • 📱 Telegram 授权登录
  • 🔑 OIDC 统一认证
  • 🔍 Key 查询使用额度（配合 new-api-key-tool）

🚀 高级功能

API 格式支持：

智能路由：

  • ⚖️ 渠道加权随机
  • 🔄 失败自动重试
  • 🚦 用户级别模型限流

格式转换：

  • 🔄 OpenAI Compatible ⇄ Claude Messages
  • 🔄 OpenAI Compatible → Google Gemini
  • 🔄 Google Gemini → OpenAI Compatible - 仅支持文本，暂不支持函数调用
  • 🚧 OpenAI Compatible ⇄ OpenAI Responses - 开发中
  • 🔄 思考转内容功能

Reasoning Effort 支持：

查看详细配置

OpenAI 系列模型：

  • o3-mini-high - High reasoning effort
  • o3-mini-medium - Medium reasoning effort
  • o3-mini-low - Low reasoning effort
  • gpt-5-high - High reasoning effort
  • gpt-5-medium - Medium reasoning effort
  • gpt-5-low - Low reasoning effort

Claude 思考模型：

  • claude-3-7-sonnet-20250219-thinking - 启用思考模式

Google Gemini 系列模型：

  • gemini-2.5-flash-thinking - 启用思考模式
  • gemini-2.5-flash-nothinking - 禁用思考模式
  • gemini-2.5-pro-thinking - 启用思考模式
  • gemini-2.5-pro-thinking-128 - 启用思考模式，并设置思考预算为128tokens
  • 也可以直接在 Gemini 模型名称后追加 -low / -medium / -high 来控制思考力度（无需再设置思考预算后缀）

🤖 模型支持

详情请参考 接口文档 - 网关接口

模型类型 说明 文档
🤖 OpenAI-Compatible OpenAI 兼容模型 文档
🤖 OpenAI Responses OpenAI Responses 格式 文档
🎨 Midjourney-Proxy Midjourney-Proxy(Plus) 文档
🎵 Suno-API Suno API 文档
🔄 Rerank Cohere、Jina 文档
💬 Claude Messages 格式 文档
🌐 Gemini Google Gemini 格式 文档
🔧 Dify ChatFlow 模式 -
🎯 自定义上游 支持配置合法授权的上游接口地址 -

📡 支持的接口

查看完整接口列表

🚢 部署

Tip

最新版 Docker 镜像： calciumion/new-api:latest

📋 部署要求

组件 要求
本地数据库 SQLite（Docker 需挂载 /data 目录）
远程数据库 MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6
容器引擎 Docker / Docker Compose
系统架构 仅支持 64 位系统（amd64 / arm64），不支持 32 位系统

⚙️ 环境变量配置

常用环境变量配置
变量名 说明 默认值
SESSION_SECRET 鉴权签名密钥；所有节点必须保持一致 -
SESSION_COOKIE_SECURE false/未配置时关闭 refresh/logout OriginGuard 以兼容本地 HTTP 开发代理；true 时启用 Secure Cookie 和严格 Origin 校验 false
SESSION_COOKIE_TRUSTED_URL Secure 模式必填：允许调用 refresh/logout 的精确 HTTPS Origin，多个用英文逗号分隔；不是 relay CORS 白名单 -
TRUSTED_PROXIES 未配置/留空时信任回环、RFC1918 和 IPv6 ULA 并输出启动告警；none 不信任任何代理；显式代理 IP/CIDR 列表完全替代默认值 127.0.0.0/8, ::1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7
USER_SESSION_ACTIVE_LIMIT 单用户最大活跃登录 Session 数 50
USER_SESSION_ISSUANCE_LIMIT 单用户在签发窗口内可创建的 Session 总数，包含已撤销 Session 100
USER_SESSION_ISSUANCE_WINDOW_SECONDS Session 签发计数窗口（秒）；高于 revoked 保留期时自动钳制 86400
USER_SESSION_REVOKED_RETENTION_DAYS revoked Session 用于审计和签发计数的保留天数 7
USER_SESSION_HOURLY_ALERT_THRESHOLD 全局每小时 Session 签发告警阈值；只告警，不拒绝登录 5000
CRYPTO_SECRET 缓存键 HMAC 密钥；共享 Redis 的节点必须使用相同有效值 默认跟随 SESSION_SECRET
SQL_DSN 数据库连接字符串 -
REDIS_CONN_STRING Redis 连接字符串 -
STREAMING_TIMEOUT 流式超时时间（秒） 300
STREAM_SCANNER_MAX_BUFFER_MB 流式扫描器单行最大缓冲（MB），图像生成等超大 data: 片段（如 4K 图片 base64）需适当调大 64
MAX_REQUEST_BODY_MB 请求体最大大小（MB，解压后计；防止超大请求/zip bomb 导致内存暴涨），超过将返回 413 32
AZURE_DEFAULT_API_VERSION Azure API 版本 2025-04-01-preview
ERROR_LOG_ENABLED 错误日志开关 false
PYROSCOPE_URL Pyroscope 服务地址 -
PYROSCOPE_APP_NAME Pyroscope 应用名 new-api
PYROSCOPE_BASIC_AUTH_USER Pyroscope Basic Auth 用户名 -
PYROSCOPE_BASIC_AUTH_PASSWORD Pyroscope Basic Auth 密码 -
PYROSCOPE_MUTEX_RATE Pyroscope mutex 采样率 5
PYROSCOPE_BLOCK_RATE Pyroscope block 采样率 5
HOSTNAME Pyroscope 标签里的主机名 new-api

📖 完整配置： 环境变量文档

🔧 部署方式

方式 1：Docker Compose（推荐） 
# 克隆项目
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# 编辑配置
nano docker-compose.yml

# 启动服务
docker-compose up -d
方式 2：Docker 命令

使用 SQLite：

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

使用 MySQL：

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

💡 路径说明：

  • ./data:/data - 相对路径，数据保存在当前目录的 data 文件夹
  • 也可使用绝对路径，如：/your/custom/path:/data
方式 3：宝塔面板
  1. 安装宝塔面板（≥ 9.2.0 版本）
  2. 在应用商店搜索 New-API
  3. 一键安装

📖 图文教程

⚠️ 多机部署注意事项

Warning

  • 所有节点必须使用同一个主数据库，并设置相同的 SESSION_SECRET；否则 Access Token、Refresh 会话和临时鉴权流程无法一致校验。
  • 连接同一个 Redis 的节点还必须设置相同的 CRYPTO_SECRET，否则节点生成的缓存键摘要不一致，无法正确共享缓存。

登录 Session 和单用户活跃数/签发数限制均以数据库为权威。Redis 中的 Session 仅为短期缓存，TTL 跟随 SYNC_FREQUENCY（默认 60 秒），且不会超过 Session 的剩余寿命。

Redis 拓扑 Session 状态传播 限流语义
所有节点共享 Redis 撤销和版本发布通常即时传播 Redis 限流额度在节点间共享
每个节点使用独立 Redis 最迟在有效 SYNC_FREQUENCY 内回源数据库收敛；版本轮换后，新 Token 在持有旧缓存的节点上可能短暂返回 401 每个节点独立计数，集群总额度最坏约为单节点阈值乘以节点数
不使用 Redis 每次 Session 校验直接读取数据库 各节点使用独立的内存限流额度

缩短 SYNC_FREQUENCY 可减小独立 Redis 的陈旧窗口，但每个活跃 SID 在每个节点上会按该 TTL 增加一次数据库主键点查。上述保证只让 Session 鉴权在不同拓扑下保持有界陈旧；限流和其他 Redis 控制面缓存仍受拓扑影响。

Token、Origin 校验和 PAT 契约见用户鉴权与登录会话。

🔄 渠道重试与缓存

重试配置： 设置 → 运营设置 → 通用设置 → 失败重试次数

缓存配置：

  • REDIS_CONN_STRING：Redis 缓存（推荐）
  • MEMORY_CACHE_ENABLED：内存缓存

🔗 相关项目

上游项目

项目 说明
One API 原版项目基础
Midjourney-Proxy Midjourney 接口支持

配套工具

项目 说明
new-api-key-tool Key 额度查询工具
new-api-horizon New API 高性能优化版

💬 帮助支持

📖 文档资源

资源 链接
📘 常见问题 FAQ
💬 社区交流 交流渠道
🐛 反馈问题 问题反馈
📚 完整文档 官方文档

🤝 贡献指南

欢迎各种形式的贡献！

  • 🐛 报告 Bug
  • 💡 提出新功能
  • 📝 改进文档
  • 🔧 提交代码

📜 许可证

本项目采用 GNU Affero 通用公共许可证 v3.0 (AGPLv3) 授权。

本项目为开源项目，在 One API（MIT 许可证）的基础上进行二次开发。

如果您所在的组织政策不允许使用 AGPLv3 许可的软件，或您希望规避 AGPLv3 的开源义务，请发送邮件至：support@quantumnous.com

🌟 Star History

Star History Chart

💖 感谢使用 New API

如果这个项目对你有帮助，欢迎给我们一个 ⭐️ Star！

官方文档 • 问题反馈 • 最新发布

Built with ❤️ by QuantumNous