MAI Gateway实战部署：AI网关私有化部署？从0到1上手指南

私有化部署和公有云场景的最大区别是：公有云你从外部拉镜像就行，私有化很多时候要离线。

这是我们公司上周做的一次私有化部署。客户是个金融机构，内网完全隔离，不能访问公网，要求用达梦数据库。整个部署过程跟之前的公有云部署差别很大，写下来做个记录。

先说明：这个客户的场景是离线纯内网部署，所有模型也都是内网部署的。如果你们是半离线（网关能出去但Docker镜像要离线）或者混合模式（内网模型+外部供应商），可以参考对应步骤调整。

部署前准备：离线环境要准备的东西

离线环境的部署难点是------所有东西都得提前下好。Docker镜像、安装包、数据库安装包，一样都不能少。一旦内网部署开始，就没有网络了。

准备清单

**1. MAI Gateway离线安装包。**联系厂商获取，里面包含Docker镜像tar包、docker-compose.yml、环境变量模板。

**2. Docker和Docker Compose。**如果内网服务器还没装，也要提前准备安装包。推荐版本Docker 20.10+、Compose 2.0+。根据目标系统选对应的版本（CentOS/Ubuntu、x86_64/arm64）。

**3. 数据库。**客户指定达梦8，提前准备达梦8的安装包和激活文件。如果用MySQL或PostgreSQL，也要准备对应的安装包。

**4. 服务器。**客户给了三台服务器：一台8核16G跑MAI Gateway，一台4核8G跑Worker，一台8核16G跑达梦8。三台都在同一个内网VLAN，互相能通。

**5. 内网模型。**客户已经有几套内网模型跑在GPU服务器上了，网关部署好之后要接入这些模型。所以需要提前知道每个模型的API地址和端口。

准备工作的顺序

最好先在一台有公网的机器上把所有东西准备好，然后拷贝到U盘或者内网传输。不要在内网服务器上临时下载，一旦缺东西就卡住了。

部署步骤

准备好了开始。整个过程大概4-5小时，慢的话一天。

步骤一：部署达梦8数据库

先装数据库，因为网关启动需要数据库。达梦8的安装相对简单，图形化向导一步一步来。

关键配置：

安装路径：D:\dameng（或者/opt/dameng，根据操作系统）。

实例名：建议用maig_dameng。

端口：默认5236。

字符集：一定要选UTF-8。

模式：服务器模式。

装完之后用disql或者达梦管理工具登录，创建数据库和用户：

复制代码

CREATE TABLESPACE maig DATAFILE 'maig.dbf' SIZE 128;
CREATE USER maig IDENTIFIED BY "密码" DEFAULT TABLESPACE maig;
GRANT DBA TO maig;

达梦8默认没有utf8mb4概念，用UTF8就行，已经能支持中文和emoji。

开放达梦端口，确保网关服务器能telnet到5236。

步骤二：部署MAI Gateway（Docker离线方式）

装数据库的同时，网关服务器上开始装Docker。

如果内网服务器没装Docker：

复制代码

# 拷贝之前准备好的Docker安装包，解压安装
tar zxvf docker-20.10.24.tgz
cp docker/* /usr/bin/
# 配置systemd服务
# 然后启动Docker
systemctl enable --now docker

装完Docker，把离线镜像加载进去。MAI Gateway的离线安装包里有三个tar文件：maig-server.tar、maig-worker.tar、maig-web.tar。

复制代码

docker load -i maig-server.tar
docker load -i maig-worker.tar
docker load -i maig-web.tar

加载完确认三个镜像都在：

复制代码

docker images | grep maig

步骤三：修改配置

拷贝.env.example改成.env，关键修改数据库连接。注意达梦的JDBC驱动和MySQL不一样，MAI Gateway的.env里专门有DM相关的配置项。

复制代码

# 数据库类型，改成dm（默认是mysql）
DB_TYPE=dm

# 数据库连接
DB_HOST=达梦服务器IP
DB_PORT=5236
DB_USER=maig
DB_PASSWORD=你的密码
DB_NAME=maig_dameng

# 服务端口
SERVER_PORT=8080
API_PORT=8000

# 管理员初始账号
ADMIN_USER=admin
ADMIN_PASSWORD=初始密码

# 离线环境设置
OFFLINE_MODE=true

OFFLINE_MODE=true很重要，会禁用网关里所有需要联网的功能（比如检查新版本、自动更新模型列表），并且关闭遥测上报。

步骤四：启动服务

启动：

复制代码

docker compose up -d

查看状态：

复制代码

docker compose ps

查看日志：

复制代码

docker logs maig-server --tail 100

这一步如果出问题，大概率是数据库连不上。检查IP、端口、用户名密码，确认网关服务器能telnet到达梦5236。

达梦的一个小坑：默认达梦只允许本机访问，需要修改达梦的访问配置，或者在达梦服务器上给maig用户授权远程访问。

步骤五：初始化数据库

浏览器访问http://网关IP:8080，进入初始化页面，点"初始化数据库"。

达梦的初始化可能比MySQL慢一点，因为表结构有差异。等1-3分钟，看到"初始化成功"就可以了。

如果初始化失败，日志里一般能看到错误。常见的是权限不够（用户没建表权限）或者表空间不够。

步骤六：接入内网模型

登录之后，添加渠道（自定义→OpenAI兼容），填内网模型的API地址和Key。测试连接。

客户的GPU服务器上跑了几个模型：deepseek-chat、qwen-turbo、chatglm4，API地址分别是http://10.0.0.12:8080、http://10.0.0.13:8080。

每个模型加一个渠道，然后注册模型、配路由（故障转移，防止某个GPU挂了）。

步骤七：生成令牌并对接业务

和公有云场景一样。但私有化场景下IP白名单建议必设------客户的业务服务器都是固定IP，加上去更安全。

步骤八：验证

curl发请求：

复制代码

curl -X POST http://网关IP:8000/v1/chat/completions \
  -H "Authorization: Bearer sk-maig-令牌" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"你好"}]}'

返回正常 → 看API请求日志 → 确认链路通了。

部署中遇到的坑

这次部署遇到的坑，列一下给后面做私有化的朋友参考。

坑一：离线镜像加载慢

三个镜像加起来有1G多，在内网服务器上load花了快10分钟。之前在公网服务器上拉镜像也就2-3分钟。

原因是内网服务器磁盘IO慢。解决不了，只能等着。提前预留好时间。

坑二：达梦字符集问题

第一次装达梦的时候没注意字符集，选了GB18030。结果网关启动后，所有中文的模型名称在日志里都是乱码。改回去太麻烦，重装了一遍达梦。

达梦安装的时候一定要选UTF8，不要选GB18030。UTF8兼容GB18030的所有字符，而且是跨系统的通用标准。

坑三：达梦JDBC驱动找不到

达梦8的JDBC驱动（DmJdbcDriver18.jar或DmJdbcDriver17.jar）没有放在标准路径里，MAI Gateway启动的时候报"找不到驱动类"。

解决：在.env里增加DM_JDBC_DRIVER_PATH配置项，指定驱动jar包的路径：

复制代码

DM_JDBC_DRIVER_PATH=/opt/maig/lib/DmJdbcDriver18.jar

把驱动jar包拷贝到这个路径就行。

坑四：内网模型端口不通

客户的GPU服务器上模型已经跑起来了，curl localhost能通，但网关服务器curl那个IP+端口超时。

原因是GPU服务器的防火墙没放行那个端口。关掉防火墙或者开放端口就行：

复制代码

firewall-cmd --zone=public --add-port=8080/tcp --permanent
firewall-cmd --reload

坑五：达梦默认不允许远程连接

网关服务器telnet达梦5236超时，但达梦本机telnet 127.0.0.1:5236能通。

原因是达梦默认只监听本机。修改达梦的dm.ini配置文件，把LISTEN_IP改成0.0.0.0：

复制代码

dm.ini里找到 LISTEN_IP = 127.0.0.1，改成 LISTEN_IP = 0.0.0.0

改完重启达梦服务。

离线部署的几个建议

这次部署下来，有几个建议给做私有化的朋友。

**建议一：提前做网络拓扑图。**把所有服务器的IP、端口、VLAN归属画清楚。部署的时候按图来，不会乱。

**建议二：准备好回滚方案。**Docker Compose部署的好处是一键停：docker compose down。出问题先停掉，排查完重新起。

**建议三：准备两个U盘。**离线环境拷贝东西的时候，一个U盘万一坏了还有第二个。这次差点栽在U盘上。

**建议四：厂商技术支持提前打招呼。**私有化部署遇到问题，厂商远程帮你调比自己查快很多。提前沟通好，让他们在线待命。

最后说几句

这次纯离线私有化部署，从进场到全部跑通，花了大概一天半。比公有云部署慢很多，主要时间花在达梦适配和内网网络调试上。

但一旦跑通了，后续的运维反而简单------内网没有外部网络变化的影响，网关和模型都在可控范围内。

私有化部署的核心难点是"离线"和"国产化适配"。Docker镜像提前load、达梦字符集选UTF8、JDBC驱动路径配对、LISTEN_IP改成0.0.0.0------这四个点做对了，达梦的坑基本就踩完了。

有问题欢迎评论区交流。