企业官网建设流程全解析

摘要

多模型接入的难点不只是统一 API，还包括模型路由、预算、限流、熔断、审计、Guardrails、MCP 管理和供应商切换。LiteLLM 解决了统一调用与路由问题，而 Portkey AI Gateway 更强调将生产治理能力集中在一个可扩展的 AI Gateway 中。

Portkey Gateway 是一个开源的 TypeScript/JavaScript AI Gateway，支持通过统一接口路由多个大模型，并可以部署到 Node.js、Docker、Cloudflare Workers 等环境。项目提供插件机制，用于在请求生命周期中执行 Guardrails、Checks 和自定义 Hook；官方在 2026 年发布说明中还介绍了生产网关开源、熔断器、使用策略、模型目录、MCP Registry 和指标等能力。

本文完成一次本地 Gateway 实战，重点介绍：

• Portkey Gateway 与 LiteLLM 的定位区别；
• 使用npx启动开源 Gateway；
• 通过配置路由多个模型；
• 使用策略、重试和熔断保护上游；
• 通过插件实现内容检查；
• 设计 MCP Registry 和工具治理；
• 部署到 Docker 或 Cloudflare 时的安全边界；
• 如何评估 Portkey 是否适合企业内部模型平台。

项目资料核对时间：2026 年 9 月 26 日。

项目地址：

• GitHub：https://github.com/Portkey-AI/gateway
• Gateway Wiki：https://github.com/Portkey-AI/gateway/wiki
• 插件说明：https://github.com/Portkey-AI/gateway/blob/main/plugins/README.md
• 官方博客：https://portkey.ai/blog/gateway-2-0/
• MCP Gateway：https://portkey.ai/blog/introducing-the-mcp-gateway/

一、背景与问题

1. 统一 API 只是第一步

一个最小模型网关可以做：

统一入口 ↓ 根据模型名转发 ↓ 返回统一响应

真正生产化后还需要：

• 供应商故障切换；
• P99 延迟熔断；
• Token 和费用限制；
• 请求和响应审计；
• 输入输出安全检查；
• Prompt 和模型版本；
• MCP 工具注册；
• 不同团队的权限和配额。

2. LiteLLM 和 Portkey 的差异

两者都可以作为开源模型网关，最终选型应以团队语言栈、部署环境、治理需求和运维能力为准。

3. Gateway 的信任边界

Gateway 可能接触：

• 上游 Provider Key；
• 用户 Prompt；
• 模型响应；
• 组织和项目元数据；
• MCP Server 配置；
• 预算和成本信息。

因此管理接口、业务请求接口、插件执行和出站网络都需要分层控制。

二、核心概念

1. Gateway

Portkey Gateway 接收兼容模型 API 的请求，执行路由、策略、插件和 Provider 调用，再返回统一响应。

应用 ↓ Portkey Gateway ├─ Auth ├─ Config ├─ Router ├─ Policies ├─ Plugins ├─ Circuit Breaker └─ Provider Adapter

2. Provider 与 Model

客户端请求一个逻辑模型，Gateway 根据配置选择真实 Provider：

customer-service → qwen-plus → gpt-4.1-mini → internal-model

3. Hook 与 Plugin

官方插件文档将插件描述为在请求生命周期的关键阶段执行自定义逻辑，当前主要用于 Guardrails。citeturn0search3

典型阶段：

请求进入 ↓ Before Request Hook ↓ Provider 调用 ↓ After Response Hook ↓ 请求返回

4. Circuit Breaker

Portkey 官方介绍的生产 Gateway 能力包含可按 P99 延迟或错误率触发的 Circuit Breaker，并可在故障时切换到缓存、备用 Provider 或返回错误。citeturn0search7

5. Usage Policy

Usage Policy 可以限制：

• 请求次数；
• Token 数；
• 成本；
• 模型范围；
• 团队或应用权限。

策略要在调用 Provider 前执行，避免已经产生费用后才发现超额。

6. MCP Registry

MCP Registry 用于管理 MCP Server、版本和端点。模型 Gateway 和 MCP Gateway 的责任仍然不同：

模型请求 → Model Provider 工具请求 → MCP Server 权限策略 → Gateway / 业务服务

三、工作原理

1. 请求处理流程

接收 OpenAI 风格请求 ↓ 认证和请求元数据解析 ↓ 加载模型和路由配置 ↓ 执行输入 Guardrail ↓ 检查预算、限流和策略 ↓ 调用 Provider ↓ 执行输出 Guardrail ↓ 记录指标和成本 ↓ 返回响应

2. Provider 失败处理

Provider A 失败 ↓ 判断错误是否可恢复 ↓ Circuit Breaker 记录失败 ↓ 选择 Provider B ↓ 返回结果或明确错误

不要对内容安全拒绝、认证错误和参数错误进行无条件切换。

3. 插件执行边界

插件可以检查输入、修改请求或拒绝请求，但插件本身也需要：

• 版本；
• 权限；
• 超时；
• 错误隔离；
• 测试；
• 日志脱敏。

不要在插件中执行任意网络请求或读取宿主机敏感文件。

四、实战示例

1. 检查 Node.js

node--version npm--version

项目仓库的开发说明显示，Gateway 使用 TypeScript/JavaScript，并支持 Node.js、Docker 和 Cloudflare Workers 等部署方式。citeturn0search4

2. 使用 npx 启动

npx @portkey-ai/gateway

官方仓库说明提供了基于npx的本地开源版本启动方式，默认本地地址为http://localhost:8787。citeturn0search8

启动后先访问健康检查或根路径，并确认进程只绑定到本机开发端口。

3. 从源码运行

gitclone https://github.com/Portkey-AI/gateway.gitcdgatewaynpminstallnpmrun dev:node

仓库开发说明还提供了npm run build、Gateway 测试和插件测试命令。citeturn0search4

4. 配置统一模型入口

配置文件结构随版本变化，下面用逻辑结构表达：

providers:openai:api_key:${OPENAI_API_KEY}qwen:base_url:${QWEN_BASE_URL}api_key:${DASHSCOPE_API_KEY}models:customer-service:provider:qwenmodel:qwen-plusfast-summary:provider:openaimodel:gpt-4.1-mini

生产环境不要允许客户端传入任意 Provider URL。模型、端点和凭据应来自受控配置。

5. 使用 OpenAI SDK 调用

fromopenaiimportOpenAI client=OpenAI(api_key="gateway-key",base_url="http://localhost:8787/v1",)response=client.chat.completions.create(model="customer-service",messages=[{"role":"user","content":"查询售后政策"}],)print(response.choices[0].message.content)

Java、Python、Node 和其他支持 OpenAI-compatible API 的客户端都可以复用相同的业务接入方式。

6. 加入路由和备用模型

routes:customer-service:primary:provider:qwenmodel:qwen-plusfallback:-provider:openaimodel:gpt-4.1-minipolicy:max_retries:1timeout_ms:30000circuit_breaker:error_rate:50p99_latency_ms:10000

配置字段应以当前版本文档为准。关键是将模型路由、备用策略和熔断参数版本化。

7. 编写 Guardrail Plugin

插件可以在请求进入 Provider 前检查敏感信息：

exportdefault{name:"sensitive-input-check",hooks:{beforeRequest:async(context:{body:unknown;metadata:Record<string,unknown>;})=>{consttext=JSON.stringify(context.body);if(text.includes("production-password")){return{blocked:true,reason:"sensitive input detected",};}return{blocked:false};},},};

生产插件还需要：

• 单元测试；
• 超时；
• 失败默认策略；
• 脱敏日志；
• 版本和回滚；
• 明确哪些请求可以被拦截。

8. 配置策略

公开数据 → 普通云模型 内部数据 → 企业批准的 Provider 机密数据 → 内部模型或私有网关 超预算请求 → 拒绝或转低成本模型

策略必须结合业务服务的用户身份和租户信息，不能只依据客户端传来的 metadata。

9. Docker 部署

FROM node:22-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --omit=dev COPY . . RUN npm run build USER node EXPOSE 8787 CMD ["npm", "run", "start"]

生产部署还需要：

• 固定依赖锁文件；
• 非 root 用户；
• 只读文件系统；
• Secret 注入；
• HTTPS；
• 健康检查；
• 资源限制；
• 出站网络白名单。

10. 管理 MCP Server

MCP Registry 的治理可以包含：

Server 名称 版本 端点 认证方式 工具列表 权限 Scope 状态 维护人

安装或启用第三方 MCP Server 前，应检查其源码、网络访问、凭据读取和数据上传行为。

五、常见问题与实践建议

1. 为什么 Gateway 启动了但模型调用失败

排查：

• Provider Key 是否注入；
• Base URL 是否正确；
• 模型名是否正确；
• Gateway 是否支持该 Provider；
• 请求路径是否包含/v1；
• 是否被 CORS、代理或防火墙拦截；
• 模型权限和配额是否可用。

2. 为什么 Fallback 没有生效

检查：

• 当前错误是否可切换；
• 备用模型是否在白名单；
• 是否已经开始流式输出；
• 备用 Provider Key 是否存在；
• Circuit Breaker 是否打开；
• 路由配置是否被缓存。

3. 插件失败应该阻塞请求吗

安全检查插件通常 fail closed；观测和统计插件可以 fail open。每个插件都要明确失败策略。

4. 如何保护 API Key

• 上游 Key 只放 Gateway；
• 应用使用短期或受限 Gateway Key；
• 管理 Key 与业务 Key 分离；
• 定期轮换；
• 不写入日志；
• 不让模型获取 Key；
• 限制 Gateway 出站网络。

5. Cloudflare Workers 和 Node.js 如何选择

边缘部署适合低延迟、无状态和靠近用户的请求；Node.js 或 Docker 更适合复杂插件、长连接、内网模型和完整运维控制。

6. Portkey 和 LiteLLM 是否同时使用

一般不建议无目的叠加。可以根据职责选择一层主 Gateway，另一层作为实验或特定 Provider 适配；如果两层都配置重试和 Fallback，容易造成请求放大。

六、进阶思考

1. Gateway 与业务 AI 服务的边界

Gateway 负责：

• Provider 适配；
• 模型路由；
• 限流；
• 熔断；
• Guardrails；
• 成本和指标。

业务服务负责：

• 用户权限；
• 会话和消息；
• RAG；
• Agent 任务；
• 工具审批；
• 业务数据。

2. Portkey 与 Coder、OpenHands 的组合

可以组成一个 Agent 研发栈：

Coder：创建隔离 Workspace ↓ OpenHands：执行代码任务 ↓ Portkey：统一模型路由、预算和策略 ↓ 多个模型 Provider

每一层都要有自己的权限边界，不能因为 Gateway 统一了模型调用，就让 Agent 获得更多文件或生产系统权限。

3. 模型目录和价格治理

模型目录可以保存：

• Provider；
• 模型能力；
• 上下文长度；
• 输入输出价格；
• 数据级别；
• 允许团队；
• 健康状态；
• 弃用时间。

业务服务只使用逻辑模型名，平台团队维护真实模型信息。

4. Gateway 的高可用

API Gateway / WAF ↓ Portkey-1 ─┐ Portkey-2 ─┼─> Provider Portkey-3 ─┘ ↓ Metrics / Logs / Config

配置、策略和插件需要可复现、可回滚；熔断状态可以是实例级，也可以由共享状态服务统一管理。

5. MCP 安全

MCP Server 需要：

• OAuth 或短期凭据；
• 工具级 Scope；
• Server 白名单；
• 版本和健康状态；
• 调用审计；
• 结果大小限制；
• 数据出口控制。

不要让模型自行注册未知 MCP Server。

结论

Portkey AI Gateway 的价值在于把多模型调用从“转发请求”提升为“可治理的生产平台”。它的开源 Gateway、插件机制、熔断、策略、模型目录和 MCP 管理方向，适合希望统一模型访问和安全控制的团队。

第一次实践可以从本地npx启动开始，使用 OpenAI-compatible 客户端调用一个逻辑模型；团队落地时，再增加 Docker、Provider 路由、预算、Guardrails、熔断和 MCP Registry。

最终是否选择 Portkey 还是 LiteLLM，应根据团队语言栈、部署形态、插件模型、可观测需求、运维能力和许可证要求进行验证，而不是只比较模型数量。

参考资料

• Portkey AI Gateway GitHub
• Portkey Gateway Wiki
• Portkey Gateway Plugins
• The Gateway Grew Up
• MCP Gateway