很多朋友在选型阶段就问部署的事。这是能理解的——选产品之前先摸清楚部署难不难、要多少资源、会不会卡住。
MAI Gateway官方提供了三种部署方式。这篇先聊最简单、上手最快的：Docker Compose单机部署。适合测试环境、POC、用量不大的生产环境。集群版和K8s部署后面单独写。
整篇按时间线来，从准备环境到业务调通，中间每一步该做什么、可能遇到什么问题，都写清楚。
部署前：准备好这些东西
动手之前先盘点，缺一样可能就卡壳。
服务器
最低4核8G就能跑。但建议至少5核10G，留一点余量给数据库（如果数据库也部署在同一台）。如果数据库单独部署，网关本身4核8G够用。
操作系统选CentOS 7.9、Ubuntu 20.04或22.04。Docker版本要求20.10以上，Docker Compose要求2.0以上。
检查一下Docker和Compose版本：
docker –version
docker compose version
如果没装，用官方脚本一键装：
curl -fsSL https://get.docker.com | bash -s docker –mirror Aliyun
systemctl enable –now docker
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
国内服务器建议换一下Docker镜像源，不然后面拉镜像会很慢。编辑/etc/docker/daemon.json，加上：
{
"registry-mirrors": ["https://docker.m.daocloud.io", "https://mirror.ccs.tencentyun.com"]
}
然后重启Docker：
systemctl daemon-reload
systemctl restart docker
数据库
MAI Gateway需要一个关系型数据库。MySQL 5.7+/8.0+、PostgreSQL 10+都行。有国产化需求的话达梦8也支持。
数据库可以跟网关部署在同一台机器上，也可以独立部署。推荐独立部署，方便后续扩展。
先创建好数据库和账号：
CREATE DATABASE maig DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'maig'@'%' IDENTIFIED BY '你的密码';
GRANT ALL PRIVILEGES ON maig.* TO 'maig'@'%';
FLUSH PRIVILEGES;
数据库服务器防火墙要放行对应端口（MySQL默认3306）。
端口
MAI Gateway默认暴露三个端口：
8080：管理界面，浏览器访问。
8000：API转发端口，业务方调模型走这个。
9090：日志端口，内部用的，不用对外开放。
服务器防火墙放行8080和8000就行：
firewall-cmd –zone=public –add-port=8080/tcp –permanent
firewall-cmd –zone=public –add-port=8000/tcp –permanent
firewall-cmd –reload
渠道信息
所有要接入的模型供应商，API Key、Base URL、协议类型，提前整理好。部署完直接填。
部署步骤
准备好了就开始。正常情况下，从下载到跑通，15-20分钟。
步骤一：拿到安装包
从官方获取最新版安装包，解压后里面有docker-compose.yml和.env.example两个关键文件。
unzip maig-gateway-v1.3.0.zip
cd maig-gateway-v1.3.0
步骤二：修改配置
复制环境变量模板，改成.env：
cp .env.example .env
vim .env
主要修改以下几项：
# 数据库配置
DB_HOST=数据库IP地址
DB_PORT=3306
DB_USER=maig
DB_PASSWORD=你的数据库密码
DB_NAME=maig
# 服务端口
SERVER_PORT=8080
API_PORT=8000
# 管理员初始账号
ADMIN_USER=admin
ADMIN_PASSWORD=初始密码（登录后记得改）
如果端口被占了，改SERVER_PORT和API_PORT。DB_HOST如果是本机，填127.0.0.1。
步骤三：启动服务
一条命令：
docker compose up -d
然后等几十秒，查看容器状态：
docker compose ps
正常应该看到三个容器：maig-server、maig-worker、maig-web，状态都是Up。
如果有容器没起来，看日志排查：
docker logs maig-server –tail 100
最常见的失败原因是数据库连不上。在网关服务器上测一下能不能通：
telnet 数据库IP 3306
不通的话检查防火墙、数据库权限、IP白名单。
步骤四：初始化并登录
浏览器访问：http://服务器IP:8080
第一次访问会跳转到初始化页面，点"初始化数据库"，等1-2分钟，看到"初始化成功"就可以用了。
用.env里配的ADMIN_USER和ADMIN_PASSWORD登录。
步骤五：接入渠道和模型
登录后第一件事：添加渠道。进入"模型管理"→"渠道列表"，点"添加渠道"。
填渠道名称、Base URL、API Key、协议类型。协议类型一般选OpenAI兼容，大多数渠道都兼容。不确定的话看供应商的文档。
添加完渠道，点"测试连接"。成功了会返回"测试成功"。
然后注册模型：进入"模型管理"→"模型列表"，点"注册模型"。选刚才加的渠道，填模型名称（要和供应商那边一致），保存。
可以批量注册，也可以一个个来。
步骤六：生成令牌并对接业务
模型接好之后，给业务方生成调用令牌。进入"令牌管理"→"新建令牌"：
填令牌名称（方便识别，比如"客服部-张三"），选能用哪些模型，设日/月/总配额。保存后会生成一个API Key，复制给业务方。
业务方调模型的时候，把网关的API转发地址（http://服务器IP:8000）和生成的Key填到他们的AI助手或者应用里。
步骤七：验证
让业务方调一次模型，然后在管理界面看"API请求日志"，确认请求确实走到网关上了。能看到请求记录、Token消耗、渠道信息，就通了。
部署中常见的坑
每次部署都多多少少遇到问题，总结几个高频的。
坑一：数据库连不上
现象：maig-server容器启动后几秒就挂，日志里写"connection refused"或者"access denied"。
排查：先telnet测端口能不能通。通了再检查数据库账号权限——有没有给对应用户授权、host是不是允许远程访问（CREATE USER 'maig'@'%'）。
坑二：端口被占
现象：容器启动失败，日志里写"address already in use"。
排查：netstat -tlnp | grep 8080，看看哪个进程占了。要么改.env里的端口，要么停掉占端口的服务。
坑三：Docker镜像拉不下来
现象：docker compose up的时候卡在拉镜像，超时。
排查：换镜像源，前面准备步骤里有。或者手动docker pull，看报什么错。
坑四：渠道测试失败
现象：添加完渠道点"测试连接"，返回"连接失败"。
排查：第一，Base URL有没有写错。第二，协议类型选对了没有。第三，服务器能不能访问到这个Base URL（curl测一下）。第四，API Key有没有复制错。
curl -X POST Base_URL/v1/chat/completions -H "Authorization: Bearer 你的Key" -H "Content-Type: application/json" -d '{"model":"模型名","messages":[{"role":"user","content":"hi"}]}'
用curl能通，说明是配置问题。curl也不通，说明是网络或Key问题。
坑五：业务方调不通
现象：业务方说调模型报401或404。
排查：401是Key错了，检查一下。404是模型名不对，业务方填的模型名要和网关注册的一致。也可能是API端口填成了管理端口，注意业务方用的是8000不是8080。
上线后的运维建议
部署完不是结束，日常维护注意几点。
每天花5分钟看用量。进入"费用中心"→"消费明细"，看用量有没有异常波动。某个部门用量突然翻几倍，赶紧排查。
定期检查配额。快到100%阻断了提前续，不要等业务方反馈"调不通"才发现。
关注版本更新。Docker方式升级很简单：
docker compose pull
docker compose up -d
零停机滚动升级，业务不中断。建议每月看一下有没有新版本，安全补丁及时更。
日志定期清理。API请求日志、会话日志持续增长，建议清理7天前的。网关后台有自动清理配置，设一下就行。
最后说几句
魔芋AI 走到今天，离不开每一位用户的支持与信任。为感谢大家一路同行，我们在今年双十一拿出最大的诚意，为大家带来不一样的玩法和极致的折扣体验：
✅每日打卡：连续签到 11 天，可获得千万token以及抽奖机会！
✅限时秒杀：数百款大模型全线打折，Deepseek、GLM 5.2、Wan 3.0、MiniMax-H3-Fast全都有，低至0.1折！
✅组队开黑：双人各得亿万 Token，车队人越多价越低，低至 2 折！
✅邀新任务：每邀 1 位实名好友 1000万，最高可得 2.1亿！
✅幸运转盘：大转盘盲盒抽奖，100% 中奖，无空奖！
11月1日 00:00 活动开启，提前注册，开服直进！我们在魔芋AI等你！
