docker-compose.md 6.1 KB
Docker Compose 部署指南
本文档介绍如何使用 Docker Compose 部署 MaaS-Base 平台。Docker Compose 方式适合单机部署、开发测试和小团队使用。
前置要求
| 要求 | 说明 |
|---|---|
| 操作系统 | Linux（推荐 Ubuntu 20.04+ / Debian 12+） |
| Docker | 20.10+，已安装 Docker Compose |
| CPU 节点 | 至少 4 核 CPU，8GB 内存（仅 Server 节点） |
| 磁盘空间 | 至少 20GB 可用空间 |
注意： Server 可运行在无 GPU 的 CPU 节点上。GPU 节点用于部署 Worker，参见 Worker 节点部署指南。
部署模式
项目提供两套 Docker Compose 配置，可根据需求选择：
| 配置文件 | 包含组件 | 适用场景 |
|---|---|---|
docker-compose.server.yaml |
PostgreSQL + Server | 最小部署，已有外部监控体系 |
docker-compose.external-observability.yaml |
PostgreSQL + Server + Prometheus + Grafana | 完整部署，内置可观测性 |
模式一：最小部署（PostgreSQL + Server）
1. 克隆项目
git clone https://github.com/your-org/maas-base.git
cd maas-base/docker-compose
2. 启动服务
docker compose -f docker-compose.server.yaml up -d
该命令会启动以下两个容器：
maas-base-db— PostgreSQL 16 数据库maas-base-server— MaaS-Base Server（从pack/Dockerfile自动构建镜像）
3. 验证部署
# 查看容器状态
docker compose -f docker-compose.server.yaml ps
# 查看 Server 日志
docker compose -f docker-compose.server.yaml logs -f maas-base-server
4. 获取初始管理员密码
docker exec maas-base-server cat /var/lib/maas-base/initial_admin_password
5. 访问 UI
在浏览器中打开 http://<服务器IP>，使用用户名 admin 和上一步获取的密码登录。
模式二：完整部署（含 Prometheus + Grafana）
1. 克隆项目
git clone https://github.com/your-org/maas-base.git
cd maas-base/docker-compose
2. 启动服务
GPUSTACK_VERSION=$(git -C .. rev-parse --short HEAD) docker compose -f docker-compose.external-observability.yaml up -d --build
nohup sh -c 'GPUSTACK_VERSION=$(git -C .. rev-parse --short HEAD) docker compose -f docker-compose.external-observability.yaml up -d --build' > deploy.log 2>&1 &
该命令会启动以下四个容器：
maas-base-db— PostgreSQL 16 数据库maas-base-server— MaaS-Base Servermaas-base-prometheus— Prometheus 指标采集maas-base-grafana— Grafana 监控面板
3. 访问服务
| 服务 | 地址 | 默认凭据 |
|---|---|---|
| MaaS-Base UI | http://<服务器IP>:80 |
admin / 初始密码 |
| Prometheus | http://<服务器IP>:9090 |
无 |
| Grafana | http://<服务器IP>:3100 |
admin / grafana |
4. 获取初始管理员密码
docker exec maas-base-server cat /var/lib/maas-base/initial_admin_password
环境变量配置
所有环境变量均可通过 .env 文件或 --env-file 参数传入。
| 变量 | 默认值 | 说明 |
|---|---|---|
POSTGRES_PASSWORD |
gpustack |
PostgreSQL 数据库密码 |
GPUSTACK_GRAFANA_URL |
空 | Grafana 外部访问地址（留空则自动使用相对路径 /grafana） |
IMAGE_REGISTRY |
docker.io |
镜像仓库地址（可用于替换为国内镜像源） |
PROMETHEUS_IMAGE_NAMESPACE |
prom |
Prometheus 镜像命名空间 |
PROMETHEUS_TAG |
latest |
Prometheus 镜像标签 |
GRAFANA_IMAGE_NAMESPACE |
grafana |
Grafana 镜像命名空间 |
GRAFANA_TAG |
latest |
Grafana 镜像标签 |
GRAFANA_PASSWORD |
grafana |
Grafana 管理员密码 |
示例：使用自定义密码
创建 .env 文件：
POSTGRES_PASSWORD=my_secure_db_password_123
GRAFANA_PASSWORD=my_secure_grafana_password
然后启动：
docker compose -f docker-compose.external-observability.yaml --env-file .env up -d
数据持久化
Docker Compose 使用命名卷（named volumes）进行数据持久化：
| 卷名 | 用途 | 挂载路径 |
|---|---|---|
postgres-data |
PostgreSQL 数据 | /var/lib/postgresql/data |
prom_data |
Prometheus 指标数据 | /prometheus |
gpustack-data |
Server 数据（含日志、配置、嵌入式数据库备份） | /var/lib/gpustack |
如需将数据映射到宿主机目录，可修改 volumes 配置：
volumes:
- /data/postgres:/var/lib/postgresql/data
- /data/prometheus:/prometheus
- /data/gpustack:/var/lib/gpustack
端口说明
| 端口 | 组件 | 用途 |
|---|---|---|
80 |
Server API | REST API、Web UI、模型推理接口 |
10161 |
Server Metrics | Prometheus 抓取指标 |
9090 |
Prometheus | Prometheus Web UI |
3100 |
Grafana | Grafana 监控面板 |
安全建议： 生产环境中建议仅开放
80端口，其他端口通过反向代理或内网访问。
外部数据库
如果已有 PostgreSQL 或 MySQL，可以不部署内嵌数据库，通过修改 GPUSTACK_DATABASE_URL 环境变量连接：
environment:
GPUSTACK_DATABASE_URL: postgresql://user:password@host:5432/gpustack
此时可从 docker-compose.*.yaml 中移除 postgres 服务及其 depends_on 依赖。
停止与清理
# 停止服务（保留数据卷）
docker compose -f docker-compose.server.yaml down
# 停止服务并删除数据卷（数据将丢失）
docker compose -f docker-compose.server.yaml down -v
# 查看日志
docker compose -f docker-compose.server.yaml logs -f
# 仅查看 Server 日志
docker compose -f docker-compose.server.yaml logs -f maas-base-server
更新镜像
# 拉取最新代码
git pull
# 重新构建并启动
docker compose -f docker-compose.external-observability.yaml up -d --build
下一步
- 部署 Worker 节点以提供 GPU 推理能力 → Worker 节点部署指南
- 使用 Kubernetes 进行大规模部署 → Kubernetes (Helm) 部署指南