部署手冊 · Field Manual 2026

github.com/QuantumNous/new-api · 37.3k ★

第 01 期 · LLM 閘道 / AI 基礎設施

把多家 LLM,
收斂成一個
相容端點。

New API 是一套開源的 LLM 閘道與 AI 資產管理系統,基於 One API 二次開發。它把 OpenAI、Claude、Gemini 等多家模型聚合到統一介面,並提供金鑰管理、配額計費、用量統計與多人權限控制。後端以 Go 撰寫,可用 Docker 一行指令自架,資料庫相容原 One API。

37.3k

GitHub Stars

8.5k

Forks

相容 API 格式

AGPL

開源授權 v3.0

這是什麼

一個聚合多家模型的
LLM 閘道。

New API 是 QuantumNous 維護的開源專案,定位為「新一代 LLM 閘道與 AI 資產管理系統」。它解決的是同一個問題:當團隊同時用 OpenAI、Claude、Gemini、DeepSeek、Qwen 等多家模型時,金鑰分散、計費混亂、介面不一致。New API 把這些上游聚合到一個 OpenAI 相容端點之後,呼叫端只需要面對單一介面與單一金鑰。

它基於 One API(MIT 授權)二次開發,後端以 Go 撰寫(占 99.8% 程式碼),資料庫完全相容原 One API,既有部署可平滑遷移。除了轉發,它還內建管理層:現代化主控台、用量與成本統計、權杖分組與模型限制、多人權限,以及對 EPay、Stripe 的內部儲值與配額分配。

閘道的核心價值在格式轉換與智慧路由。同一個端點,改 model 名稱就能在 OpenAI 與 Claude Messages 格式之間雙向轉換;通道層支援加權隨機分配、失敗自動重試與使用者層級限速。一次請求進來,依序經過鑑權、路由、格式轉換、上游呼叫,最後落到計費記錄。

New API 請求生命週期

請求進入→ 金鑰鑑權→ 通道路由→ 格式轉換→ 上游模型→ 計費記錄

Next-Generation LLM Gateway and AI Asset Management System.
新一代 LLM 閘道與 AI 資產管理系統。

— New API 官方 README · 專案定位

Docker 部署

一行 docker run,
三千埠開始服務。

部署只需要 Docker 或 Docker Compose。資料庫預設用內建 SQLite(Docker 需掛載 /data 目錄);若要用遠端資料庫,需 MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6。官方建議生產環境用 Docker Compose 搭配 MySQL 與 Redis。最新 Docker 映像為 calciumion/new-api:latest。

# 1. 取得專案
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# 2. 編輯 docker-compose.yml(資料庫、Redis、連接埠)
nano docker-compose.yml

# 3. 啟動服務
docker-compose up -d
      

不用 Compose:單一 docker run

個人或小規模使用,可直接用 docker run。預設走 SQLite;指定 SQL_DSN 即可改接 MySQL。完成後造訪 http://localhost:3000 開始設定通道與權杖。

# 使用 SQLite(預設)
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

# 使用 MySQL:加上 SQL_DSN
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
      

其他部署方式。除了 Docker,官方支援 1Panel 與寶塔面板(BaoTa ≥ 9.2.0,在應用商店搜尋 New-API 一鍵安裝),以及多節點分散式部署。-v ./data:/data 會把資料存到目前目錄的 data 資料夾,也可改成絕對路徑如 -v /your/path:/data。

功能總覽

閘道之外,
還有一整層管理能力。

New API 的能力分成幾個面向:核心管理介面、鑑權與登入、計費與配額、格式轉換、智慧路由,以及多模態介面支援。下表把官方文件列出的主要功能依面向分組。實務上最常用到的是金鑰與通道管理、配額計費,以及 OpenAI ⇄ Claude 的格式轉換。

核心 · 01

New UI

現代化主控台

重新設計的管理介面,內建視覺化資料看板與用量統計分析。

核心 · 02

i18n

五種介面語言

簡體中文、繁體中文、English、Français、日本語介面切換。

核心 · 03

One API 相容

資料庫可沿用

完全相容原 One API 資料庫,既有部署可直接遷移。

鑑權 · 04

Permission

三層權限管理

權杖分組、模型限制、使用者管理,控制誰能用哪些模型。

鑑權 · 05

OAuth

第三方登入

支援 Discord、LinuxDO、Telegram 授權登入與 OIDC 統一認證。

計費 · 06

Quota

配額計費

依請求、用量、快取命中計價,支援 EPay、Stripe 內部儲值與配額分配。

計費 · 07

Cache Billing

快取命中統計

對 OpenAI、Azure、DeepSeek、Claude、Qwen 等模型統計快取命中計費。

格式 · 08

OpenAI ⇄ Claude

雙向格式轉換

OpenAI 相容與 Claude Messages 格式雙向轉換,亦支援 OpenAI → Gemini。

格式 · 09

Thinking

思考內容轉換

thinking-to-content,將模型推理區塊併入回應內容輸出。

路由 · 10

Routing

智慧路由

通道加權隨機分配、失敗自動重試、使用者層級模型限速。

模型 · 11

Multimodal

多模態介面

涵蓋對話、影像、語音、嵌入、Rerank 與 Realtime 即時對話介面。

模型 · 12

Reasoning Effort

推理強度控制

o3-mini、gpt-5 支援 -high/-medium/-low 後綴;Gemini 可加 -thinking 變體。

支援的模型與服務

模型類型	說明
`OpenAI-Compatible`	OpenAI 相容模型,標準 Chat Completions 介面
`OpenAI Responses`	OpenAI Responses 格式(含 Realtime,支援 Azure)
`Claude`	Claude Messages 格式,含 thinking 思考模型
`Gemini`	Google Gemini 格式,含 thinking 變體
`Rerank`	Cohere、Jina 重排序模型
`Midjourney-Proxy`	Midjourney(Plus)影像介面
`Suno-API`	Suno 音樂生成介面
`Dify` / 自訂上游	Dify ChatFlow 模式;可配置合法授權的自訂上游端點

設定要點 · 官方文件

部署後,
先確認這幾個環境變數。

以下要點整理自官方 README 與環境變數文件,涵蓋多機部署、串流逾時、請求體限制與快取設定。預設值適用大多數單機場景;但多節點部署與高負載環境通常需要明確設定下列變數。

SET 01

多機部署必設 SESSION_SECRET

多節點部署時,若未設定 SESSION_SECRET,各節點之間的登入狀態會不一致,使用者會反覆被登出。這是官方明確標註的多機部署必要項。

來源 · 官方 README · 多機部署

SET 02

共用 Redis 要設 CRYPTO_SECRET

多節點共用同一個 Redis 時,必須設定 CRYPTO_SECRET 作為加密金鑰,否則節點無法解密共用資料。與 SESSION_SECRET 是兩件事,需分別設定。

來源 · 官方 README · 多機部署

SET 03

用 SQL_DSN 切換資料庫

預設使用內建 SQLite;指定 SQL_DSN 連線字串即可改用 MySQL 或 PostgreSQL。遠端資料庫需 MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6。

來源 · 環境變數文件

SET 04

串流逾時調 STREAMING_TIMEOUT

串流回應逾時預設為 300 秒。上游推理模型回應較慢時,可調高避免長回應被中途切斷。

來源 · 環境變數文件

SET 05

大型影像調 STREAM_SCANNER_MAX_BUFFER_MB

串流掃描器單行緩衝預設 64 MB。當上游傳回超大的影像或 base64 內容時,需要調高此值,否則串流會解析失敗。

來源 · 環境變數文件

SET 06

用 MAX_REQUEST_BODY_MB 限制請求體

請求體上限預設 32 MB,以解壓後大小計算,可防止超大請求或 zip bomb 耗盡記憶體。超過上限會回傳 413。

來源 · 環境變數文件

SET 07

失敗重試在後台設定

通道失敗自動重試的次數,在管理後台調整:設定 → 運營設定 → 通用設定 → 失敗重試次數。搭配通道加權隨機,可提升可用性。

來源 · 官方 README · 通道重試

SET 08

快取優先用 Redis

設定 REDIS_CONN_STRING 啟用 Redis 快取(官方建議);或用 MEMORY_CACHE_ENABLED 走記憶體快取。多機環境一律建議使用 Redis。

來源 · 官方 README · 快取設定

實戰範例

同一個端點,
切換 OpenAI 與 Claude。

下面這段示範閘道的核心價值:啟動容器後,在管理後台建立通道與權杖,接著用標準的 OpenAI /v1/chat/completions 介面呼叫。要切換到 Claude,只需改 model 名稱——由 New API 在後端做格式轉換,呼叫端的程式碼完全不用改。

~/new-api · docker · v1.0.0-rc.10

# 1. 啟動容器(SQLite,單機) $ docker run --name new-api -d -p 3000:3000 -v ./data:/data calciumion/new-api:latest a3f1c9d8... new-api 已啟動,監聽 :3000

# 2. 開瀏覽器到 localhost:3000,登入後新增上游通道與權杖 # 通道:填入你合法取得的上游金鑰(OpenAI、Claude...) # 權杖:產生一組 sk-xxx 給呼叫端使用

# 3. 用標準 OpenAI 格式呼叫 New API $ curl http://localhost:3000/v1/chat/completions \ -H "Authorization: Bearer sk-xxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"model":"gpt-4o","messages":[{"role":"user","content":"ping"}]}'

{ "id": "chatcmpl-...", "model": "gpt-4o", "choices": [{"message": {"role": "assistant", "content": "pong"}}], "usage": {"prompt_tokens": 9, "completion_tokens": 1} }

# 4. 同一個端點,只改 model 名稱就能打 Claude # OpenAI 格式進、Claude Messages 由 New API 轉換 $ curl http://localhost:3000/v1/chat/completions \ -H "Authorization: Bearer sk-xxxxxxxx" \ -d '{"model":"claude-3-7-sonnet-20250219","messages":[{"role":"user","content":"ping"}]}'

{ "model": "claude-3-7-sonnet-20250219", "choices": [{"message": {"content": "pong"}}] }

✓ 呼叫端程式碼不變,模型隨意切換 ✓ 用量、成本、快取命中已記入後台統計

OpenAI 格式進,Claude Messages 出。
呼叫端只面對一個端點、一組金鑰。

— New API 的格式轉換,讓上游切換對應用端透明

這段示範的重點

應用端始終呼叫同一個 /v1/chat/completions 端點,改的只是 model 欄位。格式轉換發生在閘道內部:把 OpenAI 請求轉成 Claude Messages 再轉回 OpenAI 回應格式。這意味著既有的 OpenAI SDK 程式碼不需修改,就能接上 Claude 或 Gemini。

每一次呼叫都會經過權限與配額檢查,並把用量、成本與快取命中寫入後台統計。對需要管理多人、多金鑰、多模型的團隊,這層集中管理正是 New API 與直接呼叫各家 API 的差別。

部署前先看清楚

自架閘道,
有合規與運維邊界。

僅限合法授權場景。官方明定本專案僅供合法且經授權的 AI API 閘道使用;使用者須合法取得上游 API 金鑰與授權,並遵守上游服務條款。對外提供生成式 AI 服務時,須自行完成備案、內容安全、實名、日誌留存、稅務等義務。
多機部署必設 SESSION_SECRET 與 CRYPTO_SECRET。未設 SESSION_SECRET 會造成各節點登入狀態不一致;共用 Redis 未設 CRYPTO_SECRET 則資料無法解密。兩者是多機部署的必要前提。
遠端資料庫有版本下限。需 MySQL ≥ 5.7.8 或 PostgreSQL ≥ 9.6;使用 SQLite 時 Docker 必須掛載 /data 目錄,否則資料不會持久化。
AGPL-3.0 授權義務。修改版若呈現使用者介面,須保留作者標示「Frontend design and development by New API contributors.」,並在介面顯著位置保留指向原專案的可見連結。組織政策不允許 AGPLv3 者,須聯繫 support@quantumnous.com 取得商業授權。
部分格式轉換仍有限制。Gemini → OpenAI 目前僅支援文字,尚不支援 function calling;OpenAI ⇄ OpenAI Responses 的雙向轉換仍在開發中。導入前請確認你需要的轉換路徑已支援。
最新版本仍是 release candidate。截至 2026 年,最新版為 v1.0.0-rc.10(2026 年 5 月),屬預發布版本。正式生產環境上線前請充分測試並鎖定版本。
自訂上游須合規。「自訂上游」功能只能配置合法授權的端點,並遵守該上游的服務條款;不得用於繞過授權或轉售未授權的模型服務。
從 One API 遷移先備份。雖然資料庫相容、可平滑遷移,遷移與升級前仍應完整備份資料,並在非生產環境驗證後再切換。

進階路徑

從單機到多節點高可用。

把單機跑通之後,常見的下一步是擴展規模、補上監控,以及接上週邊工具。下列路徑都對應官方文件或官方維護的相關專案。

擴展與運維

1. 多節點高可用。設定共用的 Redis 與遠端資料庫,水平擴展多個閘道節點;務必設定 SESSION_SECRET 與 CRYPTO_SECRET。

2. 高效能版本 new-api-horizon。官方維護的效能優化分支,針對高負載場景調校,適合作為大流量部署的替代選擇。

3. 金鑰查詢工具 new-api-key-tool。搭配使用,可查詢權杖的配額與用量,方便對內或對授權客戶核對額度。

4. 接 Pyroscope 做效能剖析。設定 PYROSCOPE_URL 等變數,把閘道的 CPU、mutex、block 取樣資料送往 Pyroscope 伺服器。

5. 面板一鍵部署。不熟 Docker 指令時,可用 1Panel 或寶塔面板(≥ 9.2.0)在應用商店搜尋 New-API 一鍵安裝。

最該讀的三份官方文件

① 官方文件——部署、API、FAQ 與社群互動的完整入口。
② 環境變數文件——所有可調設定的完整清單與預設值。
③ API 文件——閘道支援的各介面與請求格式說明。

本專案基於 One API(MIT 授權)二次開發,
以 GNU AGPL v3.0 釋出。

— New API 官方 README · 授權說明

一個聚合多家模型的LLM 閘道。

一行 docker run,三千埠開始服務。

不用 Compose:單一 docker run

閘道之外,還有一整層管理能力。

支援的模型與服務

部署後,先確認這幾個環境變數。

多機部署必設 SESSION_SECRET

共用 Redis 要設 CRYPTO_SECRET

用 SQL_DSN 切換資料庫

串流逾時調 STREAMING_TIMEOUT

大型影像調 STREAM_SCANNER_MAX_BUFFER_MB

用 MAX_REQUEST_BODY_MB 限制請求體

失敗重試在後台設定

快取優先用 Redis

同一個端點,切換 OpenAI 與 Claude。

這段示範的重點

自架閘道,有合規與運維邊界。

從單機到多節點高可用。

擴展與運維

最該讀的三份官方文件

一個聚合多家模型的
LLM 閘道。

一行 docker run,
三千埠開始服務。

閘道之外,
還有一整層管理能力。

部署後,
先確認這幾個環境變數。

同一個端點,
切換 OpenAI 與 Claude。

自架閘道,
有合規與運維邊界。