New API 完整部署手冊|統一管理多家 LLM 的開源自架閘道

01這是什麼

一個聚合多家模型的 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 格式之間雙向轉換;通道層支援加權隨機分配、失敗自動重試與使用者層級限速。一次請求進來,依序經過鑑權、路由、格式轉換、上游呼叫,最後落到計費記錄。

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

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

— New API 官方 README · 專案定位

02Docker 部署

一行 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

03功能總覽

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

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 模式;可配置合法授權的自訂上游端點

04設定要點 · 官方文件

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

以下要點整理自官方 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 · 快取設定

05實戰範例

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

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



# 1. 啟動容器(SQLite,單機)
$ docker run --name new-api -d -p 3000:3000 -v ./data:/data calciumion/new-api:latest
ok: 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"}]}'


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


# 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"}]}'


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


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

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

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

這段示範的重點

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

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

06部署前先看清楚

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

警告

**僅限合法授權場景。**官方明定本專案僅供合法且經授權的 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 遷移先備份。**雖然資料庫相容、可平滑遷移,遷移與升級前仍應完整備份資料,並在非生產環境驗證後再切換。

07進階路徑

從單機到多節點高可用。

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

擴展與運維

**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, 收斂成一個相容端點。

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

請求進入

金鑰鑑權

通道路由

格式轉換

上游模型

計費記錄

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

不用 Compose:單一 docker run

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

現代化主控台

五種介面語言

資料庫可沿用

三層權限管理

第三方登入

配額計費

快取命中統計

雙向格式轉換

思考內容轉換

智慧路由

多模態介面

推理強度控制

支援的模型與服務

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

SET 01 · 多機部署必設 SESSION_SECRET

SET 02 · 共用 Redis 要設 CRYPTO_SECRET

SET 03 · 用 SQL_DSN 切換資料庫

SET 04 · 串流逾時調 STREAMING_TIMEOUT

SET 05 · 大型影像調 STREAM_SCANNER_MAX_BUFFER_MB

SET 06 · 用 MAX_REQUEST_BODY_MB 限制請求體

SET 07 · 失敗重試在後台設定

SET 08 · 快取優先用 Redis

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

這段示範的重點

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

從單機到多節點高可用。

擴展與運維

最該讀的三份官方文件

請求進入

金鑰鑑權

通道路由

格式轉換

上游模型

計費記錄

不用 Compose:單一 docker run

現代化主控台

五種介面語言

資料庫可沿用

三層權限管理

第三方登入

配額計費

快取命中統計

雙向格式轉換

思考內容轉換

智慧路由

多模態介面

推理強度控制

支援的模型與服務

SET 01 · 多機部署必設 SESSION_SECRET

SET 02 · 共用 Redis 要設 CRYPTO_SECRET

SET 03 · 用 SQL_DSN 切換資料庫

SET 04 · 串流逾時調 STREAMING_TIMEOUT

SET 05 · 大型影像調 STREAM_SCANNER_MAX_BUFFER_MB

SET 06 · 用 MAX_REQUEST_BODY_MB 限制請求體

SET 07 · 失敗重試在後台設定

SET 08 · 快取優先用 Redis

這段示範的重點

擴展與運維

最該讀的三份官方文件

相關文件

地端 Claude 開發部署手冊|GitHub × Vercel × Cloudflare 標準工作流

把 Mac mini 變成 Jarvis|用 Hermes Agent 連接 Gmail、Slack 與整台主機的常駐代理設定手冊

剪映 Agent 剪輯技能 完整教學|讓 AI 自動完成配音、字幕、配樂與匯出

剪映 Agent 剪輯技能完整教學|讓 AI 自動完成配音、字幕、配樂與匯出