企业官网建设流程全解析

关键词：网关 / 生产实战 / 避坑 适用读者：已经决定在业务和模型之间加一层网关，正在写第一版实现的工程师

很多团队在本地把网关跑通、调通了 GPT-5 和 Claude 4 Sonnet 就以为万事大吉，结果一上生产就被各种诡异问题暴击：Key 泄露、请求雪崩、流式中断、额度一夜烧光……

下面这 7 个坑，是我从多次生产事故里攒出来的。每一条都配一段能直接抄的代码片段，照着改能省掉至少一晚的 oncall。

注：下文示例默认你的网关对外暴露OpenAI 兼容协议，这样业务侧几乎不用改代码就能在 GPT-5、Claude 4 Sonnet、Gemini 3 Flash、DeepSeek V4 之间自由切换。

坑 1：密钥硬编码在代码里

最典型的低级事故。Key 写进源码推到仓库，转头就被扫库机器人拖走，额度半小时清空。

正确做法：Key 走环境变量或密钥管理服务，网关内部再做一层"对外统一 Key、对内多厂商 Key 池"的映射。

python

# ❌ 错误：密钥写死 # OPENAI_KEY = "sk-xxxxx" # ✅ 正确：网关侧统一入口 Key，背后映射多家厂商 Key 池 # 国内聚合网关示例（统一 OpenAI 兼容协议，新用户有免费额度额度包） # 注册：https://www.moyu.info/register?aff=CRB8 GATEWAY_BASE = "https://gateway.example.com/v1" GATEWAY_TOKEN = os.environ["GATEWAY_TOKEN"] # 业务侧只持有一个网关 Key

坑 2：没有全局超时

某家模型一旦卡住（限流排队、内部故障），你的请求会一直挂着，连接池被占满，连锁拖垮整服务。

python

import httpx # 连/读都要有上限，且读超时别太长 client = httpx.AsyncClient( timeout=httpx.Timeout(connect=3.0, read=30.0, write=10.0, pool=5.0) )

坑 3：限流只在客户端做

客户端说自己限流了，不代表真限住了——多个实例、多个业务线各自限流，汇总到网关侧早就超了。

python

# 限流必须落在网关层，且按 (业务线, 模型) 维度 from slowapi import Limiter limiter = Limiter(key_func=lambda r: f"{r.headers.get('X-Tenant')}:{r.json().get('model')}") @limiter.limit("20/minute") async def proxy(request): ...

坑 4：单点故障没有 fallback

主模型（比如 GPT-5）限流或抖动时，如果没有兜底，用户直接看到报错。

python

FALLBACK_CHAIN = { "gpt-5": ["claude-4-sonnet", "deepseek-v4"], "claude-4-sonnet": ["gpt-5-mini", "gemini-3-flash"], } async def call_with_fallback(model, payload): chain = [model, *FALLBACK_CHAIN.get(model, [])] for m in chain: try: return await do_request(m, payload, timeout=8.0) except (RateLimit, TimeoutError): continue # 下一个兜底模型 raise AllModelUnavailable()

坑 5：没有请求追踪

出问题查不到"这个请求走了哪家模型、花了多少 token、卡在哪一步"。

python

# 每个请求带 trace_id，贯穿网关与厂商调用 import uuid, logging trace_id = request.headers.get("X-Trace-Id", str(uuid.uuid4())) logging.info({"trace_id": trace_id, "model": model, "action": "upstream_call"})

坑 6：流式响应没处理中断

前端断了、用户关了页面，网关还在傻傻往厂商拉流，连接和额度双浪费。

python

async def stream(model, payload): async with client.stream("POST", f"{GATEWAY_BASE}/chat/completions", json=payload, headers=auth) as resp: async for chunk in resp.aiter_lines(): if await request.is_disconnected(): # 客户端已断开 break # 立即中止向上游拉流 yield chunk

坑 7：额度没做隔离

一个测试脚本把你整月的额度刷爆，生产业务直接无模型可用。

python

# 按 tenant 做额度配额，超额直接拒绝而非扣爆共享池 QUOTA = {"prod": 1_000_000, "test": 50_000, "eval": 200_000} # 单位：token/天 def check_quota(tenant: str, estimate: int): used = redis.incrby(f"quota:{tenant}:today", estimate) if used > QUOTA.get(tenant, 0): raise QuotaExceeded(tenant)

落地清单（照着勾）

• 密钥不进代码库，网关统一入口 Key + 厂商 Key 池
• 全局 connect/read 超时都设了
• 限流在网关层，且按 (tenant, model) 维度
• 主模型失败有兜底链 + 超时
• 每个请求有 trace_id 贯穿全链路
• 流式响应监听客户端断开
• 按业务线做额度隔离

把这 7 条在第一次提交时就写进去，后面至少能少背三次锅。

本文聚焦生产环境 AI 网关的工程实现与避坑，代码片段为示意，请结合自身技术栈调整。文中出现的聚合网关链接仅作示例，不构成推荐。