ghcr.io/tbphp/gpt-load:2.0.0-rc.16

GPT-Load

一个用于多渠道、多凭证设置的自托管AI网关

API密钥、订阅账户、流量调度、故障处理、请求日志和使用统计——均通过单一入口点管理。

English · 中文 · 日本語 | Official Website

---

赞助商

成为赞助商

赞助商详情（可折叠）

OfoxAI：集文本、图像和视频AI于一体的平台 OfoxAI是一个统一的AI API平台，汇集了来自多个提供商的文本、图像和视频模型。通过兼容OpenAI的端点以及原生Anthropic和Gemini接口，开发人员可以通过一个平台访问用于AI应用、智能体和内容创作的模型。探索OfoxAI模型和API →

保护和加速网站与API，服务中国大陆及全球用户，并通过客户端SDK将加速和安全能力扩展到原生/移动应用——自建私有部署CDN | 订阅制高防护CDN | 独立可控、灵活组合的CDN网络。

感谢APIMart对本项目的赞助！APIMart是一个低成本的AI图像和视频生成API平台——GPT-Image-2低至$0.006/张，每***可生成160+张图像。一个异步API同时覆盖图像和视频：提交任务，获取ID，通过轮询或回调获取结果。可批量处理数万张图像而无超时，无需更改代码即可切换模型。按使用付费，无月费——立即注册开始使用。

为什么选择GPT-Load

您的应用只需一个基础URL和一个AccessKey。提供商、账户、凭证、模型和路由策略均在管理UI中配置。

• 一站式网关，原生协议 —— 统一管理官方API、云平台、模型服务和兼容中继，同时客户端保持其OpenAI、Anthropic或Gemini原生接口。
• API密钥与订阅统一管理 —— Codex、Claude、Antigravity、Grok和API密钥渠道共享凭证管理、调度和健康状态处理。
• 内置调度与故障隔离 —— 多凭证调度、可配置权重、重试、冷却、黑名单和会话亲和性，减少凭证过载或故障的影响。
• 可观测、自托管且部署简单 —— 通过嵌入式UI查看健康状态、路由、日志、使用情况和成本估算，后端支持SQLite、MySQL或PostgreSQL，并对本地凭证进行加密。

快速开始

[!WARNING] 如果您正在使用1.x版本，请先阅读从1.x迁移。2.0版本无法就地打开、导入或迁移1.x数据。

1. 启动服务

需要Docker和Docker Compose。

git clone --depth 1 https://github.com/tbphp/gpt-load.git
cd gpt-load

cp .env.example .env
docker compose up -d

确认服务已启动：

curl --fail http://127.0.0.1:3001/health

首次启动会生成管理密钥。请读取并安全保存：

docker compose exec gpt-load sh -c 'cat /app/data/auth.key'

使用该密钥打开并登录控制台。

[!NOTE] 您也可以在启动前在.env中显式设置AUTH_KEY。默认情况下，服务仅监听回环地址，不暴露到互联网。

2. 初始配置

初始设置需要三个步骤：

1. 添加渠道 —— 选择上游服务并添加一个或多个API密钥。对于订阅渠道，请完成OAuth流程或按提示导入凭证。
2. 创建分组 —— 选择渠道，然后配置可用模型和运行时策略。
3. 创建AccessKey —— 设置其可使用的分组和客户端协议，然后将生成的AccessKey提供给您的应用。

订阅渠道的OAuth回调端口

Codex、Claude和Antigravity的OAuth客户端使用固定回调端口。Compose会在HOST配置的地址上发布这些端口，默认为127.0.0.1；设置HOST=0.0.0.0会将这些回调端口发布到所有主机接口。由于端口由上游客户端固定，一台主机上一次只能运行一个默认的Compose实例。

通过SSH或远程浏览器操作时，浏览器的localhost可能无法访问GPT-Load——请将完整回调URL粘贴到授权对话框中以完成流程。

使用外部数据库

使用统一的 DATABASE_DSN 连接 SQLite、MySQL 或 PostgreSQL：

mysql://user:password@db.example:3306/gpt_load?charset=utf8mb4&collation=utf8mb4_bin
postgres://user:password@db.example:5432/gpt_load?sslmode=require

常用操作：

docker compose logs -f # 查看日志
docker compose pull && docker compose up -d # 更新至最新 2.x 镜像
docker compose stop # 停止服务

官方 Compose 文件使用 ghcr.io/tbphp/gpt-load:2。在正式发布（GA）前，2 跟踪经过验证的 2.0 Beta 和 RC 版本；GA 后，仅跟踪稳定的 2.x 版本。精确镜像标签省略 Git 标签的 v 前缀（例如 2.0.0-beta.25），而 2.0-beta 仍为 2.0 Beta 通道。latest 标签仍停留在 1.x 版本。

使用原生二进制文件

从 https://github.com/tbphp/gpt-load/releases 下载适用于您平台的构建版本，并首先使用附带的 SHA256SUMS 进行验证：

chmod +x ./gpt-load-linux-amd64

HOST=127.0.0.1 DATA_DIR=./data ./gpt-load-linux-amd64

然后打开 http://localhost:3001 访问管理页面。提供适用于 Linux、macOS（amd64/arm64）和 Windows 共五个目标平台的便携构建版本；gpt-load-windows-amd64.exe 仍像以前一样在前台运行。

Windows 桌面用户可下载 gpt-load-windows-setup.exe。经过一次管理员批准后，安装程序会安装并启动低权限 Windows 服务，启用自动启动，并创建指向 GPT-Load 管理页面的桌面和开始菜单快捷方式。安装程序在完成前会显示生成的管理密钥；请在关闭页面之前保存该密钥。受保护的副本保存在 %ProgramData%\GPT-Load\data\auth.key。服务配置及其 .env 文件位于 %ProgramData%\GPT-Load，持久化数据位于 %ProgramData%\GPT-Load\data。

安装新版本安装程序时，会先优雅停止服务再进行更新。Windows 卸载会移除程序和服务，但保留数据。高级用户仍可使用 gpt-load-windows-amd64.exe service start|stop|restart|status 管理已安装的服务。

环境配置

启动时，应用程序会读取当前目录下的 .env 文件；已存在的进程环境变量优先级更高。除非另有说明，否则更改配置需要重启进程或容器；通用配置模板参见 .env.example。

所有环境变量说明

环境代理仅在凭据、分组或全局设置中未指定代理时生效。

• 服务默认仅监听 127.0.0.1。如需远程访问，需通过受控网络或 TLS 反向代理暴露服务，并配置 ACL 和防火墙规则。
• 请谨慎管理 AUTH_KEY 和 ENCRYPTION_KEY。切勿将真实密钥提交到代码仓库、日志、截图或公开议题中。
• 2.0 版本设计为单应用实例。实例之间不共享状态，因此不支持水平扩展。
• 使用量和成本是根据上游响应得出的估算值。它们仅用于运营分析和容量规划，不等同于提供商发票或财务对账数据。
• 订阅渠道依赖于上游 OAuth 和兼容性协议，可能会随着上游变更而变化。仅连接您有权使用的账户，并遵守各提供商的条款。
• 使用 previous_response_id 进行的 HTTP 响应续接会自动使用声明了上游管理存储的原生响应路由：目前包括 openai、gpt_load、xai、newapi、cliproxyapi 和 sub2api。所有权通过 AccessKey 隔离，并在当前路由允许时固定原始凭证，与软亲和性无关；实际状态可用性取决于上游。无状态响应和转换后的响应不会注册为持久状态。未知 ID（包括升级前创建的 ID 或网关外创建的 ID）将被拒绝。组参数覆盖无法修改此字段。
• 原生响应 WebSocket 使用同一端口上的 GET /v1/responses。准入遵循 OpenAI、xAI、Codex 以及兼容的原生 CPA/sub2api 和 GPT-Load 端点所声明的上游能力。客户端可包含布尔值 stream:true/false；两种值均使用 WS 事件流。每一轮交互都会检查当前权限、速率和成本限制以及路由，并生成单独的使用量和成本记录。一个连接保持一个上游身份；不提供 HTTP 回退或对话历史重放功能。
• responses_websocket_enabled 默认启用。显式的组设置会覆盖全局值；否则组将继承全局值。禁用后会立即关闭受影响的 WS 连接并中断生成过程，但不影响 HTTP/SSE。重新启用不会恢复旧连接的临时状态。
• 完整的 stream_id 多路复用和分支功能已为端到端支持该功能的 OpenAI 和 GPT-Load 级联启用。上述其他渠道按顺序运行，并拒绝命名流。预热会向上游发送 generate:false。Codex 续接需要原始活动连接：不支持 store:true 以及通过新连接使用旧 ID 进行恢复。其他渠道的持久续接取决于存储能力和有效的所有权。现有的 Codex SDK 代理、读取和关闭限制 仍然适用。
• 响应绑定在内存中最多保留 30 天，限制为 100,000 条条目和 16 MiB 的 ID 文本；达到容量时会淘汰较旧的条目。正常关闭期间的成功检查点允许从同一数据目录恢复。不保证崩溃恢复和上游状态的持续可用性。
• conversation 和其他现有资源 ID 不在此所有权路由范围内，仍依赖于单个凭证或跨凭证的上游资源共享。

从 1.x 迁移

[!WARNING] GPT-Load 2.0 是完全重写的版本。它无法就地打开、导入或迁移 1.x 数据。

使用独立的数据库、DATA_DIR、端口和 Docker 卷部署 2.0 版本。仅在验证后切换流量，并保留原始 1.x 部署直至回滚窗口关闭。1.4.x 维护版本的文档位于 官方文档。

开源依赖项

GPT-Load 的部分功能基于以下项目构建，在此表示感谢：

GPT-Load 负责凭证存储、账户选择、调度、重试、健康检查、亲和性、日志记录和使用策略。第三方声明位于 THIRD_PARTY_NOTICES.md，完整许可证文本位于 LICENSES/，每个版本均附带涵盖 Go 依赖图的 CycloneDX SBOM。

渠道图标标识其各自的上游提供商。所有商标均归其所有者所有；本项目不隶属于任何提供商，也未获得其背书。

Project support

Platform support

Community support

Infrastructure support

---

MIT 许可证 · 第三方声明 · 安全策略