maas-base/docs/deployment-linux-docker.md

Linux Docker 部署指南

前置要求

• Linux（Ubuntu 22.04+ 或 CentOS 8+）
• Docker 24.0+
• Docker Compose v2.20+

安装 Docker：

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker

---

一、基础部署（含内置 PostgreSQL）

适合快速上手，所有组件运行在同一台机器。

1. 进入 docker-compose 目录

cd /path/to/maas-base/docker-compose

2. 启动服务

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

3. 查看初始管理员密码

docker exec gpustack-server cat /var/lib/gpustack/initial_admin_password

4. 访问

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

---

二、使用外部 PostgreSQL

如果已有 PostgreSQL 实例，通过环境变量指定连接地址。

1. 创建 .env 文件

cat > .env <<EOF
POSTGRES_PASSWORD=your_strong_password
EOF

2. 修改 docker-compose.server.yaml 中的数据库配置

将 postgres 服务替换为外部数据库连接：

environment:
  GPUSTACK_DATABASE_URL: postgresql://gpustack:your_password@your_db_host:5432/gpustack

并删除 postgres 服务和 postgres-data volume。

确保外部数据库已执行授权：

GRANT CREATE ON SCHEMA public TO gpustack;
GRANT ALL PRIVILEGES ON DATABASE gpustack TO gpustack;

3. 启动

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

---

三、含外部监控部署（Prometheus + Grafana）

适合需要独立监控面板的场景。

1. 创建 .env 文件

cat > .env <<EOF
POSTGRES_PASSWORD=your_strong_password
GRAFANA_PASSWORD=your_grafana_password
GPUSTACK_GRAFANA_URL=http://<服务器IP>:3000
EOF

GPUSTACK_GRAFANA_URL 必须是浏览器可访问的地址（不能是容器内部地址）。

2. 启动

docker compose -f docker-compose.external-observability.yaml up -d

3. 访问

服务	地址	默认账号
GPUStack	http://<IP>:80	admin / 见 initial_admin_password
Grafana	http://<IP>:3000	admin / 见 .env
Prometheus	http://<IP>:9090	-

---

四、常用运维命令

# 查看服务状态
docker compose -f docker-compose.server.yaml ps

# 查看日志
docker logs -f gpustack-server

# 停止服务
docker compose -f docker-compose.server.yaml down

# 停止并删除数据（危险）
docker compose -f docker-compose.server.yaml down -v

# 更新镜像
docker compose -f docker-compose.server.yaml pull
docker compose -f docker-compose.server.yaml up -d

---

五、GPU 支持

NVIDIA GPU

需要安装 NVIDIA Container Toolkit：

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
apt-get update && apt-get install -y nvidia-container-toolkit
nvidia-ctk runtime configure --runtime=docker
systemctl restart docker

在 docker-compose.server.yaml 的 gpustack-server 服务中添加：

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

AMD GPU

在 gpustack-server 服务中添加：

devices:
  - /dev/kfd:/dev/kfd
  - /dev/dri:/dev/dri
group_add:
  - video

---

六、注意事项

1. 端口冲突：确保 80、5432、9090、3000 端口未被占用。

2. 防火墙：开放对应端口：

   ufw allow 80/tcp
   ufw allow 3000/tcp   # Grafana（如需外部访问）
   

3. 数据持久化：数据存储在 Docker volume 中，删除容器不会丢失数据，但 down -v 会清除所有数据。

4. 生产环境：建议修改 .env 中的所有默认密码。