Skip to content

Docker部署 ​

概述 ​

本文介绍如何使用 Docker Compose 部署 Mars AI Studio 的完整生产环境。

部署相关的所有文件位于 devops/ 目录:

devops/
├── deploy.sh                      # 统一部署入口脚本
└── docker/
    ├── docker-compose.prod.yaml    # 生产编排文件
    ├── backend/Dockerfile          # 后端镜像构建
    ├── mysql/import-mars-ai.sh     # MySQL 初始化导入脚本
    ├── nginx/nginx.conf            # 反向代理与静态资源服务
    ├── nginx/web/                  # 前端构建产物(dist)放置目录
    ├── nginx/ssl/                  # SSL 证书目录(可选)
    └── milvus/                     # Milvus standalone 独立编排

部署架构 ​

整套服务通过 mars_ai_network 桥接网络互联,容器间使用服务名(如 mysql、redis、backend)互相访问。对外仅暴露 Nginx 的 80/443 端口,由 Nginx 统一转发 API 与托管前端。

  • 后端(backend)与 AI 异步任务队列(ai-worker)共用同一镜像,前者提供 HTTP 接口,后者消费 arq 队列(文档解析、异步向量化等)。
  • 前端不单独起服务,由 Nginx 直接托管 nginx/web 下的静态文件,并将 /api/v1 反向代理到后端。
  • 有状态服务(MySQL、Redis、Milvus 及 etcd、MinIO)的数据全部挂载到宿主机目录,容器销毁后数据不丢失。

环境准备 ​

服务器配置 ​

服务器配置选型

最低配置:64核64GB,固态硬盘容量2TB+2TB,8GB新款NVIDAI/AMD显卡

推荐配置:32核64GB,固态硬盘容量4TB+4TB,16GB新款NVIDAI/AMD显卡

说明:

  • 显卡用于本地部署文档解析引擎、嵌入/重排模型。
  • 建议使用云端大模型。如果需要本地部署大模型,则增加额外服务器和显卡。
  • 服务器具体配置以客户业务需求为准

操作系统:推荐Ubuntu Server 24.04 LTS

安装Docker ​

设置 Docker 的 apt 源

sh
# 信任 Docker 的 GPG 公钥
sudo apt-get update && apt-get install ca-certificates curl gnupg -y
sudo install -m 0755 -d /etc/apt/keyrings

# 下面命令可能失败,多试几次
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 添加仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

安装Docker

sh
apt-get update
apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

# 安装成功后查看版本
docker version

设置开机启动

sh
systemctl start docker
systemctl enable docker
systemctl status docker

设置镜像加速 ​

配置镜像源

sh
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io",
    "https://dislabaiot.xyz"
  ]
}
EOF

# 重启服务生效
sudo systemctl daemon-reload && sudo systemctl restart docker

部署步骤 ​

生产环境配置 ​

编辑后端生产环境变量 backend/env/.env.prod,至少确认以下关键项:

  • DATABASE_PASSWORD / REDIS_PASSWORD / MINIO_ROOT_PASSWORD:compose 会用它们初始化 MySQL、Redis、MinIO,生产环境务必改为强密码。
  • SECRET_KEY:JWT 签名密钥,生产必须覆盖默认值(可用 python -c "import secrets; print(secrets.token_urlsafe(48))" 生成)。

构建前端 ​

确认配置文件 frontend/apps/web-ele/.env.production ,在开发环境构建前端

bash
# 本地开发环境构建,构建结果:frontend\apps\web-ele\dist.zip
cd frontend
pnpm build:ele

### 下面信息表示构建成功
#@vben/web-ele:build: ✓ built in 19.65s
#@vben/web-ele:build: ZIP file created: D:\workspace_ai\mars-ai-studio\frontend\apps\web-ele\dist.zip

执行部署脚本 ​

以 Ubuntu Server 22.04 LTS 为例,以 root 用户 SSH 登录服务器,执行下面命令:

bash
# 安装解压工具(只需安装一次)
apt install unzip

# 下载最新代码到服务器
cd /opt
git clone https://gitee.com/abc/mars-ai-studio.git # 修改为自己的代码仓库
cd /opt/mars-ai-studio
git pull

# 手动上传前端产物 dist.zip 到下面目录
cd /opt/mars-ai-studio/devops/docker/nginx/web/ 
# (上传过程略)
unzip dist.zip

# 执行完整部署(构建 → 备份 → 迁移 → 启动 → 清理),第一次部署约15~30分钟
cd /opt/mars-ai-studio/devops
bash /opt/mars-ai-studio/devops/deploy.sh

MinerU部署 ​

详见《MinerU安装与使用》

vLLM部署 ​

详见《vLLM安装与使用》

部署后配置 ​

浏览器登录:http://<服务器IP> 默认账号 admin / admin123

  • 文件管理--文件配置,修改本地存储的自定义域名。同域部署请留空。
  • MinerU功能:基础设施--配置管理,mineru_api_base 填写正确的地址。
  • TEI功能:API 密钥 -- TEI 平台,BASE URL 填写正确的地址。
  • (可选)开发环境backend\static\upload目录下的文件,默认没有上传到服务器。如果需要,自行复制到服务的/opt/docker-data/backend/upload目录。

日常运维 ​

数据持久化 ​

所有有状态数据挂载到 DOCKER_DATA_DIR(默认 /opt/docker-data)下。Docker 数据目录配置位置:backend/env/.env.prod

bash
# 建议保持默认
DOCKER_DATA_DIR=/opt/docker-data

目录用途

子目录用途
mysql/dataMySQL 数据文件
mysql/backupmysqldump 备份(gzip)
redis/dataRedis AOF 持久化
backend/logs后端日志(挂载到容器 /app/logs)
backend/upload上传文件(挂载到容器 /app/static/upload)
bash
# 数据目录
root@ubuntu22:~# tree -L 2 /opt/docker-data
/opt/docker-data
├── backend
│   ├── logs
│   └── upload
├── mysql
│   ├── backup
│   └── data
└── redis
    └── data

docker compose down(或脚本 destroy)只删除容器与网络,数据保留在宿主机。

DANGER

生产环境清理数据,属于高危操作!务必先对数据进行备份,再操作!

部署脚本说明 ​

部署脚本 devops/deploy.sh,所有命令执行前都会先加载 backend/env/.env.prod 环境变量

bash
# 进入仓库根目录
cd /opt/mars-ai-studio

# 完整部署(构建 → 备份 → 迁移 → 启动 → 清理)
bash devops/deploy.sh

# 启动 / 停止 / 重启 / 销毁
bash devops/deploy.sh start
bash devops/deploy.sh stop
bash devops/deploy.sh restart
bash devops/deploy.sh destroy

# 查看状态与日志
bash devops/deploy.sh verify
bash devops/deploy.sh logs

# 数据库备份与迁移
bash devops/deploy.sh backup
bash devops/deploy.sh migrate

docker命令 ​

对外暴露端口由 .env.prod 控制:HTTP_PORT(默认 80)、HTTPS_PORT(默认 443)。docker-compose.prod.yaml 为各服务设置内存上限,生产环境建议按实际负载调整。

  • MySQL 2GB
  • Redis 512MB
  • backend 2GB
  • ai-worker 2GB
  • nginx 256MB。
sh
# 查看各服务状态
docker ps
docker compose -f /opt/mars-ai-studio/devops/docker/docker-compose.prod.yaml ps

# 查看容器最后50条日志
docker logs -n 50 mars-ai-backend

# 查看容器CPU/内存等使用情况
docker stats

# 查看容器内部进程
docker top mars-ai-backend

# 查看容器详细信息
docker inspect mars-ai-backend

# 进入容器
docker exec -it mars-ai-backend /bin/bash

运维场景 ​

场景一 ​

需求:删除MySQL数据库所有内容,重新执行backend\sql\mysql\mars-ai-studio.sql

操作类型:高危操作

操作步骤:

bash
cd /opt/mars-ai-studio

# 1. 停止全部服务
bash devops/deploy.sh stop

# 2. 删除 MySQL 数据目录(自动备份在目录 /opt/docker-data/mysql/backup)
rm -rf /opt/docker-data/mysql/data

# 3. 重新启动(MySQL 重新初始化,自动执行 import-mars-ai.sh 导入 dump)
bash devops/deploy.sh start
# 当代码也有更新,则重新部署
# bash devops/deploy.sh

场景二 ​

需求:删除Milvus向量数据库所有数据

操作类型:高危操作

操作步骤:使用VectorDBZ连接Milvus,删除集合mars_ai_studio