十几人团队自建 API 网关:统一入口、记账与故障切换

给十几人的小团队搭一套模型 API 网关:用 Nginx 做统一入口和按模型路由,中转服务负责记账、限流与故障切换,并处理流式响应、重试和密钥安全。读完可拿走配置骨架、上线清单与排错方法,重点是边界清楚,而不是追求功能齐全。

文章目录

原文:自建 API 网关实战:十几个人共用一套模型,Nginx 与中转服务怎么配

模型 API 网关不是简单转发器。对十几人的小团队,它把多个模型通道收拢成一个入口,让成员只记一个地址,同时回答“谁用了、用了多少”和“主通道挂了怎么办”。团队开始共用模型后,入口、权限、用量和故障边界必须明确,否则每次切换和排查都要临时协调。

这套方案给出可执行路径:Nginx 负责统一入口、按模型名路由和连接参数,中转服务负责鉴权、记账、限流与备用通道。配置之后,再把限流错误、重试边界、流式响应和密钥脱敏纳入上线检查。核心判断是:先做责任边界清晰的最小版本,再按真实使用情况扩展。

1、先把职责定下来

1、先把职责定下来(AI 生成示意图)

1、先把职责定下来 · AI 生成示意图

网关先解决三件事,边界如下表。上游密钥只留在网关侧,客户端不应拿到模型供应商密钥。统一入口便于记账和限流,故障切换也才有明确落点。

问题 网关动作 客户端看到
入口分散 所有请求进入同一地址 成员只记一个地址
用量难追 按成员与模型记录用量 能核对谁用了多少
主通道故障 主备端点自动切换 客户端不必修改地址
密钥扩散 密钥只保存在网关侧 客户端不接触上游密钥

2、最小架构与 Nginx 路由

2、最小架构与 Nginx 路由(AI 生成示意图)

2、最小架构与 Nginx 路由 · AI 生成示意图

最小架构是 Nginx 加中转服务:Nginx 提供统一入口并按模型别名选择上游;中转服务连接模型通道,同时完成鉴权、记账、限流和故障切换。客户端通过约定请求头提交路由别名,中转服务继续校验模型白名单。

map $http_x_model_route $model_upstream {
    default        primary_pool;
    team-secondary secondary_pool;
}

upstream primary_pool {
    server 127.0.0.1:8001;
    server 127.0.0.1:8002 backup;
}

upstream secondary_pool {
    server 127.0.0.1:8002;
    server 127.0.0.1:8001 backup;
}

server {
    listen 8080;
    server_name gateway.internal;

    client_max_body_size 10m;
    proxy_read_timeout 1h;
    proxy_send_timeout 1h;

    location / {
        proxy_pass http://$model_upstream;
        proxy_http_version 1.1;
        proxy_set_header Connection '';
        proxy_set_header Host $host;
        proxy_set_header X-Request-ID $request_id;

        proxy_next_upstream error timeout;
        proxy_buffering off;
        proxy_request_buffering off;
    }
}

下面是可调整的 Nginx 示例,端口和别名按部署替换,接口限制以原文为准。请求体上限由 client_max_body_size 控制,长连接由读写超时控制;关闭代理缓冲,让流式响应及时下发。backup 只处理连接级切换,模型通道的 429 等状态交给中转服务判断。

export GATEWAY_BIND_ADDR='127.0.0.1:8080'
export UPSTREAM_PRIMARY_URL='http://127.0.0.1:8001'
export UPSTREAM_SECONDARY_URL='http://127.0.0.1:8002'
export UPSTREAM_API_KEY_FILE='/run/secrets/model_api_key'
export ALLOWED_MODELS='team-primary,team-secondary'
export USER_QUOTA_FILE='/etc/model-gateway/quotas.conf'

环境变量由中转服务读取,密钥从受限 secret 文件取得,不写入配置或镜像。额度、白名单和重试策略也放在网关侧,便于统一变更。

3、记账、限流与重试

记账按“用户 + 模型”记录请求量和上游返回的用量信息。限流按成员设上限,模型按白名单放行。超限不要等成超时:额度用尽返回 HTTP 429 和 QUOTA_EXCEEDED,模型不在白名单则返回明确的拒绝错误。

重试要区分幂等与非幂等请求。只有能安全重放的请求才允许有限重试,并尊重上游 Retry-After;可能重复扣费的请求不自动重试。每个请求带唯一 ID,并记录尝试次数。

4、三个最容易出事的地方

429 被网关放大

上游拒绝后,若网关、客户端和中转服务都重试,一次拥塞会变成多次请求。只让一层负责重试,设置上限,不对 429 无条件切备用。

客户端超时,后台仍在跑

客户端断开不代表上游停止。中转服务应传递取消信号,给任务设置截止时间;无法立即取消的也要标记并回收,避免遗留脱离请求生命周期的任务。

密钥进日志

关闭不必要的原始日志,对 Authorization、Cookie 和密钥字段脱敏,用请求 ID 排查;发现泄漏就轮换并清理历史日志。

5、上线前自检与每周巡检

  • 客户端只指向网关,主备通道可达;
  • 长请求与流式响应正常,代理缓冲已关闭;
  • 成员额度、模型白名单和错误码符合预期;
  • 重试仅用于可安全重放的请求;
  • 日志不含密钥,也不输出敏感请求头。

上线后每周检查用量异常、失败分布、备用通道健康、密钥轮换与配置变更。每次故障沿用请求 ID 复盘,再逐步调整路由与限额。

写在最后

小团队不必把网关做成复杂平台,Nginx 加中转服务就能先解决入口、记账、限流和切换。
先把密钥、路由、流式参数与失败语义定下来,再根据真实记录补功能。
上线后用请求 ID 和每周巡检把问题闭环,而不是继续堆功能。
我的判断是:能说清每次请求去了哪里、记了多少、失败后怎么办,比功能数量更重要。

相关阅读

想把这套流程装到自己服务器上?阿凡达提供一次性的私有化部署与出海模型接入服务,说明与报价见站内服务页:查看技术服务。

文中链接

整理自本文的外部链接,请以来源页面说明为准。

十几人团队自建 API 网关:统一入口、记账与故障切换 · 阿凡达博客