企业官网建设流程全解析

• API网关
• 后端
• 负载均衡

本文以 GPT-Load 2.0 为主线，完整讲解这一自托管 AI 网关的架构设计、快速部署、首次配置、支持协议与内置渠道、数据库与密钥安全、全部环境变量，以及从 1.x 平滑切换的注意事项。读完本文，你将掌握如何用一条 Base URL 加一个 AccessKey 统一管理 OpenAI、Anthropic、Gemini、Codex、Claude、Grok 等多渠道的 API Key 与订阅账号，并理解其调度容错与日志用量体系的实现原理。

一、为什么需要 GPT-Load：统一入口背后的设计

GPT-Load 的核心思想极其简洁：你的应用只需要配置一个地址（Base URL）和一个 AccessKey，上游的服务商、账号、凭据、模型与路由策略全部在管理界面中完成。这样应用侧完全无需改造代码，即可获得多凭据调度、故障隔离与用量统计能力。

围绕这一思想，README 明确了四项核心能力：

• 统一入口，保留原生协议：官方 API、云平台、模型服务和兼容中转统一管理，客户端继续使用 OpenAI、Anthropic 或 Gemini 原生接口，不需要引入任何 SDK 或协议转换层。
• 统一管理 API Key 与订阅账号：Codex、Claude、Antigravity、Grok 等订阅渠道与普通 API Key 渠道共享同一套凭据管理、调度与健康体系。
• 内置调度与故障隔离：多凭据调度、可配置权重、重试、冷却（cooldown）、黑名单与会话亲和（session affinity），降低单个凭据过载或失效对整体可用性的影响。
• 可观测、易部署、数据自持：单个 Go 二进制内嵌管理界面，提供健康、路由、日志、用量与成本估算，存储层支持 SQLite、MySQL、PostgreSQL，凭据在本地加密保存。

从源码结构看，这些能力被清晰地拆分为多个内部模块：internal/gateway承担数据面（协议路由与转发）、internal/scheduler承担渠道与凭据的调度选择、internal/control承担管理面（渠道、分组、AccessKey、用量等 CRUD 与 API）、internal/storage承担持久化。整个进程入口在 main.go：无参数时直接启动服务，带参数时进入help、version、update、service等子命令分发。

二、快速开始：五分钟跑起一个网关

1. 启动服务

前置条件是需要 Docker 与 Docker Compose。官方 Compose 文件位于 docker-compose.yml，启动过程如下：

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

该健康检查端点返回{"status":"ok","version":...}，其实现位于 internal/app/http_routes.go；Docker Compose 的healthcheck也使用同一端点（见 docker-compose.yml）。

首次启动会自动生成管理密钥，读取并妥善保存：

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

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

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

管理密钥的解析逻辑位于 internal/platform/authkey/authkey.go：显式设置AUTH_KEY时校验其不含空白字符；未设置时在DATA_DIR下读取或生成auth.key文件。docker compose exec命令读取的正是这个文件。

2. 完成首次配置

首次配置只需三步：

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

订阅渠道的 OAuth 回调端口

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

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

三、界面与可观测性

分组总览统一展示渠道、模型、凭据数量、流量与健康状态；用量统计页面展示请求趋势、缓存命中率、Token 分类与成本估算。管理界面相关的构建产物位于internal/webui（内嵌于单个 Go 二进制的 Web 资源）与web/src（前端源码，采用 Vue 技术栈），请求日志、用量与成本计算的后端实现分别位于internal/requestlog、internal/usage与internal/pricing。

四、支持范围：客户端协议与内置渠道

客户端协议

数据面 HTTP 路由的挂载定义在 internal/gateway/http_routes.go：命名空间前缀覆盖/v1、/v1beta、/mistral，全部请求先经过 AccessKey 认证（httproute.AuthAccessKey），再按端点目录分派。具体协议与入口如下表：

这些协议在internal/dialect中分别有独立的解析与转换实现，例如 internal/dialect/mistral.go 精确匹配/v1/ocr、/v1/audio/transcriptions、/v1/audio/speech及/mistral/v1/audio/voices等 Mistral 原生路径；internal/dialect/gemini.go 定义了geminiGenerationPrefix = "/v1beta/models/"，对应的嵌入端点行为由 internal/dialect/gemini_embeddings_test.go 大量用例覆盖。README 中列出的全部端点（包括 Rerank 与 Mistral OCR/音频）均在测试中存在对应验证。

内置渠道

• 官方与云平台：OpenAI、Anthropic、Gemini、xAI、Azure OpenAI、AWS Bedrock、Google Vertex AI
• 常用模型服务：DeepSeek、Moonshot AI、SiliconFlow、Zhipu AI、Alibaba、Volcengine、OpenRouter、Cline、Groq、Cerebras、Mistral、Nebius、Parasail、Wafer、Hugging Face（聊天）、Cohere（文本重排序）、OpenCode Go、OpenCode Zen
• 订阅渠道：Codex、Claude、Antigravity、Grok
• 自定义：OpenAI Compatible（任意兼容中转）

各渠道的协议适配注册在 internal/channel/builtins.go 及internal/channel/modules子目录中；渠道的品牌图标来自 Lobe Icons，仅用于标识对应的上游服务商，商标权归各自所有者，本项目与这些服务商没有从属或背书关系。

五、部署与数据：SQLite、外部数据库与密钥安全

数据与密钥的存放位置

Docker Compose 默认使用应用托管的 SQLite，数据存放在gpt-load-data具名卷中，包含数据库（gpt-load.db）、auth.key和encryption.key。卷挂载与DATA_DIR=/app/data的固定配置见 docker-compose.yml。

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

凭据加密的实现位于 internal/platform/encryption/encryption.go：使用ENCRYPTION_KEY派生出 AES-256-GCM 密钥与 HMAC-SHA256 指纹密钥（域分离派生gpt-load/encryption/aes-256-gcm/v1与gpt-load/encryption/fingerprint-hmac/v1），每次加密都使用随机 nonce；LoadOrCreateKeyMaterial（同文件第 71-87 行）在未显式配置时于DATA_DIR/encryption.key生成 32 字节随机密钥。这就是"密钥必须与数据库一起备份"这一要求的源码依据。

使用外部数据库

通过统一的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

DSN 解析逻辑位于 internal/platform/config/config.go：空值回落到${DATA_DIR}/gpt-load.db（应用托管模式，仅允许 SQLite）；支持file:、sqlite:前缀的 SQLite 路径或 URL，以及mysql、postgres/postgresql网络 URL；不支持的 scheme 会直接报错。MySQL 与 PostgreSQL 连接池上限由DATABASE_MAX_OPEN_CONNECTIONS（默认 10）与DATABASE_MAX_IDLE_CONNECTIONS（默认 5）控制，且要求空闲连接数不大于打开连接数（见 config.go）；SQLite 始终使用单连接。

常用运维命令

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，因此不要用latest拉取 2.0。

使用原生二进制（非 Docker 部署）

从 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管理已安装服务——这一子命令体系对应 main.go 中的命令分发逻辑（service分支）。

六、环境配置：全部变量详解

应用启动时读取当前目录的.env，已有的进程环境变量优先。这一加载逻辑实现在 internal/platform/config/config.go：调用godotenv.Load()读取.env，但os.Getenv读取的是进程环境变量，因此已有的进程环境变量永远覆盖.env。除非特别说明，修改后需要重启进程或容器。完整配置模板见 .env.example。

环境代理仅在凭据、Group 和全局设置都未指定代理时生效，即代理优先级为：凭据级 > Group 级 > 全局设置 > 环境代理。

补充：Codex 语音中继（Voice Relay）相关变量

.env.example中还包含一组用于 Codex 实时语音/媒体中继的变量：CODEX_LIVE_PUBLIC_IP（客户端可达的媒体 IP，必填）、CODEX_LIVE_UDP_PORT_MIN/CODEX_LIVE_UDP_PORT_MAX（默认50000/50127）、CODEX_LIVE_MAX_SESSIONS（默认 32，范围 1–1024）、CODEX_LIVE_ICE_SERVERS（可选 JSON 数组，最多 16 个 ICE/STUN/TURN 服务器）。这些配置的完整解析与校验在 config.go，例如CODEX_LIVE_PUBLIC_IP必须是合法 IP、UDP 端口必须成区间、TURN 服务器必须带凭据。启用语音中继时需叠加 Compose override 文件：

docker compose -f docker-compose.yml -f docker-compose.voice.yml up -d

对应的端口发布与必填校验见 docker-compose.voice.yml。Codex 语音默认直连媒体（Off / Direct / Relay 三选一，可在系统设置中切换，Codex 分组可覆盖此默认值）；只有 Relay 模式会使用上述进程级媒体配置，且现有媒体中继部署必须选择 Relay。

七、调度与故障隔离的实现原理

README 声称的"多凭据调度、可配置权重、重试、冷却、黑名单与会话亲和"，在源码中都有对应落点：

• 调度选择：internal/scheduler包负责"无 IO、无持久化"的纯内存调度决策。核心的Iterator（见 internal/scheduler/scheduler.go）按 Group 与 RouteMode 分层构建候选池（candidatePool），对每个候选凭据按其权重（weightedCredential）参与选择，并记录已尝试（tried）与跳过（skippedGroups）的状态，全部候选耗尽时返回ErrExhausted。权重、优先级、路由模式等策略在internal/scheduler下有fair.go、priority_test.go、route_strategy_test.go等实现与测试佐证。
• 冷却（cooldown）：internal/scheduler/model_cooldown.go中的modelCooldownUntil与Iterator.CooldownUntil依据模型与凭据的冷却时间表计算下一次可路由时刻，用于失败后熔断。
• 会话亲和（affinity）：internal/gateway/affinity.go基于 AccessKey、客户端协议与 Prompt 缓存键派生亲和键（affinity.DeriveKey），优先把会话固定到同一凭据上，减少缓存失效；底层缓存在internal/affinity。
• 执行与重试：internal/execution提供请求执行边界、重试预算（retry_budget测试见 internal/gateway/retry_budget_test.go）与错误分类；internal/health负责错误分类与执行判定（execution_judge），决定是否对凭据降级或熔断；internal/ratelimit提供 AccessKey 级别 RPM 与并发限制（internal/gateway/concurrency.go中的TryAcquireGroup）。

从架构上讲，internal/gateway/handler.go的Handler在每次数据面请求中依次完成：认证 AccessKey（http_routes.go）→ 并发准入 → 配额准入 → 调度选路 → 上游转发 → 用量捕获，任何一步失败都按错误分类进入重试或熔断流程。

八、从 1.x 切换：完整重写带来的兼容性边界

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

如果你正在使用 1.x，请遵守以下迁移纪律：

1. 为 2.0 部署独立的数据库、DATA_DIR、端口和 Docker 卷，不要指向 1.x 的数据目录；
2. 在隔离环境中完整验证新实例的渠道、分组与 AccessKey 行为；
3. 验证完成后再切换业务流量，并在回滚窗口关闭前保留原 1.x 部署，以便随时回滚；
4. 1.4.x 维护线的文档请查阅官方文档站（README 中给出 https://www.gpt-load.com/docs 入口）。

九、开源依赖与安全边界

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

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

十、写在最后：一条实用的启动检查清单

完成部署后，建议按以下顺序做一次自检：

1. curl --fail http://127.0.0.1:3001/health确认进程健康；
2. 确认auth.key已安全保存，且encryption.key与数据库放在同一备份介质中；
3. 在管理界面完成"渠道 → 分组 → AccessKey"三步配置，并用生成的 AccessKey 实测一次POST /v1/chat/completions；
4. 若使用订阅渠道，确认 OAuth 回调端口（1455、54545、51121）在防火墙中可达；
5. 查看分组总览与用量统计页，确认凭据健康状态与 Token/成本数据正常入库；
6. 如需外部数据库，先在.env中配置DATABASE_DSN并重启，验证internal/storage侧连接池参数生效。

至此，你已具备从部署、配置到理解调度原理的完整闭环，可以放心地把 GPT-Load 作为统一入口接入你的多渠道 AI 应用。

• API网关
• 后端
• 负载均衡