搭建 API 中转站,真正需要解决的问题是让转发这一层可以被解释、被排查,而不是把请求转发出去就完事:谁在调用、被转到哪个上游、失败时返回什么。先判断自己的场景属于哪一种:统一收口多个上游的密钥和域名、在内部服务前加一层鉴权与限流,还是只做跨域与协议适配。场景不同,转发层要不要鉴权、要不要改写请求体、验证时看哪些信号都不一样。
API 中转站的最小可用形态是「一个路径映射 + 一个上游 + 一层鉴权」,先用单条路由跑通,再考虑多上游分发。判断能否落地看三点:上游鉴权方式是否可在转发层注入、响应是否需要流式返回、请求体大小是否在转发层限额内。验证不看配置写没写对,而是看状态码透传、流式是否逐块到达、鉴权失败是否不落到上游,以及超时是否返回 504 而不是 502。
先确认当前场景和目标
动手之前先确认几个前提,它们直接决定架构选择:
- 密钥归属:上游密钥需要只存在转发层、由客户端持另一个令牌,还是原样透传客户端自己的密钥。前者要把转发层当作敏感组件对待,后者转发层基本无状态。
- 上游鉴权形式:是固定 Header 里的 Bearer、自定义 Header(例如 api-key),还是签名参数。自定义 Header 名必须在上游文档里核对,不要靠猜。
- 响应形态:普通 JSON 一次性返回,还是 SSE、chunked 之类的长连接流式返回。流式响应决定了必须关闭转发层缓冲。
- 路径前缀:上游 base URL 是否已带
/v1之类前缀,转发路径会不会拼成/v1/v1/...。 - 请求体与超时:单请求最大体积、上游典型耗时,用于设
client_max_body_size和proxy_read_timeout。
如果只是内部几个服务互通,转发层做健康检查和日志就够;如果要对外暴露给第三方调用,鉴权、限流、密钥脱敏就必须一起考虑,否则后续补起来代价更大。
按这个顺序处理
建议按「定映射 → 起最小转发 → 加鉴权 → 处理流式与超时 → 补日志」的顺序推进,每步都能独立验证。

第一步:把路径映射写成一张可核对的表
先明确客户端路径和上游路径的对应关系,再写配置。例如:
- 客户端
/relay/v1/chat→ 上游https://upstream.example.com/v1/chat - 客户端
/relay/v1/embed→ 上游https://upstream.example.com/v1/embed
映射表确认后再落到配置上,能避免大半前缀重复的问题。
第二步:用反向代理跑通单条路由
下面是 nginx 的示意片段,替换域名、路径和密钥注入方式后放在 conf.d 下即可。密钥不要直接提交到代码仓库,建议用环境变量或受控的 include 文件注入。
server {
listen 443 ssl;
server_name relay.example.com; # 替换为自己的域名与证书
client_max_body_size 8m; # 按上游允许的请求体上限调整
location /relay/v1/ {
proxy_pass https://upstream.example.com/v1/; # 结尾斜杠决定是否替换前缀
proxy_http_version 1.1;
proxy_set_header Host upstream.example.com;
proxy_set_header Authorization "Bearer 替换为实际密钥";
proxy_set_header X-Request-Id $request_id;
proxy_set_header Connection "";
proxy_buffering off; # 流式响应不要缓冲
proxy_connect_timeout 5s;
proxy_read_timeout 120s;
}
}
如果更希望在转发层做逻辑(改写请求体、按租户路由、记录用量),可以先用一个最小服务骨架跑通链路,再逐项加功能。下面的 Node 片段只示意请求与响应流向,生产使用需要自行补鉴权、限流和日志脱敏:

import http from 'node:http';
const UPSTREAM = 'https://upstream.example.com';
const KEY = process.env.UPSTREAM_KEY;
http.createServer(async (req, res) => {
const target = new URL(req.url, UPSTREAM); // 保留路径与查询串
const headers = { ...req.headers, host: undefined, authorization: Bearer ${KEY} };
const upstreamRes = await fetch(target, {
method: req.method,
headers,
body: ['GET', 'HEAD'].includes(req.method) ? undefined : req,
duplex: 'half',
});
res.writeHead(upstreamRes.status, Object.fromEntries(upstreamRes.headers));
for await (const chunk of upstreamRes.body) res.write(chunk);
res.end();
}).listen(8080);
第三步到第五步分别是:在转发层做令牌校验、仅对通过校验的请求注入上游密钥;对流式接口确认关闭各级缓冲;对每个请求生成并回传 X-Request-Id,日志里同时记录上游地址、状态码和耗时,但不要记录完整 Authorization 与请求体中的敏感字段。
改完后怎么验证
验证时建议用命令行逐项对照,不要只看“页面能打开”。
- 看状态码与响应头:
curl -i https://relay.example.com/relay/v1/chat -H 'Authorization: Bearer 测试令牌' ...,预期返回上游的原始状态码和content-type,而不是一律 200 或一律 502。 - 看鉴权是否前置:不带令牌再请求一次,预期得到 401/403,同时上游侧日志里不应出现这次请求。
- 看流式是否逐块到达:对流式接口用
curl -N观察,预期内容持续输出;如果一直等到结束才一次性吐出,说明某层缓冲没有关闭。 - 看错误是否透传:故意请求一个不存在的路径或非法参数,预期上游的 4xx 原样返回。若统一变成 502,说明转发层把上游响应吞掉了。
- 看限额与超时:超过
client_max_body_size的请求预期返回 413;上游不可达时预期返回 504 或 502,且转发层日志里有对应的 upstream 记录。 - 看请求可追踪:同一请求在客户端、转发层、上游日志中用同一个
X-Request-Id串起来。
预期信号是:路径映射无误(不会出现双前缀)、状态码与上游一致、流式逐块输出、鉴权失败不产生上游调用、限额与超时返回明确错误码。任一项不符,先回到配置层查这一项,不要用重试掩盖。
容易忽略的边界
- 流式与缓冲:除了
proxy_buffering off,还要确认是否经过 CDN 或其他中间层,这些层也可能缓存或缓冲,需要单独确认。 - Header 处理:
Host、Connection、Content-Length、Accept-Encoding在上游校验较严时容易出问题;重复压缩可能导致客户端解析失败。 - 重试与幂等:读请求超时后自动重试通常可接受,写请求(例如创建任务)不要盲目重试,超时并不代表上游没执行。
- 密钥边界:把上游密钥集中到转发层,等于把一个高价值凭据集中放到了这里,需要控制配置文件权限、日志脱敏,也不要把密钥放进 URL 查询参数。
- 不适用条件:若上游要求双向 TLS 且客户端证书无法在转发层复用、或合规上不允许密钥落到第三方机器、或需要客户端与上游端到端加密,这种简单中转就不适用,应改为客户端直连,由调用方各自持有凭据。
- 回退建议:流式、长连接或大文件场景短时间调不通时,先用路径前缀把中转限定在少数接口上,保留直连路径作为回退,避免一次切换把所有调用都压到未验证的转发层上。