AI网关如何接入？MAI Gateway部署实操教程

这篇和之前写过的部署教程不重复。之前的部署教程是告诉你"怎么装"------具体的docker compose命令、安装包步骤、K8s YAML。这篇反过来，先帮你做一个决策：三种部署方式（Docker Compose、安装包、Kubernetes），到底选哪个。

很多朋友上来就问"Docker怎么装"或者"K8s怎么部署"，但实际上选哪个部署方式，取决于你的场景。选对了，后面运维轻松。选错了，要么功能受限要么运维过度。

三种部署方式速览

先快速过一下每种方式是什么样的。

方式一：Docker Compose

最简单、最常见的方式。拉三个镜像（server、worker、web），一个docker-compose.yml文件，一条命令起来。

复制代码

docker compose up -d

单节点或者小规模集群，用Docker Compose管理容器的启停和依赖。配置全在.env里。

方式二：安装包（裸机/虚拟机）

官方提供Linux安装包（.tar.gz或者.rpm），解压后执行install.sh，按提示配置端口、数据库地址、管理员账号。不依赖Docker，直接跑在宿主机进程里。

复制代码

tar -xzf maig-gateway-v1.3.0.tar.gz
cd maig-gateway && ./install.sh

适合不想用Docker的场景（安全合规要求、或者对容器化有顾虑的传统企业）。

方式三：Kubernetes（Helm Chart）

官方提供Helm Chart，一条helm install命令部署到K8s集群。自动管理Pod、Service、Deployment、Ingress。支持弹性伸缩、滚动更新、自愈。

复制代码

helm install maig maig/maig --namespace maig -f values.yaml

适合已经有K8s集群的团队、需要高可用+弹性伸缩的生产环境。

一张表看清楚怎么选

三种方式在关键维度上的对比：

维度	Docker Compose	安装包	Kubernetes
上手难度	最简单，10分钟起	简单，20分钟起	复杂，需要K8s基础
生产可用	小规模可以（单机+备份）	大规模可以，配合systemd	生产首选，全量特性
高可用	需要自己搭多节点+Nginx	需要自己搭多节点+Nginx	内置Service自动负载均衡
弹性伸缩	手动改compose scale	加机器+起进程	HPA自动扩缩容
滚动升级	手动，需要编排	需要手动停启进程	Helm内置，零停机
离线支持	离线load镜像就行	直接支持，不依赖Docker	麻烦，镜像仓库也要离线
资源隔离	容器级，天然隔离	进程级，需要自己管控	容器级+命名空间，隔离最好
依赖	Docker 20.10+、Compose 2.0+	OpenJDK 17+	K8s 1.20+、Helm 3+
适合场景	测试、POC、小规模生产	私有化部署、信创环境、不喜欢Docker的团队	大规模生产、需要弹性、已有K8s集群

决策树：一步步选

如果看完表格还是纠结，按这个决策树一步步选。

问题一：你的环境能不能用Docker？

如果不能用Docker（安全合规要求禁用、或者传统企业对容器化有顾虑）→ 选安装包。

如果能用Docker，继续往下。

问题二：有没有K8s集群？

已经有成熟的K8s集群，团队有K8s运维经验 → 选Kubernetes。高可用、弹性伸缩、零停机滚动升级全是内置的，最省心。

没有K8s集群，或者团队没有K8s运维经验 → 继续往下。

问题三：部署的核心目的是什么？

测试环境/POC验证 → 选Docker Compose。最快，起完就跑。

小规模生产（日均10万次以内、不需要高可用）→ 选Docker Compose，单机跑着，定期备份数据库就行。

大规模生产（需要高可用、并发高、未来要扩容）→ 有两个选择：要么现在就上K8s，要么先用Docker Compose跑着，后面需要了再迁移。取决于你现在的运维能力和未来的增长预期。

三种方式的关键配置

选好方式了，每种方式的关键配置项汇总一下。不是完整的配置文件，是你最需要关注的那些参数。

Docker Compose关键配置

.env配置（最重要的文件）：

复制代码

# 数据库（MySQL示例）
DB_HOST=数据库IP
DB_PORT=3306
DB_USER=maig
DB_PASSWORD=你的密码
DB_NAME=maig

# 数据库（达梦示例）
DB_TYPE=dm
DB_HOST=达梦IP
DB_PORT=5236
DB_USER=maig
DB_PASSWORD=你的密码
DB_NAME=maig_dameng
DM_JDBC_DRIVER_PATH=/opt/maig/DmJdbcDriver18.jar

# Redis（可选，集群版必需）
REDIS_HOST=Redis地址
REDIS_PORT=6379
REDIS_PASSWORD=你的密码

# 服务端口
SERVER_PORT=8080   # 管理界面
API_PORT=8000       # API转发

# 离线模式（私有化部署设成true）
OFFLINE_MODE=false

# GPU监控（GPU服务器上如果不需要可以关）
ENABLE_GPU_MONITOR=false

docker-compose.yml里可以调整的：

复制代码

# 调整内存限制（默认每个服务512M-1G）
server:
  image: maig/server:latest
  mem_limit: 2g      # API Server建议至少2G
  ports:
    - "8080:8080"
    - "8000:8000"

worker:
  image: maig/worker:latest
  mem_limit: 1g      # Worker可以小一点

如果是集群版，改成deploy.replicas或者同时启动多个compose实例，前面放Nginx做负载均衡。

安装包方式关键配置

安装包方式用的是systemd管理服务，配置在/etc/maig/目录下。

复制代码

# 主要配置文件位置
/etc/maig/application.yml    # 主配置
/etc/maig/env.conf           # 环境变量（数据库、Redis等）
/etc/maig/jvm.conf           # JVM参数（内存、GC）
/etc/systemd/system/maig.service  # systemd服务文件

JVM内存调整（很重要）：

MAI Gateway是Java写的。默认JVM堆内存可能不够，生产环境建议：

复制代码

# /etc/maig/jvm.conf
JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

API Server节点建议Xmx至少2g，高并发可以给到4g-8g。Worker节点1g-2g够了。

多实例部署：

安装包方式做多实例，每台服务器跑一个实例。确保每台的.env里NODE_ID不一样，其他配置一致。

复制代码

# 节点1
NODE_ID=server-node-1
SERVER_PORT=8080
API_PORT=8000

# 节点2
NODE_ID=server-node-2
SERVER_PORT=8080
API_PORT=8000

然后Nginx前面做负载均衡：

复制代码

upstream maig {
    server node1:8000;
    server node2:8000;
}
proxy_pass http://maig;

Kubernetes关键配置

Helm Chart的values.yaml里主要关注这几块（下面是通用示例，实际配置项以厂商提供的Helm Chart为准）：

复制代码

# API Server配置
server:
  replicas: 3                    # 副本数，高可用至少3
  image: maig/server:latest
  env:
    DB_HOST: rds地址
    DB_PORT: 3306
    DB_USER: maig
    DB_PASSWORD: "密码"
    DB_NAME: maig
    REDIS_HOST: redis地址
    REDIS_PORT: 6379
  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "8"
      memory: "8Gi"
  autoscaling:
    enabled: true                 # 开HPA自动扩缩
    minReplicas: 3
    maxReplicas: 10
    targetCPUUtilizationPercentage: 70

# Worker配置
worker:
  replicas: 2                    # Worker可以少一点
  resources:
    requests:
      cpu: "1"
      memory: "2Gi"
    limits:
      cpu: "4"
      memory: "4Gi"

# Ingress配置（流量入口）
ingress:
  enabled: true
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"  # 流式输出需要
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"    # 大请求体
  hosts:
    - host: api.yourdomain.com
      paths:
        - path: /
          pathType: Prefix

K8s的特殊优势：

autoscaling开启之后，CPU利用率高了自动加Pod，低了自动缩。用量波动大的场景（比如月初月末用量暴增）特别合适。

滚动更新：helm upgrade的时候，K8s自动做滚动更新，先起新Pod再关旧Pod，全程零停机。

三种方式的迁移方案

如果选错了部署方式，能换吗？能。但不是直接切，需要规划。

**Docker Compose → K8s：**最简单。数据库导出、Redis数据导出，helm install起来，导入数据。整个过程半小时。MAI Gateway的数据库结构在不同部署方式下是一样的。

**安装包 → Docker Compose/K8s：**也是导出数据→新部署→导入。注意安装包方式的配置（JVM参数、内存限制）要在Docker或K8s里重新对应上。

**Docker Compose → 安装包：**导出数据→卸载Docker容器→安装安装包→导入数据。数据库还是同一个，不用动。

所有迁移的关键都是数据库和Redis要保留。MAI Gateway的所有状态和数据都在数据库里，容器/进程本身是无状态的。数据保住了，换什么部署方式都好说。

最后说几句

选部署方式的核心原则：用最能满足当前需求的，不要为了"未来可能"提前搞复杂。

测试环境选Docker Compose，别上K8s杀鸡用牛刀。生产环境如果只有一台服务器能跑，也别硬上集群，先单机跑着定期备份就行。

未来增长了，再迁移。MAI Gateway的数据在数据库里，迁移不难。

有问题欢迎评论区交流。欢迎联系我们咨询详情！