GPUStack 基于 Docker 与 Docker Compose 的安装部署实战指南

GPUStack 是一款面向高性能 AI 模型推理（vLLM、SGLang）与按需 SSH 可访问 GPU 实例的 GPU 集群管理平台。本文以官方安装文档为主体，结合仓库内的配置文件、入口脚本与源码实现，完整讲解如何通过 Docker 部署 GPUStack Server、如何准备 Worker 节点、如何获取初始管理员密码，以及 HTTPS 自定义证书、外部数据库、外部 Server URL、额外受信 CA 等常见自定义配置，最后介绍基于 Docker Compose 的一键部署方式。读完本文，你将具备从零部署一套可对外提供服务的 GPUStack 集群的完整实战能力。

一、安装前置条件

在开始部署之前，需要区分 GPUStack Server 与 GPUStack Worker 两类节点，二者的要求不同。

Server 节点要求

• 必须安装 Docker。Windows 与 macOS 上的 Docker Desktop 均受支持（Server 角色）。

Worker 节点要求

• 必须安装 Docker，但 Docker Desktop 不受支持。
• Worker 节点仅支持 Linux。Windows 用户请考虑使用 WSL2 且不要使用 Docker Desktop；macOS 不支持作为 Worker 节点。
• 必须根据硬件安装对应的 GPU 驱动与容器工具链，详见 安装要求。

系统与数据库要求

官方 安装要求 还给出了如下关键约束：

• GPUStack 支持 AMD64 与 ARM64 架构的主流现代 Linux 发行版；不支持通过 PyPI 直接安装，官方推荐使用 Docker 镜像以获得最佳兼容性。
• 节点间需要安装 NTP（Network Time Protocol）以保证状态同步一致。
• GPUStack Server 的状态存储在 SQL 数据库中。Server 容器镜像内置了嵌入式 PostgreSQL，开箱即用无需任何配置；也可通过 --database-url 参数或 GPUSTACK_DATABASE_URL 环境变量改用外部数据库，兼容版本如下：

数据库	已验证版本	Database URL 格式
PostgreSQL	13.0+	postgresql://username:password@host:port/dbname
MySQL	8.0.36+	mysql://username:password@host:port/dbname
openGauss	v6.0.5、v7.0.0-RC3	postgresql://username:password@host:port/dbname
OceanBase	CE-v4.3.5	mysql://username:password@host:port/dbname

其中 openGauss 兼容 PostgreSQL、OceanBase 兼容 MySQL，因此分别沿用 postgresql:// 与 mysql:// 的 URL scheme。

加速器运行时要求

GPUStack 支持多种通用加速器作为推理后端，包括 NVIDIA GPU、AMD GPU、Ascend NPU、Hygon DCU、MetaX GPU，以及实验性的 MThreads GPU、Iluvatar GPU、Cambricon MLU、T-Head PPU。每种加速器都需要在运行 GPUStack 前安装对应的驱动与容器工具链，例如：

• NVIDIA GPU：需要支持 CUDA 12.8 或更高版本的驱动，以及 NVIDIA Container Toolkit；可用 sudo nvidia-smi 验证驱动，用 sudo docker info 2>/dev/null | grep -q "nvidia" 验证容器工具链。
• AMD GPU：需要支持 ROCm 7.0 或更高版本的驱动与 AMD Container Runtime；对应验证命令为 sudo amd-smi static。
• Ascend NPU：需要 Ascend NPU 驱动与 Ascend Docker Runtime；验证命令为 sudo npu-smi info。
• 其他加速器（Hygon DCU、MetaX GPU、MThreads GPU、Iluvatar GPU、Cambricon MLU、T-Head PPU）的驱动、工具链与验证命令均可在 安装要求 中查到。

端口要求

GPUStack 通过固定端口通信，部署前请确保这些端口可用，具体端口清单见 安装要求 - 端口要求。核心端口包括：

• Server 端口：TCP 80（UI 与 API 默认端口）、TCP 443（启用 TLS 后的默认端口）、TCP 10161（Server 指标端点）、TCP 30080（Server 内部 API）、TCP 5432（嵌入式 PostgreSQL）。
• Worker 端口：TCP 10150（Worker 默认端口）、TCP 10151（Worker 指标端点）、TCP 40000-40063（推理服务端口范围）、TCP 41000-41999（vLLM 分布式部署使用的 Ray 服务端口范围）。

二、使用 Docker 安装 GPUStack Server

执行下面的命令即可安装并启动 GPUStack Server：

sudo docker run -d --name gpustack \
    --restart unless-stopped \
    -p 80:80 \
    --volume gpustack-data:/var/lib/gpustack \
    gpustack/gpustack

命令要点说明：

• --restart unless-stopped：容器退出后自动重启，保证服务可用性。
• -p 80:80：将容器内 80 端口映射到宿主机，用于提供 UI 与 API。
• --volume gpustack-data:/var/lib/gpustack：使用 Docker 命名卷持久化数据目录，其中保存数据库、模型文件与初始密码等关键状态。
• gpustack/gpustack：GPUStack v2 为所有 GPU 设备类型使用统一的单容器镜像，不再区分设备专属镜像。

从仓库的 pack/entrypoint.sh 可以看到容器入口脚本的行为：它会将 docker run 追加在镜像名之后的参数保存到 /run/gpustack/args，确保 nofile ulimit 不低于 65535（若不满足会在日志中提示使用 --ulimit nofile=65535:65535 启动），然后以 exec /init gpustack start $@ 的形式把剩余参数透传给 gpustack start 命令。

因此一个重要的 CLI 参数放置规则是：gpustack start 的命令行参数必须放在镜像名之后、docker run 命令的末尾，而不能作为 docker run 自身的选项。例如：

docker run [docker 选项] gpustack/gpustack <start-args>

完整参数列表见 CLI Reference：gpustack start。

三、启动、日志与初始登录

启动容器后，先检查启动日志确认服务是否正常：

sudo docker logs -f gpustack

日志显示服务就绪后，在浏览器中打开 http://your_host_ip 即可访问 GPUStack UI。

默认用户名为 admin，初始密码为自动生成，通过如下命令从容器内读取：

sudo docker exec -it gpustack \
    cat /var/lib/gpustack/initial_admin_password

从源码看，初始密码文件由服务端在首次初始化时写入数据目录：在 gpustack/routes/auth.py 中，initial_admin_password 文件路径由 config.data_dir 推导而来，即容器内的 /var/lib/gpustack/initial_admin_password，与上文 --volume gpustack-data:/var/lib/gpustack 挂载的数据目录一致。若希望使用自定义初始密码，可通过 --bootstrap-password 参数指定。

四、添加 GPU 集群与 Worker 节点

登录 GPUStack UI 后，按照 Clusters 和 Workers 页面上的界面提示，即可添加 GPU 集群与 Worker 节点。Worker 节点需要先满足第一节中列出的硬件驱动、容器工具链与端口要求，再使用页面提供的注册令牌（--token）与 Server 地址（--server-url）启动 Worker。

如果使用云厂商来供给 Worker 节点，请务必同时参考下文「配置外部 Server URL」一节，确保 Worker 能正确连接 Server。

五、自定义配置

以下小节给出启动 GPUStack Server 容器时的常见自定义配置示例；全部可用选项请参阅 CLI Reference。

启用 HTTPS（自定义证书）

GPUStack 支持使用自定义证书启用 HTTPS，需要在原有启动命令基础上追加 443 端口映射、证书目录挂载以及 SSL 相关环境变量：

 sudo docker run -d --name gpustack \
     ...
     -p 80:80 \
+    -p 443:443 \
     --volume gpustack-data:/var/lib/gpustack \
+    --volume /path/to/cert_files:/path/to/cert_files:ro \
+    -e GPUSTACK_SSL_KEYFILE=/path/to/cert_files/your_domain.key \
+    -e GPUSTACK_SSL_CERTFILE=/path/to/cert_files/your_domain.crt \
     gpustack/gpustack
     ...

其中：

• GPUSTACK_SSL_CERTFILE 应包含服务器证书及随后的任何中间证书。
• 当服务器证书由私有 CA 签名时，还需要挂载 PEM 格式的 CA 包，让 Worker 与 benchmark 容器能够自动验证 Server：

 sudo docker run -d --name gpustack \
     ...
+    -e GPUSTACK_SSL_CA_CERTFILE=/path/to/cert_files/ca-bundle.crt \
     gpustack/gpustack
     ...

证书校验的行为细节（来自原文档，并在 gpustack/config/config.py 的 read_server_ca_bundle 调用链中得到印证）：

• 对于自签名服务器证书，在未配置独立 CA 包时，会直接使用证书文件本身作为信任来源。
• 由公共 CA 签发的证书无需任何额外 CA 配置。
• Worker 的注册命令中包含 bootstrap CA 包的 SHA-256 校验和；Worker 会在安装未经过 TLS 验证下载的 bundle 之前先校验该校验和。这并非证书固定（certificate pinning）：如果 Server 已经通过正常 TLS 验证，Worker 会直接使用现有信任库，不会下载或检查 bootstrap bundle。
• Worker 会优先将验证过的 CA 安装到系统信任库；若系统信任库无法更新或 Worker 的 TLS 客户端使用不同的 bundle，则通过 SSL_CERT_FILE 为其进程及子进程使用临时合并 bundle。已有 operator 提供的证书会被保留；替换注入的 bootstrap CA 时不会保留更早注入的 bundle。
• 作为最后手段，当 Worker 无论如何都无法验证 Server 证书时，可在该 Worker 上设置 GPUSTACK_INSECURE_TLS=true 跳过与 Server 连接时的证书验证。注意：此时流量仍然加密，但不再受防拦截保护，只能在可信网络上使用。详见 环境变量文档。

使用外部数据库

默认情况下 GPUStack 使用嵌入式 PostgreSQL。如需使用 PostgreSQL、MySQL 等外部数据库，可通过设置 GPUSTACK_DATABASE_URL 环境变量（或 --database-url 参数）实现：

 sudo docker run -d --name gpustack \
     ...
     --volume gpustack-data:/var/lib/gpustack \
+    -e GPUSTACK_DATABASE_URL="postgresql://username:password@host:port/dbname" \
     gpustack/gpustack
     ...

兼容数据库及对应 URL 格式见 数据库要求（即第一节中的表格）。MySQL 用户使用 mysql://username:password@host:port/dbname 格式。在 CLI Reference 中，--database-url 的默认值为嵌入式 PostgreSQL，支持 PostgreSQL 13.0+、MySQL 8.0.36+ 及 openGauss、OceanBase 等兼容数据库。

配置外部 Server URL

如果使用云厂商供给 Worker，请设置外部 Server URL 用于 Worker 注册，确保 Worker 能正确连接到 Server：

sudo docker run -d --name gpustack \
    ...
+   -e GPUSTACK_SERVER_EXTERNAL_URL="https://your_external_server_url" \
    gpustack/gpustack
    ...

对应参数为 --server-external-url，该选项在通过云厂商供给 Worker 时是必需的。与之相关的还有 --trusted-hosts：当 GPUStack 位于反向代理之后时，它用于限制 X-Forwarded-Host 头；未设置时从 --server-external-url 推导，两者都未设置时默认为 *。

添加额外受信 CA

当 GPUStack 需要与使用私有或企业 CA 签发证书的服务通信时（例如自建 Identity Provider、Hugging Face 镜像或内部 API 端点），可以把 CA 证书挂载到容器的 /usr/local/share/ca-certificates/ 目录下，GPUStack 会在启动时自动导入挂载的 CA 证书并将其加入系统信任库：

 sudo docker run -d --name gpustack \
     ...
     --volume gpustack-data:/var/lib/gpustack \
+    --volume /path/to/custom-root-ca.crt:/usr/local/share/ca-certificates/custom-root-ca.crt:ro \
     gpustack/gpustack
     ...

注意：CA 证书必须是 PEM 编码且以 .crt 为扩展名；可以通过追加多个 --volume 标志挂载多个 CA 证书。

更多配置途径：环境变量与配置文件

除了 docker run 环境变量，GPUStack 还支持 YAML 配置文件。绝大部分命令行参数都能通过 GPUSTACK_ 前缀的大写环境变量设置（如 --data-dir 对应 GPUSTACK_DATA_DIR），也可在启动时用 --config-file 指定 YAML 配置文件。配置生效的优先级从高到低为：

1. 命令行参数
2. 环境变量
3. 配置文件
4. 默认值

即命令行参数始终覆盖环境变量，环境变量覆盖配置文件。完整的 YAML 配置示例（涵盖 port、tls_port、api_port、database_url、ssl_keyfile、ssl_certfile、server_external_url、worker_port、service_port_range、ray_port_range 等 Server/Worker/网关插件配置）见 CLI Reference：配置文件。环境变量完整列表见 环境变量文档。

六、使用 Docker Compose 安装

前置条件

• 必须安装 Docker Compose。
• 必须保证 端口要求 中列出的端口可用。

获取 Compose 文件并部署

Docker Compose 文件与相关配置文件维护在仓库的 docker-compose 目录下。先克隆仓库并切换到最新稳定版标签：

LATEST_TAG=$(
    curl -s "https://api.github.com/repos/gpustack/gpustack/releases" \
    | grep '"tag_name"' \
    | sed -E 's/.*"tag_name": "([^"]+)".*/\1/' \
    | grep -Ev 'rc|beta|alpha|preview' \
    | head -1
)
echo "Latest stable release: $LATEST_TAG"
git clone -b "$LATEST_TAG" https://gitcode.com/gh_mirrors/gp/gpustack.git
cd gpustack/docker-compose

启动 GPUStack Server：

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

服务启动后，在浏览器中打开 http://your_host_ip 访问 GPUStack UI。初始密码的获取方式与 Docker 部署一致，只是容器名为 gpustack-server：

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

Compose 文件结构说明

仓库中的 docker-compose.server.yaml 是最小化的 Server 部署定义：仅包含 gpustack-server 一个服务，镜像通过 IMAGE_REGISTRY、IMAGE_NAMESPACE、GPUSTACK_TAG 三个环境变量可覆盖（默认 docker.io/gpustack/gpustack:latest），挂载 gpustack-data 命名卷并映射 80:80 端口。

而 docker-compose.external-observability.yaml 展示了外接可观测性栈的部署方式：Server 通过 GPUSTACK_DISABLE_BUILTIN_OBSERVABILITY=true 关闭内置可观测性，并通过 GPUSTACK_GRAFANA_URL 指向浏览器可达的外部 Grafana（未设置该变量时 compose 会直接报错），同时一并启动 Prometheus 与 Grafana 容器（Prometheus 配置位于 docker-compose/prometheus/prometheus.yml，Grafana 的预置仪表盘与供给配置位于 docker-compose/grafana）。

可观测性选项

关于内置与外部可观测性（内置 Prometheus/Grafana、指标端点、仪表盘）的详细配置，请参阅 可观测性指南。

七、验证部署与排障要点

部署完成后建议按以下顺序验证：

1. 检查容器状态与日志：sudo docker logs -f gpustack（或 gpustack-server），确认无报错并完成启动流程。
2. 访问 UI 并登录：浏览器打开 http://your_host_ip，用 admin 与 initial_admin_password 文件中的初始密码登录；首次登录后建议尽快修改密码。
3. 添加 Worker：在 Clusters / Workers 页面按提示注册 Worker，并在 Worker 节点上确认 GPU 驱动、容器工具链与端口就绪（参考 安装要求）。
4. 核对自定义配置生效：若启用了 HTTPS、外部数据库或外部 Server URL，分别验证 443 端口可访问、数据库连接正常、云供给的 Worker 能成功注册。

常见的故障方向包括：Worker 无法连接 Server（检查 --server-url、外部 Server URL 与防火墙端口）、证书验证失败（检查 CA 包配置或按需使用 GPUSTACK_INSECURE_TLS，仅限可信网络）、端口被占用（核对第一节的端口清单）。更详细的故障排查内容可参考 Troubleshooting 文档；若需要 Helm 方式在 Kubernetes 中部署，请参阅 Helm 安装指南；离线环境部署请参阅 离线安装指南。