企业官网建设流程全解析

• 后端
• 人工智能
• 模型推理服务
• 集群管理
• 可观测性

本指南围绕 GPUStack 的 DigitalOcean 云提供商集群展开：从准备 Personal Access Token、配置--server-external-url，到通过 Web 控制台创建云凭证、Worker Pool，再到理解 droplet 的 cloud-init 自动初始化过程与安全缩容步骤。读完本文，你将掌握如何在 GPUStack 中按需拉起 DigitalOcean GPU 工作节点，将其纳入统一集群调度，并安全地销毁不再需要的 droplet。文中涉及的底层实现均可在 cloud_providers/digital_ocean.py 等源码中逐一印证。

背景：GPUStack 如何利用云提供商扩展集群

GPUStack 支持多种集群形态：Docker与Kubernetes属于自托管（Self-Host）方式，而DigitalOcean与SHUIHUA FUTURE则属于云提供商（Cloud Provider）方式。当创建一个 DigitalOcean 集群时，GPUStack 会调用 DigitalOcean API 自动创建 worker（即 droplet），并将它们加入 GPUStack 集群，随后即可在这些节点上部署模型实例。

从源码看，云提供商的抽象定义在 cloud_providers/abstract.py，其生命周期注释清晰说明了调用顺序：

1. create_ssh_key—— 在云侧注册 SSH 公钥
2. create_instance—— 携带已创建的 SSH 密钥创建实例
3. wait_for_started—— 等待实例启动
4. wait_for_public_ip—— 等待公网 IP 分配
5. （可选）create_volumes_and_attach—— 创建并挂载卷
6. delete_instance—— 销毁实例
7. （可选）delete_ssh_key—— 删除 SSH 密钥

DigitalOcean 的具体实现位于 cloud_providers/digital_ocean.py，通过官方异步 SDKpydo.aio.Client与https://api.digitalocean.com通信。该客户端将 droplet 的new/active状态映射为 GPUStack 的created/running状态，并在启动与公网 IP 分配上分别做轮询等待（默认每 15 秒探测一次，最多 20 次重试，超时抛出TimeoutError）。

准备工作：Token、权限与 Server URL

创建 Personal Access Token

首先需要注册 DigitalOcean 账号，并在其 API 页面创建一个 Personal Access Token（PAT）。创建完成后，在 GPUStack 的Cloud Credentials页面填入该 Token，即可让 GPUStack 以该账号身份调用 DigitalOcean API。

注意：Token 的作用域必须设置为Full Access。如果使用 Custom Scopes 自定义权限，可能会在删除 droplet 时遇到失败。原因在于 GPUStack 销毁 droplet 时调用的是droplets.destroy_with_associated_resources_dangerous（见 digital_ocean.py），该接口需要较完整的删除权限，权限不足会导致清理不彻底。

配置--server-external-url

启动 GPUStack Server 时，必须指定--server-external-url参数。该参数用于在 droplet 创建并启动 worker 后，配置 worker 的--server-url——即 droplet 内的 worker 进程通过该地址回连 GPUStack Server API。

如果 Server 运行在反向代理之后，请务必把代理地址填进去，确保公网上的 droplet 能通过该地址访问 GPUStack Server API。该参数在 cmd/start.py 中定义，可通过命令行参数--server-external-url或环境变量SERVER_EXTERNAL_URL设置，其帮助文本明确说明："External URL of the server. Should be set if the server is behind a reverse proxy."（当服务器位于反向代理后时应设置）。

此外，start.py 还提供了--trusted-hosts参数作为反向代理场景的补充：用于放行X-Forwarded-Host头；未设置时由--server-external-url推导，两者都未设置时默认"*"（仅在服务器只能通过可信代理访问时才建议如此）。

创建 DigitalOcean 集群

完整步骤可参考 创建 DigitalOcean 集群，核心流程如下。

第一步：创建云凭证（Cloud Credential）

在 GPUStack 的Cloud Credentials页面创建一个 DigitalOcean 云凭证，填入上一步生成的 PAT。凭证模型定义在 schemas/clusters.py 中，每个凭证归属于一个组织（Org），key与secret分别用于调用云厂商 API。

从工厂注册代码（cloud_providers/common.py）可以看到，DigitalOcean 凭证使用credential.secret（即 PAT）作为 token 构造DigitalOceanClient，认证方式为在请求头注入Authorization: Bearer <token>（见 digital_ocean.py）。

第二步：创建集群并选择云提供商

进入集群创建页面，在Cloud Provider中选择DigitalOcean：

然后填写Name（必填）、选择刚创建的云凭证，并选择一个支持 GPU Droplet 的区域：

在此步骤中还需配置GPUStack Server URL，即新创建的 droplet 可访问的 GPUStack Server 地址——这正是准备阶段--server-external-url所配置的地址。点击Next进入 Worker Pool 创建环节。

第三步：创建 Worker Pool

Worker Pool 是云端 worker 的批量定义。需要填写以下字段：

• Name—— 池名称；
• Replicas—— 期望的 worker 数量（即 droplet 数量）；
• Batch Size—— 批量创建的上限，控制并发开通数量，避免一次性创建过多 droplet 触发限流；
• Instance Type—— DigitalOcean 术语中的 droplet size（实例规格），选择包含 GPU 的规格：

接着选择OS Image：

Worker Pool 的数据结构定义在 schemas/clusters.py，除上述字段外还支持Labels与Volumes。Replicas允许为 0（ge=0），用于先定义池、后续再扩容。

支持的操作系统镜像与驱动引导

目前仅支持Nvidia 系列 GPU Droplet（AMD GPU Droplet 经常不可用），且只支持Debian 系操作系统。分两种情况：

• Nvidia AI/ML Ready（推荐）：基于 Ubuntu 22.04，已预装驱动、CUDA 与 container-toolkit，无需额外安装任何软件包；
• Debian 发行版：通过 cloud-init 引导安装nvidia-open驱动、CUDA 12.8 与 nvidia-container-toolkit 1.17.8-1；
• Ubuntu 发行版：通过 cloud-init 引导安装nvidia-driver-570驱动、CUDA 12.8 与 nvidia-container-toolkit 1.17.8-1。

这些版本的判断逻辑与安装命令可在 cloud_providers/user_data.py 中看到：镜像 slug 以gpu开头视为 AI/ML Ready 镜像（此时只做驱动 setup，不重新安装）；否则若发行版为debian/ubuntu，则走install_driver路径——追加build-essential、dkms、linux-headers-generic、curl等包，通过 NVIDIA 官方 CUDA 仓库与nvidia-container-toolkit仓库安装指定版本驱动与工具，并注册 DKMS 自动编译服务。驱动安装完成后会触发一次重启（power_state: reboot），重启后由post-reboot.service拉起 worker 容器。

Labels 与 Volumes

Worker Pool 支持设置Labels和Volumes来定制 worker 的形态：

• Labels会以key:value形式作为 droplet 的 tags 传入 DigitalOcean 创建请求，同时 GPUStack 侧也保留cluster_id、worker_id等内部标签（见 digital_ocean.py 与 common.py）；
• Volumes会创建 DigitalOcean Block Storage 卷并挂载到 droplet。卷的校验逻辑在 digital_ocean.py：size_gb必须大于 0，format仅支持ext4与xfs，卷名最长 60 字符（源码会追加 worker id 以保证唯一性，见 schemas/clusters.py）。

重要提醒：为 droplet 创建并挂载的卷不会自动挂载进 worker 容器。如有需要，可以修改 droplet 内的/opt/gpustack-run-worker.sh脚本（该脚本由 cloud-init 生成，负责docker run拉起 worker 容器，见 user_data.py），在docker run命令中追加-v参数以按需挂载卷。

全部配置完成后点击Save保存集群。

等待 Worker 完成供给（Provisioning）

保存集群后，前往Workers页面即可看到 DigitalOcean worker 的供给进度。

整个供给过程包含以下步骤：

1. 创建 SSH 密钥：GPUStack 生成密钥对，并通过 DigitalOceanssh_keysAPI 注册公钥（默认 ED25519 算法，见 common.py），worker 记录其external_id；
2. 携带 SSH 密钥创建 droplet：调用droplets.create，请求体包含 name、image、size、region、ssh_keys、user_data 与 tags（见 digital_ocean.py）；
3. 等待 droplet 启动：轮询 droplet 状态直至active；
4. 等待分配公网 IP：从 droplet 网络信息中解析类型为public的 IPv4 地址；
5. 创建卷并挂载到 droplet（若 Worker Pool 配置了 Volumes）；
6. worker 进入Initialized状态：等待 worker 容器启动并连接 Server。

供给过程中 worker 的状态机在 server/controllers.py 中定义：PENDING（池创建的初始状态）→PROVISIONING（开始供给）→PROVISIONED（供给完成，等待注册）→ 注册后变为Ready，异常则进入ERROR。供给的并发受Batch Size约束——控制器仅在"正在供给的 worker 数量小于 batch_size"时才继续创建新实例（见 controllers.py）。

值得留意的是，cloud-init 的runcmd中会通过 DigitalOcean 元数据服务（169.254.169.254）写入两份关键文件（见 digital_ocean.py）：

• /var/lib/gpustack/external_id—— droplet 的 ID，用于 GPUStack 关联云实例与 worker；
• /var/lib/gpustack/advertise_address—— droplet 的公网 IP，作为 worker 的对外宣告地址。

当 worker 达到Ready状态后，就可以在其上部署模型了：

安全缩容 DigitalOcean Worker

当一个 DigitalOcean worker 不再需要时，请按以下顺序安全销毁对应的 droplet：

1. 调整 Worker Pool 的副本数：将Replicas调整为希望保留的 worker 数量。注意：这一步不会自动删除任何 worker，只是停止继续供给新的 droplet；
2. 确认待删除的 worker 上没有部署模型实例：Worker Pool 的运维入口位于Clusters页，可直接在 worker 列修改副本数，或通过Edit按钮调整Name、Replica、Batch Size与Labels（见 cluster-management.md）；
3. 按需删除 worker：删除后，对应的 droplet 会被一并销毁。销毁走的是destroy_with_associated_resources_dangerous接口（见 digital_ocean.py），这会连带清理 droplet 的关联资源——这也是前文强调 PAT 必须具有 Full Access 权限的原因。

补充：Worker 与 Server 的连接模式

DigitalOcean worker 部署在公网，GPUStack Server 需要通过网络回连到这些 worker 才能转发推理请求。连接模式由 worker 的proxy_mode选项控制（可在集群的 Worker Configuration YAML 中预设），共三种：

• direct—— Server 与网关直连 worker 的宣告地址与端口，开销最低，但要求 worker 对 Server 直接可达；
• worker—— 请求经由 worker 内置的 HTTP 反向代理转发到本地推理进程，Server 仍需可达 worker，但只需暴露 worker 端口；
• tunnel—— worker 只建立一条出站WebSocket 连接到 Server，Server 仅通过该隧道访问 worker，适用于 worker 无法接受 Server 入站连接的场景（如防火墙或 NAT 之后）。

默认情况下，Server 内嵌 worker 使用direct，独立 worker 使用worker。对于公网 droplet 场景，通常可以直接使用默认模式；若你的网络环境特殊，可在 Worker Configuration YAML 中设置为tunnel。DigitalOcean worker 通过--server-external-url配置的地址回连 Server，因此请确保该地址从 droplet 所在网络可达。

总结

通过 GPUStack 的 DigitalOcean 云提供商支持，你可以：

• 用 PAT 建立云凭证，选择 GPU 区域与实例规格，以 Worker Pool 方式批量开通 GPU droplet；
• 依赖 cloud-init 自动完成驱动、CUDA、container-toolkit 的安装与 worker 容器拉起，实现"开机即就绪"；
• 借助 Labels 与 Volumes 定制节点形态，并在 droplet 内修改/opt/gpustack-run-worker.sh实现卷的按需挂载；
• 通过调整副本数与删除 worker 的方式安全缩容，避免残留计费资源。

需要深入了解的读者，可继续阅读 cluster-management.md 中关于 Worker Pool 运维、Worker Configuration YAML 与连接模式的完整说明，或直接研读 cloud_providers/digital_ocean.py 与 cloud_providers/user_data.py 的源码实现。

• 后端
• 人工智能
• 模型推理服务
• 集群管理
• 可观测性