# Docker Compose 部署指南

本文档介绍如何使用 Docker Compose 部署 MaaS-Base 平台。Docker Compose 方式适合单机部署、开发测试和小团队使用。

## 前置要求

| 要求 | 说明 |
|------|------|
| 操作系统 | Linux（推荐 Ubuntu 20.04+ / Debian 12+） |
| Docker | 20.10+，已安装 [Docker Compose](https://docs.docker.com/compose/install/) |
| CPU 节点 | 至少 4 核 CPU，8GB 内存（仅 Server 节点） |
| 磁盘空间 | 至少 20GB 可用空间 |

> **注意：** Server 可运行在无 GPU 的 CPU 节点上。GPU 节点用于部署 Worker，参见 [Worker 节点部署指南](../deployment/worker.md)。

## 部署模式

项目提供两套 Docker Compose 配置，可根据需求选择：

| 配置文件 | 包含组件 | 适用场景 |
|----------|---------|---------|
| `docker-compose.server.yaml` | PostgreSQL + Server | 最小部署，已有外部监控体系 |
| `docker-compose.external-observability.yaml` | PostgreSQL + Server + Prometheus + Grafana | 完整部署，内置可观测性 |

---

## 模式一：最小部署（PostgreSQL + Server）

### 1. 克隆项目

```bash
git clone https://github.com/your-org/maas-base.git
cd maas-base/docker-compose
```

### 2. 启动服务

```bash
docker compose -f docker-compose.server.yaml up -d
```

该命令会启动以下两个容器：

- **`maas-base-db`** — PostgreSQL 16 数据库
- **`maas-base-server`** — MaaS-Base Server（从 `pack/Dockerfile` 自动构建镜像）

### 3. 验证部署

```bash
# 查看容器状态
docker compose -f docker-compose.server.yaml ps

# 查看 Server 日志
docker compose -f docker-compose.server.yaml logs -f maas-base-server
```

### 4. 获取初始管理员密码

```bash
docker exec maas-base-server cat /var/lib/maas-base/initial_admin_password
```

### 5. 访问 UI

在浏览器中打开 `http://<服务器IP>`，使用用户名 `admin` 和上一步获取的密码登录。

---

## 模式二：完整部署（含 Prometheus + Grafana）

### 1. 克隆项目

```bash
git clone https://github.com/your-org/maas-base.git
cd maas-base/docker-compose
```

### 2. 启动服务

```bash
GPUSTACK_VERSION=$(git -C .. rev-parse --short HEAD) docker compose -f docker-compose.external-observability.yaml up -d --build
```

```BASH
 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 Server
- **`maas-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. 获取初始管理员密码

```bash
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` 文件：

```env
POSTGRES_PASSWORD=my_secure_db_password_123
GRAFANA_PASSWORD=my_secure_grafana_password
```

然后启动：

```bash
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` 配置：

```yaml
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` 环境变量连接：

```yaml
environment:
  GPUSTACK_DATABASE_URL: postgresql://user:password@host:5432/gpustack
```

此时可从 `docker-compose.*.yaml` 中移除 `postgres` 服务及其 `depends_on` 依赖。

---

## 停止与清理

```bash
# 停止服务（保留数据卷）
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
```

---

## 更新镜像

```bash
# 拉取最新代码
git pull

# 重新构建并启动
docker compose -f docker-compose.external-observability.yaml up -d --build
```

---

## 下一步

- 部署 Worker 节点以提供 GPU 推理能力 → [Worker 节点部署指南](../deployment/worker.md)
- 使用 Kubernetes 进行大规模部署 → [Kubernetes (Helm) 部署指南](../deployment/kubernetes.md)