API中转站部署教程:从零搭建请求转发服务

文章导读
搭建 API 中转站,真正需要解决的问题是让转发这一层可以被解释、被排查,而不是把请求转发出去就完事:谁在调用、被转到哪个上游、失败时返回什么。先判断自己的场景属于哪一种:统一收口多个上游的密钥和域名、在内部服务前加一层鉴权与限流,还是只做跨域与协议适配。场景不同,转发层要不要鉴权、要不要改写请求体、验证时看哪些信号都不一样。
📋 目录
  1. 壹 先确认当前场景和目标
  2. 贰 按这个顺序处理
  3. 叁 改完后怎么验证
  4. 肆 容易忽略的边界
A A

搭建 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。

如果只是内部几个服务互通,转发层做健康检查和日志就够;如果要对外暴露给第三方调用,鉴权、限流、密钥脱敏就必须一起考虑,否则后续补起来代价更大。

按这个顺序处理

建议按「定映射 → 起最小转发 → 加鉴权 → 处理流式与超时 → 补日志」的顺序推进,每步都能独立验证。

API中转站部署教程:从零搭建请求转发服务

第一步:把路径映射写成一张可核对的表

先明确客户端路径和上游路径的对应关系,再写配置。例如:

  • 客户端 /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 片段只示意请求与响应流向,生产使用需要自行补鉴权、限流和日志脱敏:

API中转站部署教程:从零搭建请求转发服务
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 与请求体中的敏感字段。

改完后怎么验证

验证时建议用命令行逐项对照,不要只看“页面能打开”。

  1. 看状态码与响应头:curl -i https://relay.example.com/relay/v1/chat -H 'Authorization: Bearer 测试令牌' ...,预期返回上游的原始状态码和 content-type,而不是一律 200 或一律 502。
  2. 看鉴权是否前置:不带令牌再请求一次,预期得到 401/403,同时上游侧日志里不应出现这次请求。
  3. 看流式是否逐块到达:对流式接口用 curl -N 观察,预期内容持续输出;如果一直等到结束才一次性吐出,说明某层缓冲没有关闭。
  4. 看错误是否透传:故意请求一个不存在的路径或非法参数,预期上游的 4xx 原样返回。若统一变成 502,说明转发层把上游响应吞掉了。
  5. 看限额与超时:超过 client_max_body_size 的请求预期返回 413;上游不可达时预期返回 504 或 502,且转发层日志里有对应的 upstream 记录。
  6. 看请求可追踪:同一请求在客户端、转发层、上游日志中用同一个 X-Request-Id 串起来。

预期信号是:路径映射无误(不会出现双前缀)、状态码与上游一致、流式逐块输出、鉴权失败不产生上游调用、限额与超时返回明确错误码。任一项不符,先回到配置层查这一项,不要用重试掩盖。

容易忽略的边界

  • 流式与缓冲:除了 proxy_buffering off,还要确认是否经过 CDN 或其他中间层,这些层也可能缓存或缓冲,需要单独确认。
  • Header 处理:Host、Connection、Content-Length、Accept-Encoding 在上游校验较严时容易出问题;重复压缩可能导致客户端解析失败。
  • 重试与幂等:读请求超时后自动重试通常可接受,写请求(例如创建任务)不要盲目重试,超时并不代表上游没执行。
  • 密钥边界:把上游密钥集中到转发层,等于把一个高价值凭据集中放到了这里,需要控制配置文件权限、日志脱敏,也不要把密钥放进 URL 查询参数。
  • 不适用条件:若上游要求双向 TLS 且客户端证书无法在转发层复用、或合规上不允许密钥落到第三方机器、或需要客户端与上游端到端加密,这种简单中转就不适用,应改为客户端直连,由调用方各自持有凭据。
  • 回退建议:流式、长连接或大文件场景短时间调不通时,先用路径前缀把中转限定在少数接口上,保留直连路径作为回退,避免一次切换把所有调用都压到未验证的转发层上。