最近后台有朋友私信问我MAI Gateway怎么部署。刚好上周帮另一家公司完成了一次完整的部署，从环境准备到上线跑通，花了大概两天。这篇把过程整理一下，给同样在部署的朋友做个参考。
先说明，这篇不是官方文档的抄录，是我们实际部署过程中的经验总结。有些步骤可能因为你的环境不同需要调整，具体以官方文档为准。
部署前：先准备好这几样
动手之前先盘点一下，以下东西得先有。
第一，服务器资源。
MAI Gateway有单机版和集群版两种。单机版适合测试环境或者用量不大的生产环境，最低4核8G就能跑。集群版适合高并发的生产环境，建议至少3台节点，每台8核16G起步。我们这次帮朋友部署的是单机版，5核10G，跑了两周稳定没出过问题。
操作系统推荐CentOS 7.9、Ubuntu 20.04或者22.04。
第二，数据库。
MAI Gateway需要一个关系型数据库。官方推荐MySQL 5.7+/8.0+、PostgreSQL 10+。如果有国产化需求，达梦8也支持。数据库可以跟网关部署在同一台机器上，也可以独立部署。我们建议独立部署，尤其是集群版，方便后续扩展。
这次部署用的是MySQL 8.0，独立在另一台服务器上。
第三，网络和端口。
网关默认暴露3个端口：管理界面端口（默认8080）、API转发端口（默认8000）、日志端口（默认9090）。服务器防火墙要开放这三个端口。业务方调模型的时候，走的是API转发端口。
如果有内网私有化模型要接入，要确保网关服务器能访问到私有化模型的地址。
第四，渠道的API Key和地址。
所有要接入的模型供应商，API Key、Base URL、协议类型（OpenAI兼容、阿里兼容等），提前整理好。部署完直接填，省得到时候一个个找。
部署方式：三种任选
MAI Gateway支持三种部署方式。
第一种：Docker Compose一键部署。
最简单，适合单机版。下载官方的docker-compose.yml，改几个配置项，一条命令就起来了。整个过程大概10-15分钟。测试环境或者小规模生产，推荐这种。
第二种：安装包部署。
官方提供Linux安装包，解压后执行安装脚本，按提示一步步来。比Docker稍微麻烦一点，但更灵活，可以自定义目录、端口、内存参数。适合需要定制化配置的场景。
第三种：Kubernetes部署。
官方提供Helm Chart，适合集群版。如果你们公司有K8s集群，这种方式最方便，自动管理副本、服务发现、负载均衡。适合高并发的生产环境。
我们这次帮朋友用的是Docker Compose方式，最快。
从零开始：完整的部署步骤
下面以Docker Compose方式为例，一步步来。
步骤一：下载配置文件
从官方拿到最新版的安装包，解压后里面有docker-compose.yml和.env.example。把.env.example复制一份改成.env，然后修改里面的配置。
主要改这几项：
数据库连接信息：DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME。确保数据库提前建好，账号有读写权限。
网关端口：SERVER_PORT（管理界面）、API_PORT（API转发）。如果8080和8000端口已经被占了，改成别的。
管理员初始密码：ADMIN_PASSWORD。第一次登录用这个，后面要改。
步骤二：启动服务
一行命令：
docker-compose up -d然后等几十秒，用docker ps看看三个容器是不是都起来了。正常的话应该有maig-server、maig-worker、maig-web三个容器。
如果有容器没起来，看日志排查：
docker logs maig-server最常见的问题是数据库连不上。检查一下数据库地址、端口、账号密码、权限是不是都对。
步骤三：初始化数据库
服务起来之后，第一次访问管理界面（比如http://服务器IP:8080），会跳转到初始化页面。点"初始化数据库"，网关会自动建表、插入初始数据。
这个过程大概1-2分钟。完成后会提示"初始化成功"，然后进入登录页面。
用之前在.env里配置的ADMIN_USER和ADMIN_PASSWORD登录。
步骤四：接入模型
登录进去之后，先做两件事：添加渠道、注册模型。
**添加渠道：**进入"模型管理"页面，点"添加渠道"。填渠道名称、Base URL、API Key、协议类型。协议类型选对应的兼容协议，大多数渠道是OpenAI兼容。
添加完渠道，可以点"测试连接"。能通的话会返回成功，通不了检查一下Base URL和Key有没有写错。
**注册模型：**渠道添加好之后，点"注册模型"。选刚才添加的渠道，填模型名称（要和供应商那边的模型名一致，比如qwen-turbo），然后保存。
我们这次帮朋友接了三家渠道，加起来注册了十二三个模型。这个过程比较机械，逐个填就行。
步骤五：生成令牌和配置权限
模型接好之后，给业务方生成调用令牌。
进入"令牌管理"页面，点"新建令牌"。填令牌名称（比如"客服部-张三"），选能用哪些模型，设配额（日/月/总），设IP白名单（可选）。
保存之后会生成一个API Key，复制给业务方就行。业务方调模型的时候，把网关的API转发端口和这个Key填到他们的AI助手配置里。
步骤六：对接业务并测试
让业务方用新的网关地址和Key调一次模型，确认能通。然后在管理界面看一下API请求日志，确认请求确实走到网关上了，Token消耗也正常。
这个过程是闭环的：业务方调 → 网关转发 → 日志能看到 → Token能统计。通了就没问题。
部署中遇到的几个坑
每次部署都多多少少遇到问题，总结几个常见的。
坑一：数据库连接超时。
最常见的问题。原因要么是数据库IP/端口填错了，要么是数据库服务器的防火墙没放行，要么是数据库账号没给对应IP的访问权限。先在网关服务器上用telnet测一下能不能通数据库端口：
telnet DB_HOST DB_PORT通了再检查账号权限。
坑二：端口被占用。
8080、8000、9090这三个默认端口如果被其他服务占了，容器起不来。改.env里的端口配置就行。可以用netstat查一下哪些端口被占了：
netstat -tlnp | grep 8080坑三：模型协议选错。
不同渠道的API协议可能不一样。虽然大多数是OpenAI兼容的，但也有阿里兼容的、火山兼容的。选错协议的话，渠道测试会失败。如果不确定，先看供应商的文档，或者问一下技术支持。
坑四：内网私有化模型连不上。
如果要接内网私有化部署的模型，要确保网关服务器在同一个网络里，或者有专线/VPN打通。最常见的问题是网关服务器在外网，私有化模型在一个单独的内网，两边不通。部署前先确认网络拓扑。
上线后的运维要点
部署上线只是开始，后面还要维护。给几个实用的要点。
第一，定期看用量。
每天花5分钟看一下消费明细，确认用量有没有异常。如果某个部门用量突然涨了很多，赶紧排查是不是Key泄露了或者模型用错了。
第二，检查配额。
看一下哪些令牌快用完了，提前续配额。不要等100%阻断了才发现，业务方体验不好。
第三，日志定期清理。
API请求日志、会话日志这些会持续增长。建议每天清理7天前的日志，避免数据库撑爆。网关有自动清理配置，设置好就行。
第四，关注版本更新。
厂商会定期推送新版本，有的是修复bug，有的是安全补丁。建议每月看一下有没有新版本，确认没问题就升级。Docker方式升级很简单：
docker-compose pull && docker-compose up -d零停机滚动升级，业务不中断。
最后说几句
MAI Gateway的部署整体来说不算难，Docker Compose方式最快，15分钟就能起。但前面的准备工作（数据库、端口、渠道Key）要做扎实，后面部署过程基本不会卡壳。
我们这次帮朋友部署，前后两天搞定------第一天准备环境和资料，第二天部署+接入模型+对接业务。上线跑了两周没出问题。
如果遇到问题，先看官方文档，再看日志排查。实在搞不定，找技术支持，响应很快。