API 中转站搭建教程：从反向代理到 AI API 网关架构

直接答案：API 中转站搭建不是加一层反向代理就结束。可运维的自建 API 中转站应把控制面与数据面分开：控制面管理用户、密钥、模型、配额和策略；数据面执行 API 中转站鉴权、协议校验、路由、流式转发、Token 计量、限流熔断和可观测性。

实施顺序：先做单协议、单上游、独立密钥和可复算计量，再补第二上游与手动切换，最后才自动路由。每次增加能力都要有指标、审计、回滚与故障演练。

API 中转站搭建的适用边界

自建适合已有后端、运维、安全和值班能力，并确实需要多模型统一、专有网络、细粒度配额、内部审计或定制数据策略的团队。若只是少量内部调用、无人持续修补依赖或无法演练恢复，托管网关通常更容易控制总风险。

边界问题	适合自建的信号	先不要自建的信号
治理需求	需要项目级模型、地域、预算和数据策略	只想少改一个 Base URL
运维能力	有补丁、备份、值班、容量和事故流程	上线后无人维护
正确性	能回归 SSE、工具调用、Token 与错误语义	只能验证非流式文本
供应链	能审查许可证、发布、漏洞和升级路径	只按 Star 数选源码

用开源源码搭建：New API、Sub2API 与 Docker 部署

不想从零写网关，可以先部署现成的开源中转站源码，再用本文后面的架构清单逐项补齐。常见的几个：

• New API（QuantumNous/new-api，AGPL-3.0）：Go 后端加 Web 控制台，带用户、渠道、分组、额度和用量日志；官方 README 给出 Docker 单容器和 Docker Compose 两种部署方式。
• Sub2API（Wei-Shaw/sub2api，LGPL-3.0）：面向订阅额度分发，依赖 PostgreSQL 与 Redis。README 提示使用它可能违反 Anthropic 等上游服务商的服务条款，仅供学习研究。
• One API（MIT）最近一次发布是 2025-02-02 的 v0.6.10；LiteLLM Proxy（Python，主体 MIT）适合团队内部统一网关。

四个项目的许可证、技术栈和维护状态对比见API 中转站源码对比：New API、Sub2API、One API、LiteLLM；想按步骤在服务器上跑起 New API，看 New API Docker 部署教程。源码、部署与架构文章汇总在自建 API 中转站专题。部署完成后，仍按下文的控制面与数据面、流式转发、计量和限流熔断逐项验收。

AI API 网关架构：控制面、数据面与组件

组件	核心职责	关键证据
边缘反向代理	TLS、请求体限制、连接与基础防护	边缘请求 ID、状态与耗时
鉴权与策略	Key 摘要、主体、项目、模型与地域权限	主体、策略版本、拒绝原因
限流与预算	请求、Token、并发、日/月预算	命中规则、窗口、重置时间
协议适配	字段、错误、SSE、工具调用与取消	协议和适配器版本
模型路由	内部模型名、能力、健康、优先级和回退	选中上游、模型和路由原因
上游连接器	凭据、连接池、超时、重试与取消传播	上游请求 ID 和尝试次数
计量存储	Token、缓存、价格版本、预算与对账	不可变请求级事件
可观测与审计	指标、日志、追踪、告警和管理变更	trace、部署版本、操作前后值

开源实现可从官方 LiteLLM repository了解统一模型代理的能力边界，从 Apache APISIX 官方 ai-proxy 插件文档了解网关侧模型转发配置。项目文档用于验证能力，不替代威胁建模和实际压测。

一条请求的完整处理链路

1. 边缘层终止 TLS，限制头部、正文、连接数和总时长，生成请求 ID。
2. 鉴权层只查用户 Key 摘要，绑定租户、项目、模型权限和策略版本。
3. 配额层预扣请求、Token 估算、并发与预算，拒绝必须发生在上游计费前。
4. 协议层校验字段、工具结构和模型能力，形成规范化内部请求。
5. 路由层选择明确 Provider、模型版本与地域，记录选择原因。
6. 连接器使用隔离的上游凭据，设置连接、首字节、空闲和总超时。
7. 流式层逐事件转发并传播取消，不把上游错误伪装成正常正文。
8. 计量层落不可变事件；观测层输出脱敏日志、指标和 trace，结算预扣额度。

用户 Key 与上游凭据必须分离。完整 Key 只在创建时展示一次，数据库保存可识别前缀与不可逆摘要；上游凭据放入密钥管理系统并按环境、Provider 和用途拆分。生命周期设计可参考API Key 安全指南。

反向代理、鉴权与流式转发要点

API 中转站反向代理负责入口，不应承担全部业务策略。鉴权必须在产生上游成本前完成；日志永不记录 Authorization。对 SSE，应关闭不合适的响应缓冲和压缩，保持事件边界，分别监控 TTFT、空闲超时、总时长与中途断流。客户端断开后要取消上游请求，避免继续产生 Token。

工具调用参数可能跨多个 chunk，且并行调用由不同 ID 关联，必须使用状态机聚合。回归用例可参考流式输出与工具调用兼容性。

路由、限流熔断与故障恢复

路由维度至少包括模型能力、租户权限、处理地域、健康状态、延迟目标与预算。限流应同时覆盖请求数、Token、并发和费用，按租户、项目、模型与上游隔离。Envoy Gateway 官方rate limiting 文档区分本地与全局限流，可用于审视不同边界的实现取舍。

重试只应用于明确可重试且尚未产生不可逆副作用的请求，并设置尝试上限、指数退避和随机抖动。熔断器达到失败阈值后进入打开状态，半开阶段仅放少量探针；不要把全部流量瞬间压到备用上游。状态机与演练方法见API 中转站重试与故障切换。

Token 计量、成本公式与示例变量

每个计量事件至少记录请求 ID、租户、项目、Provider、模型、状态、输入输出 Token、缓存用量、重试、价格版本、上游原始用量和时间。估算值必须标注来源，不能冒充上游实测。聚合账单由不可变事件派生，价格版本更新不得回写历史请求。

月度总拥有成本用下面的可见公式复算，不填虚构金额：

monthly_tco = compute + database + cache + observability + egress + on_call_hours × hourly_cost

示例变量：compute取网关实例与弹性余量，database取主从和备份，cache取限流/策略缓存，observability取指标日志追踪的采集与保留，egress取实际出站流量，on_call_hours取当月值班及事故工时，hourly_cost取团队内部核算工时成本。另列上游模型消费，避免把模型账单与网关 TCO 混在一起。

自建 API 中转站的选型维度

维度	验证问题	最低验收
协议兼容	SSE、工具、多模态、取消与错误是否保真	真实 SDK 回归通过
安全边界	租户、密钥、管理面和正文是否隔离	越权与泄露用例通过
计量配额	Token、缓存、重试和价格版本能否复算	请求事件与账单对平
可靠性	超时、重试、熔断、回退和容量是否可控	故障注入不扩大故障
可观测性	指标、日志、trace 和上游 ID 能否关联	单请求端到端定位
维护供应链	许可证、发布节奏、漏洞响应和迁移路径	可复现构建与回滚

源码候选的系统化比较可继续阅读开源 API 中转站源码选型。不要让“支持多少模型”掩盖流式正确性、租户隔离与维护成本。

可复现：本地网关配置、请求与流式验证

以下命令针对已部署在本机的 OpenAI 兼容网关，不连接公网域名。真实值只从环境变量注入；示例不写入凭据文件或命令输出。先设置本地地址、测试密钥和已配置模型：

export GATEWAY_BASE_URL="http://127.0.0.1:4000"
export GATEWAY_API_KEY="${GATEWAY_API_KEY:?set a lab-only key in the environment}"
export GATEWAY_MODEL="${GATEWAY_MODEL:?set a configured model alias}"

test "$(python -c 'import urllib.parse,os; print(urllib.parse.urlparse(os.environ["GATEWAY_BASE_URL"]).hostname)' )" = "127.0.0.1"
curl --fail-with-body --silent --show-error \
  --connect-timeout 3 --max-time 10 \
  "${GATEWAY_BASE_URL}/health/ready"

预期就绪响应示例：

{"status":"ready","policy_version":"gateway-policy-version"}

发送一个非流式示例请求，并保留响应头用于核对请求 ID：

curl --fail-with-body --silent --show-error \
  --connect-timeout 3 --max-time 30 \
  -D response.headers \
  -H "Authorization: Bearer ${GATEWAY_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: local-validation-001" \
  --data "{\"model\":\"${GATEWAY_MODEL}\",\"messages\":[{\"role\":\"user\",\"content\":\"reply only with pong\"}],\"stream\":false,\"max_tokens\":8}" \
  "${GATEWAY_BASE_URL}/v1/chat/completions"

响应字段示例；id、模型别名和 Token 数应来自实际网关，不要在测试中写死：

{
  "id": "gateway-request-id",
  "object": "chat.completion",
  "model": "configured-model-alias",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "pong"}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 3, "completion_tokens": 2, "total_tokens": 5}
}

流式验证使用 --no-buffer，并限制测试输出；应看到若干 data: 事件，最后是 data: [DONE]：

curl --fail-with-body --silent --show-error --no-buffer \
  --connect-timeout 3 --max-time 30 \
  -H "Authorization: Bearer ${GATEWAY_API_KEY}" \
  -H "Content-Type: application/json" \
  --data "{\"model\":\"${GATEWAY_MODEL}\",\"messages\":[{\"role\":\"user\",\"content\":\"reply only with pong\"}],\"stream\":true,\"max_tokens\":8}" \
  "${GATEWAY_BASE_URL}/v1/chat/completions"

# 预期事件：
# data: {"choices":[{"delta":{"content":"pong"}}]}
# data: [DONE]

明确参数边界

参数	实验边界	拒绝或停止条件
入口地址	仅 127.0.0.1 本地验证	主机名不是本机即停止脚本
连接超时	3 秒	网络、监听或 TLS 建连未完成
请求总时长	健康检查 10 秒，生成请求 30 秒	超过后由 curl 取消，网关应传播取消
示例输出	max_tokens=8	模型不支持或策略上限更低时返回明确 4xx
请求正文	仅固定公开测试文本	不得上传个人信息、代码或客户数据

这些数值是本地冒烟测试边界，不是所有工作负载的生产推荐值。正式限额应由并发、TTFT、输出长度、上游配额和错误预算压测得出。

错误/失败模式与验证指标

• 401/403：用户 Key 无效、撤销或无模型权限；不得自动改用上游凭据。
• 400/422：字段、模型能力或工具 schema 不兼容；不得静默删除未知字段。
• 429：租户、Token、并发、预算或上游限额命中；响应应暴露可追踪规则和重置提示。
• 502/503/504：上游错误、熔断打开或超时；有限重试后保留原始错误类别。
• 流提前结束：代理缓冲、空闲超时、客户端断开或上游断流；必须记录终止方与已产生用量。
• 验证指标：状态码、请求 ID、TTFT、总耗时、流中断率、输入输出 Token、重试次数、熔断状态、上游 ID 和策略/部署版本。

故障排查步骤

1. 先检查 /health/ready，区分入口不可达、控制面策略过期与上游不可用。
2. 用 grep -i '^x-request-id:' response.headers 取得请求 ID，在日志、trace 和计量事件中关联。
3. 对比非流式与流式测试；只有流式失败时检查代理缓冲、首字节/空闲超时和取消传播。
4. 核对策略版本、模型映射和上游凭据版本，不在日志中打印 Authorization。
5. 检查请求级计量事件是否只有一条最终结算，重试是否按 attempt 关联而非重复收费。

回滚步骤

1. 停止继续灰度，把路由权重冻结在上一已验证版本，保留失败请求 ID 与指标快照。
2. 恢复上一网关镜像、只读策略快照和协议适配器；数据库 schema 只使用已演练的向后兼容回滚。
3. 重新运行健康、非流式、流式、401、429 与取消用例，确认计量能对平。
4. 确认错误率、TTFT、流中断和熔断恢复基线后再逐步放量；未恢复时保持上一版本。

API 中转站部署与运维检查表

• 按开发、预发、生产镜像环境隔离数据库、缓存、密钥与上游项目。
• 控制面发布带版本的只读策略快照；数据面仅在有限时窗使用最后有效版本。
• 执行无效 Key、越权、超限、429/5xx、慢首字节、流中断和取消回归。
• 数据库与计量事件做备份恢复演练；缓存丢失不能绕过鉴权或配额。
• 监控成功率、错误、TTFT、总耗时、流中断、Token、预算、重试与熔断。
• 日志默认不保存正文和凭据；调试采样必须有脱敏、审批与自动到期。
• 发布采用灰度、版本化策略和一键回滚，升级前验证协议及账单差异。
• 明确值班、事故等级、状态通知、证据保全、复盘和容量扩展阈值。

遥测语义与采集器设计应参考 OpenTelemetry 官方文档；指标落地方式可结合API 网关可观测性指南。

合规与安全风险排查

自建不会自动解决 AI API 合规。上线前仍需确认上游合同和地区、提示词及附件的数据分类、日志与备份地域、保留删除、内容权利和受监管行业要求。安全测试应覆盖对象级与功能级授权、资源消耗、服务端请求伪造、资产清单和第三方 API 消费等风险，可对照官方 OWASP API Security Top 10 2023建立用例。

需要逐项核对合同、数据、跨境与审计时，使用API 中转站合规风险清单，并把结论绑定到项目、地域、模型、数据类别和策略版本。

常见问题

API 中转站常见问题

只用 Nginx 反向代理能完成 API 中转站搭建吗？

不能覆盖完整生产责任。Nginx 可以承担 TLS、入口限制和基础转发，但仍需项目鉴权、模型路由、流式事件处理、Token 计量、配额、审计、限流熔断、凭据管理和故障恢复。

自建 API 中转站第一版应该包含什么？

从单协议、单上游开始，至少完成独立用户密钥、请求 ID、字段验证、明确超时、流式取消、准确计量、基础指标和脱敏日志；验证稳定后再加入第二上游与自动路由。

API 中转站流式转发为什么不能按普通 JSON 处理？

SSE 响应由持续到达的事件组成，工具调用参数还可能跨事件分片。代理必须避免整段缓冲，分别设置首字节、空闲和总超时，并在客户端断开时向上游传播取消。

Token 计量和账单如何做到可复算？

为每个请求保存不可变计量事件，记录模型、输入输出 Token、缓存、重试、价格版本和上游原始用量。聚合账单由事件派生，价格变更不得回写历史记录。

API 中转站限流与熔断应该按什么维度设置？

至少按租户、项目、模型和上游分别控制请求数、Token、并发与预算。熔断基于明确失败窗口，半开阶段只放少量探针，避免所有流量同时涌向备用上游。

API 中转站如何配置反向代理参数边界？

分别设置请求体、请求头、连接、首事件、空闲和总超时，并用本地非流式、SSE、取消和超限请求验证。边界来自工作负载压测与上游限制，不能照搬文章中的冒烟参数。

API 中转站如何验证模型路由和流式响应？

固定模型别名与策略版本，记录实际 Provider、模型、请求 ID 和路由原因；对 SSE 检查事件顺序、工具调用分片、取消传播、终止标记和已产生用量，再注入 429、5xx 与断流验证受限回退。

自建 AI API 网关怎样估算部署与运维成本？

把计算、数据库、缓存、观测、网络和按值班工时折算的运维成本作为变量，按同一周期汇总；同时记录故障、升级、备份恢复和安全维护工时，不把软件许可证免费等同于总成本为零。

GPT 中转站搭建和 API 中转站搭建是同一件事吗？

是同一件事的两种叫法。中文语境里「GPT 中转站」「AI 中转站」「API 中转站」通常指同一类东西：一个 OpenAI 兼容的网关，替你把请求转发到上游模型。本文讲的控制面与数据面划分、反向代理与流式转发、计量与限流熔断，对这几种叫法适用同一套做法。真正需要区分的不是叫法，而是你要接的上游协议——Anthropic Messages 与 OpenAI Chat Completions 在工具调用结构、system 位置和流式事件上都不同，这会直接决定协议适配层要写多少东西。

想最快搭一个 API 中转站，用什么源码？

不打算自己写网关时，可以直接部署开源源码：需要用户、额度和计费后台的多模型中转站，可以先评估 New API，它提供官方 Docker 镜像和 Compose 配置。部署后仍要按本文清单验收鉴权、流式转发、计量和限流熔断。分步操作见 New API Docker 部署教程。