MAI Gateway 私有化部署，要同时安排模型调用路径、管理入口和运行数据。应用从哪里访问，管理员从哪里登录，哪些请求允许进入公共模型，哪些内容只能交给本地模型，这些决定应在安装前确定。

MAI Gateway 支持统一接入外部模型 API 与内部自部署模型。

一、先比较部署方式

方式	适合的情况	主要维护工作
单机 Docker	试点、开发验证、较小规模内部应用	主机、容器、存储和备份
Kubernetes	企业已有容器平台，需要多副本和统一发布	集群、资源配额、入口和滚动升级
G 系列网关	已有模型服务，需要统一管理调用	模型接入、路由、权限与费用
S 系列一体机	需要本地推理，处理高频或敏感任务	网关运维与 GPU、模型服务维护

Docker 和 Kubernetes 是运行方式，G、S 系列是产品选择，二者不属于同一分类。企业应先决定是否需要新增本地算力，再确定软件运行环境。

二、生产环境推荐架构

下面是采用多副本网关的推荐逻辑拓扑。状态服务按实际交付包部署，图中不限定具体数据库或缓存产品。

flowchart TB
    subgraph APP["企业应用区"]
        A["客服、知识库、研发工具"]
    end

    subgraph GW["企业网关区"]
        B["统一 API 入口与负载均衡"]
        C["MAI Gateway 实例 A"]
        D["MAI Gateway 实例 B"]
        E["配套状态服务与持久化存储"]
        F["监控、日志与备份"]
    end

    subgraph LOCAL["企业模型区"]
        G["本地模型与内网推理服务"]
    end

    subgraph ADMIN["管理网络"]
        H["管理员与企业身份系统"]
    end

    I["受控网络出口"]
    J["外部模型 API"]

    A --> B
    B --> C
    B --> D
    C --> E
    D --> E
    C --> F
    D --> F
    C --> G
    D --> G
    C --> I
    D --> I
    I --> J
    H --> C
    H --> D

应用只连接统一 API 入口。网关根据令牌、模型权限和路由配置选择上游，调用结果和消耗进入日志与费用记录。

私有化部署能够把网关配置、密钥与管理数据放在企业环境中。使用公共模型时，请求仍会经过企业出口发送到外部；完全离线时，业务应使用内网模型。

三、先划网络，再安装服务

把网络关系整理成访问规则，比上线以后逐个排查端口更省事。

来源	目标	推荐访问范围
业务应用	网关 API 入口	开放业务所需接口
管理员	管理入口	通过管理网络或 VPN 访问
网关实例	配套状态服务	仅允许网关及维护系统访问
网关实例	本地推理服务	开放所需模型端点
网关实例	外部模型 API	按供应商域名和出口策略放行
监控与备份系统	网关及存储	使用专用账号和最小权限

管理入口与业务入口可以使用不同域名或访问策略。模型密钥由网关保存，业务应用使用网关签发的调用令牌。

四、按顺序完成部署

第一步，准备域名、证书和持久化存储

确定管理地址与 API 地址，配置 DNS 和 HTTPS。

随后识别交付包中的持久化目录、外部依赖和备份对象。配置、账单、日志与密钥相关数据都要有明确存放位置，不能随临时容器一起丢失。

第二步，启动配套组件与网关

Docker 环境使用交付包的编排文件，Kubernetes 环境使用配套部署资源。

先检查依赖连通性，再完成初始化。生产多副本环境还要按照版本的升级说明安排数据迁移，避免多个实例同时执行初始化或迁移任务。

第三步，接入一条公共模型和一条本地模型

分别登记地址、协议、密钥与模型 ID。公共模型验证出口连接，本地模型验证内网连接。

先让两条调用独立成功，再配置路由。这样发生错误时，能快速区分上游接入问题和路由问题。

第四步，接入统一 API 入口

在网关前配置负载均衡或反向代理，业务应用通过稳定域名访问。

健康检查按交付版本提供的方式设置。扩容或替换网关实例时，业务地址保持稳定。

第五步，配置组织、项目和令牌

MAI Gateway 支持组织同步、模型权限、独立令牌、配额和费用归集。企业可以把客服、研发、运营等业务分别建立项目，再给每个应用分发令牌。

五、流式输出需要单独处理

大模型响应可能持续较长时间。普通网页接口的代理配置，未必适合流式输出。

项目	普通短请求	流式模型请求
响应方式	一次返回完整内容	持续返回数据片段
代理缓冲	通常影响不明显	可能导致内容积攒后才显示
超时判断	关注完整响应时间	同时关注连接空闲间隔
发布操作	请求结束较快	需要处理已有长连接
故障恢复	可重新发起请求	已返回内容需要业务端处理

使用 Nginx 时，可以在对应流式接口位置关闭响应缓冲，并根据业务设置读取超时。proxy_read_timeout 控制两次读取之间的等待时间。

六、高可用要覆盖整条调用路径

检查位置	可采取的措施
网关版本	健康检查、摘除实例、其他副本承接
状态服务	使用对应组件的高可用与备份方案
外部模型服务	配置备用供应商或备用模型
本地推理节点	增加可用推理端点，检查模型容量
网络出口	准备符合企业策略的备用出口
升级过程	分批发布，观察后继续，保留恢复路径

备用模型要能够完成同类任务。结构化输出、工具调用、上下文长度和业务质量，都可能随着模型更换而变化。

七、迁移应用采用小批量方式

先选一条调用量稳定、负责人明确的业务接入。

第一批只改 API 地址、令牌和模型配置，记录成功率、延迟与费用。第二批再增加预算、安全与告警规则。最后逐步扩大接入范围，并清理应用中遗留的供应商密钥。

迁移时保留旧配置和恢复方法。真正需要恢复的可能包括应用配置、网关策略、密钥和状态数据，单纯换回旧镜像未必够用。

八、上线前检查六项结果

检查项	具体动作
接入	公共模型和本地模型分别调用成功
权限	停用测试令牌后，应用访问被拒绝
预算	小额测试项目达到阈值后，执行预设动作
高可用	停止一个网关实例，观察剩余实例承接情况
流式	连续输出正常，代理没有集中缓冲
备份	在隔离环境恢复配置与必要数据

部署完成以后，把网关版本、配置变更、备份记录和告警联系人纳入现有运维流程。统一入口开始承接更多业务后，这些日常记录会直接影响排障和恢复速度。