gpt-load/README_CN.md

GPT-Load

面向多渠道、多凭据场景的自托管 AI 网关

把 API Key、订阅账号、流量调度、故障处理、请求日志与用量统计，收进同一个入口。

English · 中文 · 日本語 | 官方网站

---

赞助商

_{成为赞助商}

赞助商详情（可折叠）

	OfoxAI：一个平台，连接文本、图像与视频 AI OfoxAI 是统一的 AI API 平台，汇集多家文本、图像和视频模型，支持 OpenAI 兼容接口及 Anthropic、Gemini 原生接口。开发者可通过一个平台为 AI 应用、智能体和内容创作接入模型，按任务选择合适的能力。 探索 OfoxAI 模型与 API →
	PackyCode PackyCode 是一家稳定、高效的 API 中转服务商。一句话接入主流大模型。统一域名、统一密钥、智能容灾切换，97% 可用性。人民币1:1充值，无汇率无手续费坑，新用户首充立享折扣 + $1免费体验额度，多分组折扣低至 2 折起，提供专属Codex/Claude Code高速通道。点此链接注册，立即开始使用！
	一个入口，接入并管理全球主流AI模型 Fluxion AI面向个人开发者、技术团队与企业，通过统一API接入并管理全球主流AI模型；通过多线路动态调度提升可用性，模型表现、响应时间与费用透明可查。根据不同模型与线路，API调用成本较官方或基准价格可降低40%—98%。立即访问并注册，即可获得 $7 API 额度。（专属链接）
	保护并加速网站与 API，兼顾中国大陆及全球的访问体验，并通过客户端 SDK，将加速与安全能力延伸至原生/移动 App — 自建私有部署 CDN｜订阅式高防 CDN｜自主可控、灵活组合的 CDN 网络。
	感谢 APIMart 赞助了本项目！APIMart 是专注 AI 图片/视频生成的低价 API 平台，GPT-Image-2 低至 $0.006/张，1 美元可出图 160+ 张。图片、视频一套异步 API 通吃，提交任务拿 ID、回调取结果，跑批万张不超时、换模型不改代码。按量付费、无月费，通过此注册链接注册即可开用。

为什么选择 GPT-Load

应用只需要配置一个地址和一个 AccessKey。后面的服务商、账号、凭据、模型与路由策略，全部在管理界面里完成。

• 统一入口，保留原生协议 — 官方 API、云平台、模型服务和兼容中转统一管理；客户端继续使用 OpenAI、Anthropic 或 Gemini 原生接口，无需改造代码。
• 统一管理 API Key 与订阅账号 — Codex、Claude、Antigravity、Grok 等订阅渠道与 API Key 渠道共享凭据管理、调度和健康体系。
• 内置调度与故障隔离 — 多凭据调度、可配置权重、重试、冷却、黑名单与会话亲和，降低单个凭据过载或失效的影响。
• 可观测、易部署、数据自持 — 提供健康、路由、日志、用量与成本估算；单个 Go 二进制内嵌管理界面，支持 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'

打开 http://127.0.0.1:3001，用该密钥登录控制台。

也可以在启动前通过 .env 里的 AUTH_KEY 显式指定管理密钥。默认只监听本机地址，不会直接暴露到公网。

2. 完成首次配置

首次配置只需三步：

1. 添加渠道 — 选择上游服务，填入一个或多个 API Key；订阅渠道按界面提示完成 OAuth 授权或导入凭据。
2. 创建 Group — 选择渠道，配置可用模型与运行策略。
3. 创建 AccessKey — 设置允许访问的 Group 与客户端协议，把生成的 AccessKey 交给应用使用。

订阅渠道的 OAuth 回调端口

Codex、Claude、Antigravity 的 OAuth 客户端使用固定回调端口。Compose 会把它们发布到 HOST 配置的地址，默认是 127.0.0.1；设置 HOST=0.0.0.0 时，这些回调端口也会发布到宿主机的全部网络接口。因为端口由上游客户端固定，同一台机器同一时刻只能运行一个默认 Compose 实例。

如果通过 SSH 或远程浏览器操作，浏览器的 localhost 可能到不了 GPT-Load —— 此时把完整回调 URL 复制到授权弹窗里即可完成流程。

界面预览

分组总览 — 统一查看渠道、模型、凭据数量、流量与健康状态

用量统计 — 查看请求趋势、缓存命中率、Token 分类与成本估算

支持范围

客户端协议

协议	主要入口
OpenAI Chat Completions	POST /v1/chat/completions
OpenAI Responses	/v1/responses 及其资源路径
OpenAI Images	POST /v1/images/...
OpenAI Embeddings	POST /v1/embeddings
Rerank	POST /v1/rerank
Anthropic Messages	POST /v1/messages
Gemini	/v1beta/models/...

每个渠道会明确声明自己可执行的协议与能力。GPT-Load 在受支持的能力之间做转换，但不是任意协议、任意 JSON 的通用转换器。

Embeddings 首期只在 OpenAI、OpenRouter 和 OpenAI Compatible API Key 渠道提供原生 OpenAI-compatible Wire，不支持订阅渠道或协议互转。未设置协议过滤器的 AccessKey 会按既有语义允许全部已启用协议，升级后也会获得 Embeddings 访问能力；最小权限部署请显式配置协议过滤器。

Rerank 使用独立的 rerank 协议，在 OpenAI Compatible、New API、GPT-Load API Key 渠道支持 POST /v1/rerank。请求使用 model、query 和纯文本 documents 数组，可传 top_n、return_documents 等上游参数；不支持流式、订阅渠道或协议互转。OpenAI Compatible 的 Base URL 是完整 API 前缀（如 https://host/v1），New API / GPT-Load 使用网关根地址；上游必须提供兼容 Rerank 接口。未设置协议过滤器的 AccessKey 也会获得 Rerank 访问能力。仅有 search_units 等非 Token 计量时保持未计价，不将其视为 Token 或免费请求。

内置渠道

• 官方与云平台：OpenAI、Anthropic、Gemini、xAI、Azure OpenAI、AWS Bedrock、Google Vertex AI
• 常用模型服务：DeepSeek、Moonshot AI、SiliconFlow、Zhipu AI、Alibaba、Volcengine、OpenRouter、Groq
• 订阅渠道：Codex、Claude、Antigravity、Grok
• 自定义：OpenAI Compatible（任意兼容中转）

部署与数据

Docker Compose 默认使用应用管理的 SQLite，数据存放在 gpt-load-data 具名卷中，包含数据库、auth.key 和 encryption.key。

Important

encryption.key 用于解密渠道凭据。备份或迁移时，数据库和密钥必须一起保存；密钥丢失或被替换后，已有加密凭据无法恢复，且当前版本不支持主密钥轮换。

使用外部数据库

通过统一的 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 tag 的 v 前缀（例如 2.0.0-beta.25），2.0-beta 则保留为 2.0 Beta 通道；latest 继续留在 1.x。

使用原生二进制

从 GitHub Releases 下载对应平台的文件，建议先用随附的 SHA256SUMS 校验：

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

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

启动后访问 http://127.0.0.1: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。服务配置目录为 %ProgramData%\GPT-Load 并从其中读取 .env，数据目录为 %ProgramData%\GPT-Load\data。

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

环境配置

应用启动时读取当前目录的 .env，已有的进程环境变量优先。除特别说明外，修改后需要重启进程或容器；常用配置模板见 .env.example。

查看全部环境变量

变量	默认值	说明
HOST	127.0.0.1	Native 模式的监听地址，也是 Compose 主端口和 OAuth 回调端口的默认宿主机发布地址；Compose 容器内部固定监听 0.0.0.0。
PORT	3001	HTTP 服务端口，必须为 1–65535；Compose 同时用于容器端口、宿主机发布端口和健康检查。
BIND_ADDRESS	空，继承 HOST	仅用于 Compose，单独覆盖主服务端口的宿主机发布地址，不改变 OAuth 回调端口。
OAUTH_CALLBACK_BIND_ADDRESS	空，继承 HOST	仅用于 Compose，单独覆盖 OAuth 固定回调端口 1455、54545、51121 的宿主机发布地址。
GRACEFUL_SHUTDOWN_TIMEOUT	10	收到停止信号后等待请求结束的最长时间，正整数，单位秒。
CONTAINER_STOP_GRACE_PERIOD	15s	Compose 强制停止容器前的等待时间，使用 Docker duration，建议大于 GRACEFUL_SHUTDOWN_TIMEOUT。
READ_TIMEOUT	60	HTTP 请求读取超时，正整数，单位秒。
IDLE_TIMEOUT	120	HTTP keep-alive 空闲连接超时，正整数，单位秒。
DATA_DIR	./data	托管数据库、auth.key、encryption.key 和运行状态文件的目录；官方 Compose 固定为 /app/data，Windows Setup 服务固定为 %ProgramData%\GPT-Load\data。
DATABASE_DSN	空，使用 ${DATA_DIR}/gpt-load.db	空值使用应用托管的 SQLite；非空值支持 SQLite 路径或 URL、MySQL URL、PostgreSQL URL，并视为运维方管理的外部数据库。容器内文件路径必须位于已挂载目录。
DATABASE_MAX_OPEN_CONNECTIONS	10	MySQL 和 PostgreSQL 的最大打开连接数，必须为正整数；SQLite 始终使用单连接。
DATABASE_MAX_IDLE_CONNECTIONS	5	MySQL 和 PostgreSQL 的最大空闲连接数，必须为正整数且不大于 DATABASE_MAX_OPEN_CONNECTIONS；SQLite 始终使用单连接。
AUTH_KEY	空，读取或生成 ${DATA_DIR}/auth.key	管理界面和 /api 管理接口的 Bearer 密钥，不是数据面 AccessKey。
ENCRYPTION_KEY	空，读取或生成 ${DATA_DIR}/encryption.key	用于加密渠道凭据；更换或丢失后无法解密已有凭据，必须与数据库一起备份。
HTTP_PROXY	空	HTTP 上游请求的环境代理。
HTTPS_PROXY	空	HTTPS 上游请求的环境代理。
NO_PROXY	空	逗号分隔的不经过环境代理的主机、域名或 IP。
LOG_LEVEL	info	支持 panic、fatal、error、warn、warning、info、debug、trace；无效值会告警并回退到 info。
LOG_FORMAT	text	支持 text、json；其他值会导致启动失败。
MODELS_DEV_AUTO_SYNC_ENABLED	未设置，初始默认 true	未设置时使用管理界面的持久化设置；设置后强制开启或关闭 Models.dev 自动同步，并使管理界面中的同名选项变为只读。

环境代理仅在凭据、Group 和全局设置都未指定代理时生效。

生产使用注意事项

• 默认只监听 127.0.0.1。需要远程访问时，应通过受控网络或带 TLS 的反向代理暴露，并配置 ACL 与防火墙。
• 妥善管理 AUTH_KEY 与 ENCRYPTION_KEY，不要把真实密钥提交到仓库、日志、截图或公开 Issue。
• 2.0 按单应用实例设计，多个实例之间不共享状态，不支持直接横向扩容。
• 用量与成本是基于上游返回数据的估算，用于运行分析和资源评估，不等同于服务商账单或财务对账结果。
• 订阅渠道依赖上游 OAuth 与兼容协议，可能随上游变化调整。请只接入自己有权使用的账号，并遵守对应服务商条款。
• HTTP Responses 的 previous_response_id 续接按协议及现有存储能力自动接入：原生 Responses 且声明由上游管理状态的渠道目前包括 openai、gpt_load、xai、newapi、cliproxyapi、sub2api。按 AccessKey 隔离归属，在当前路由允许时固定原凭据，不受软亲和开关影响；实际状态可用性由上游决定。无状态及转换响应不登记为持久状态。未知 ID（包括升级前或网关外创建的 ID）直接拒绝；Group 参数覆盖不能改写该字段。
• 原生 Responses 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 条，ID 文本合计最多 16 MiB，达到容量时淘汰旧记录。正常停机成功保存 checkpoint 后可在同一数据目录恢复；不保证崩溃恢复或上游历史仍有效。
• conversation 与其他既有资源 ID 不在上述归属路由范围内，仍依赖单凭据或上游跨凭据共享资源。

从 1.x 切换

Warning

GPT-Load 2.0 是完整重写的新版本，不能打开、导入或原地迁移 1.x 数据。

部署 2.0 时请使用独立的数据库、DATA_DIR、端口和 Docker 卷，验证完成后再切换业务流量，并在回滚窗口关闭前保留原 1.x 部署。1.4.x 维护线文档见官方文档。

开源依赖

GPT-Load 的部分能力构建在这些开源项目之上，在此致谢：

项目	作用	许可证
Bifrost Core	各服务商的认证、请求响应转换、流式与用量归一化	Apache-2.0
CLIProxyAPI	订阅渠道的 OAuth 与执行适配	MIT
Lobe Icons	管理界面中的渠道品牌图标	MIT

GPT-Load 自身负责凭据存储、账号选择、调度、重试、健康、亲和、日志与用量策略。第三方声明见 THIRD_PARTY_NOTICES.md，许可证全文位于 LICENSES/，每个 Release 另附覆盖 Go 依赖的 CycloneDX SBOM。

各渠道图标用于标识对应的上游服务商，其商标权归各自所有者；本项目与这些服务商没有从属或背书关系。

项目支持

平台支持

社区支持

基础设施支持

---

MIT License · 第三方声明 · 安全政策