引言

产品版本

本文档对应的产品版本为 ZStack API Router preview。

读者对象

本文档介绍 ZStack API Router 的架构、能力和典型实践，主要适用于以下读者：

企业 AI 平台架构师。
部署运维工程师。
平台管理员。
技术支持工程师。
需要评估模型网关能力的相关人员。

产品概述

ZStack API Router 是面向企业 AI 应用的统一模型访问网关。它在业务应用和上游模型服务之间提供统一入口，支持 OpenAI 兼容调用方式，并提供渠道路由、模型访问控制、令牌管理、用量计量、审计追踪、健康观测和兼容旧调用链路的能力。

核心价值

价值	说明
统一入口	业务应用通过统一地址和统一鉴权调用模型。
集中治理	管理员集中配置渠道、模型、路由、权限和配额。
成本可见	按组织、用户、令牌、模型和渠道记录用量。
故障可查	通过用量日志、审计日志、健康检查和指标定位问题。
平滑演进	支持独立部署（Standalone）和 LobsterPool 兼容入口灰度替换。

功能架构

ZStack API Router 的功能架构覆盖统一访问能力、网关治理能力、组织权限能力、运营与可观测能力、平台生命周期能力。

管理员可在统一网关层管理模型调用入口、令牌、模型可见范围、渠道、路由策略、调用计量、审计记录、系统设置、导出任务和 OpenAPI 合约。

总体架构

ZStack API Router 的总体架构由入口层、控制台、网关服务、后台任务、数据库和上游模型服务组成。

组件	说明
控制台	管理员进行渠道、模型、令牌、组织、配额和日志管理的界面。
入口代理	Nginx、Ingress 或负载均衡，负责 HTTPS、域名、灰度和路径转发。
`zr-server`	主服务，提供控制面 API、数据面 API、健康检查和指标。
`zr-worker`	后台任务组件，负责渠道健康探测和模型同步。
`zr-migrate`	数据库迁移工具，在服务启动或升级前执行。
PostgreSQL	保存配置、凭证哈希值、组织、用量、审计和配额数据。
上游模型服务	OpenAI 兼容服务、内部推理服务或其他模型供应商。
LobsterPool 兼容入口	为现有调用链路提供 `/openai/v1/*` 兼容接口。

软件架构

ZStack API Router 的软件架构由访问入口、统一入口层、ZStack API Router 服务层、上游模型服务、数据与基础设施组成。

业务应用、智能体应用和管理控制台通过 OpenAI 兼容 API 或管理 API 接入网关。服务层负责 OpenAPI 请求处理、请求转发、渠道适配、健康探测、模型同步、公共策略执行、用量记录、审计脱敏、设置和遥测。

部署模式

独立部署模式

独立部署模式适合单独部署 API 网关。zr-server 提供控制台、控制面、数据面和健康指标。管理员可通过控制台完成模型接入和策略配置，业务应用通过 /v1/* 调用模型。

生产入口模式

生产环境建议通过 Nginx、Ingress 或负载均衡对外暴露服务。入口层负责 TLS、域名、访问控制、灰度发布和路径转发。指标接口 /metrics 建议只允许监控系统访问。

LobsterPool 兼容模式

当需要替换旧 slim-gateway 或 TensorZero 兼容链路时，可将 LobsterPool 的模型调用切到 /openai/v1/*。该模式适合灰度迁移，可通过入口层逐步放量。

模型接入和渠道管理

ZStack API Router 将模型访问拆分为模型、渠道和路由策略。

资源结构

ZStack API Router 资源划分为身份与组织域、模型服务治理域、运营与审计域。

身份与组织域定义用户、组织、角色集和模型访问规则。模型服务治理域定义令牌、渠道、渠道模型和路由策略。运营与审计域记录用量日志、审计日志、预算、配额和系统设置。

概念	说明
模型	业务应用调用时填写的模型名称。
渠道	连接到上游模型服务的访问出口。
渠道模型	某个渠道已经同步并启用的模型。
路由策略（Route Policy）	决定特定模型或组织请求如何选择渠道。

这种设计让管理员可以在不修改业务代码的情况下调整上游服务、切换渠道、添加备用渠道或做灰度验证。

渠道生命周期

创建渠道。
配置上游地址和凭证。
同步模型。
启用需要开放的模型。
配置路由策略。
通过用量日志观察实际流量。
根据健康状态调整渠道。

数据面调用链路

业务请求进入 ZStack API Router 后，会经过鉴权、权限、配额、路由、安全检查、上游转发和用量记录。

典型链路如下：

业务应用
  |
API Key 鉴权
  |
模型访问权限检查
  |
配额和限流检查
  |
路由策略选择渠道
  |
上游地址安全检查
  |
请求转发到模型服务
  |
返回响应并记录用量日志

支持的主要接口

接口	说明
`/v1/chat/completions`	Chat Completions。
`/v1/responses`	Responses API。
`/v1/messages`	Anthropic Messages 兼容接口。
`/v1/completions`	Completions。
`/v1/embeddings`	Embedding。
`/v1/images/generations`	图像生成。
`/v1/rerank`	Rerank。
`/v1/models`	模型列表。
`/openai/v1/*`	LobsterPool 兼容入口。

路由治理

路由策略用于控制模型请求如何选择渠道。生产环境常见策略包括：

策略	使用场景
主备路由	主渠道异常时切换到备用渠道。
权重路由	多个同级渠道按比例分担流量。
组织隔离	不同组织使用不同模型供应商或渠道。
灰度路由	小范围切入新渠道或新模型。
成本优先	默认使用低成本渠道，高质量渠道作为备用。

Note:

渠道必须同步并启用目标模型后才会参与路由。空模型列表不会被视为支持所有模型。

安全和权限

ZStack API Router 从凭证、访问控制、上游地址安全和日志脱敏几个方面保障安全。

凭证保护

API Key 只保存哈希值。
上游模型服务凭证不得出现在文档、截图、日志或工单中。
管理员应为不同应用和环境创建不同令牌。
API Key 泄露后应立即停用对应令牌并重新创建。

访问控制

访问控制覆盖：

范围	说明
用户	控制用户可操作的管理资源。
组织	控制成本归属和模型访问范围。
令牌（Token）	控制调用方可用模型、额度和来源 IP。
模型	控制哪些组织或用户可以调用。
控制面	通过云平台访问令牌（Cloud token）或统一身份能力保护管理 API。

上游地址安全

网关会对上游地址执行安全检查，防止请求被路由到不允许的内部地址或不受信任地址。生产环境应维护明确的上游地址范围。

配额和计量

ZStack API Router 会记录每次模型调用的用户、组织、令牌、模型、渠道、状态、耗时、模型 Token 数和额度消耗。

计量维度

维度	用途
组织	部门成本归集。
用户	个人使用分析。
令牌	应用级用量跟踪。
模型	模型成本和调用趋势分析。
渠道	供应商质量、成本和稳定性分析。
状态	成功率和失败原因分析。

配额治理

管理员可按组织、用户或令牌设置额度，限制成本风险。建议生产环境为高成本模型设置单独访问范围和额度。

审计和观测

用量日志

用量日志用于查看每次模型调用的状态和用量。排障时建议先根据请求 ID（request ID）定位具体请求，再查看模型、渠道、上游状态和延迟。

审计日志

审计日志用于查看控制面操作，例如创建渠道、修改模型、调整配额、创建令牌、修改组织权限等。

健康和指标

入口	说明
`/healthz`	服务健康检查。
`/readyz`	服务就绪检查。
`/metrics`	Prometheus 指标。

重点指标包括请求成功率、首个输出 Token 延迟、活跃流数量、数据库连接池状态和异步计量队列状态。

高可用和灰度实践

生产环境建议：

使用独立 PostgreSQL，并配置定期备份。
通过 Nginx、Ingress 或负载均衡暴露服务。
至少保留一个稳定版本入口。
对新版本采用灰度策略。
控制台和数据面分开验证。
流式接口关闭代理缓冲。
按并发流数量规划文件句柄上限（open files）。

运维建议

场景	建议
新接入模型	先在测试组织验证，再开放给生产组织。
渠道异常	先停用异常渠道，再分析上游和用量日志。
成本增长	按组织、令牌、模型维度查看用量。
升级发布	先入口层灰度，再逐步扩大流量。
安全审计	定期查看审计日志和高权限令牌。

附录：运维参考

以下信息面向运维和技术支持人员，用于定位问题：

工具或进程	用途
`zr-migrate`	执行数据库迁移。
`zr-worker`	执行渠道健康探测和模型同步。
上游失败诊断文件	保存脱敏后的上游失败证据。
流式响应不完整诊断文件	保存脱敏后的流式响应不完整证据。

Note:

诊断文件只能包含脱敏和截断后的诊断信息，不得保存真实 API Key、上游凭证、密码、令牌、完整 Prompt 或完整响应正文。