Worker 节点部署指南

本文档介绍如何部署 MaaS-Base Worker 节点，为平台提供 GPU 推理能力。

概述

Worker 是 MaaS-Base 的实际推理执行单元，负责：

检测 GPU 设备并上报资源信息
管理模型实例的生命周期（启动、停止、重启）
导出性能指标（GPU 利用率、显存、推理延迟等）
向 Server 发送心跳并同步状态

Worker 必须运行在 Linux 节点上，且该节点需配备 GPU/NPU 等加速器。Server 可以运行在无 GPU 的 CPU 节点上。

前置要求

要求	说明
操作系统	Linux（推荐 Ubuntu 20.04+ / Debian 12+）
加速器	NVIDIA GPU、AMD GPU、Ascend NPU、Hygon DCU、MThreads GPU、Iluvatar GPU、MetaX GPU、Cambricon MLU、T-Head PPU
驱动	已安装对应加速器厂商的驱动
Docker	20.10+
NVIDIA Container Toolkit	NVIDIA GPU 必需，安装指南
网络连接	Worker 需能访问 Server 的 API 端口（默认 80）

GPU 驱动版本参考

厂商	驱动 / 工具包
NVIDIA	NVIDIA Driver + CUDA
AMD	ROCm
Ascend	CANN + Ascend Driver
Hygon	DTK + HyHal
MThreads	MThreads Driver
Iluvatar	CoreX
MetaX	MACA + MX Driver
Cambricon	Neuware + cnmon
T-Head	PPU SDK

方式一：Docker 直接部署 Worker

1. 在 Server 端获取注册令牌

# 如果 Server 是通过 Docker Compose 部署的
docker exec maas-base-server cat /var/lib/gpustack/registration_token

2. 在 Worker 节点上启动

docker run -d --name maas-base-worker \
    --restart unless-stopped \
    --privileged \
    --network host \
    --ipc host \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /var/run/cdi:/var/run/cdi \
    -v /var/lib/gpustack:/var/lib/gpustack \
    -e GPUSTACK_SERVER_URL=http://<SERVER_IP>:80 \
    -e GPUSTACK_RUNTIME_DEPLOY=Docker \
    -e GPUSTACK_RUNTIME_DEPLOY_MIRRORED_DEPLOYMENT=true \
    -v /var/lib/kubelet/device-plugins:/var/lib/kubelet/device-plugins \
    gpustack/gpustack:latest \
    gpustack start \
    --gateway-mode disabled \
    --worker

参数说明：

--privileged：允许 Worker 访问 GPU 设备

--network host：使用宿主机网络，简化端口管理

--ipc host：共享 IPC 命名空间，某些推理引擎需要

-v /var/run/docker.sock:/var/run/docker.sock：让 Worker 能调度模型容器

--gateway-mode disabled：Worker 不启动网关，仅做推理

--worker：以 Worker 模式运行

3. 验证部署

# 查看 Worker 日志
docker logs -f maas-base-worker

# 在 Server UI 中查看节点是否上线
# 访问 http://<SERVER_IP> -> Clusters 页面

方式二：Server 与 Worker 合一（嵌入式模式）

如果单机部署且节点本身有 GPU，可以直接在 Server 容器中启用 Worker 模式：

docker run -d --name maas-base \
    --restart unless-stopped \
    --privileged \
    --network host \
    --ipc host \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /var/run/cdi:/var/run/cdi \
    -v maas-base-data:/var/lib/maas-base \
    -v /var/lib/kubelet/device-plugins:/var/lib/kubelet/device-plugins \
    -e NVIDIA_VISIBLE_DEVICES=all \
    -e NVIDIA_DRIVER_CAPABILITIES=compute,utility \
    maas-base/maas-base \
    gpustack start \
    --gateway-mode disabled \
    --api-port 80

该模式下，同一个容器既作为 Server 也作为 Worker，适合单 GPU 节点的快速部署。

方式三：通过 Docker Compose 附加 Worker

可在 docker-compose 文件中追加 Worker 服务：

  maas-base-worker:
    image: gpustack/gpustack:latest
    container_name: maas-base-worker
    restart: unless-stopped
    privileged: true
    network_mode: host
    ipc: host
    environment:
      GPUSTACK_SERVER_URL: http://<SERVER_IP>:80
      GPUSTACK_RUNTIME_DEPLOY: "Docker"
      GPUSTACK_RUNTIME_DEPLOY_MIRRORED_DEPLOYMENT: "true"
      # NVIDIA GPU 环境变量
      NVIDIA_VISIBLE_DEVICES: all
      NVIDIA_DRIVER_CAPABILITIES: compute,utility
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/run/cdi:/var/run/cdi
      - /var/lib/gpustack:/var/lib/gpustack
      - /var/lib/kubelet/device-plugins:/var/lib/kubelet/device-plugins
    command: ["gpustack", "start", "--gateway-mode", "disabled", "--worker"]

方式四：通过 Kubernetes (Helm) 部署 Worker

在 Kubernetes 环境中，Worker 以 DaemonSet 形式自动部署到每个 GPU 节点。

helm install -n gpustack-system gpustack ./gpustack --create-namespace \
  --set worker.enabled=true \
  --set worker.gpuVendor=nvidia

支持的 GPU 厂商配置：

`worker.gpuVendor`	适用硬件
`nvidia`	NVIDIA GPU
`amd`	AMD GPU (ROCm)
`ascend`	Huawei Ascend NPU
`hygon`	Hygon DCU
`mthreads`	Moore Threads GPU
`iluvatar`	Iluvatar GPU
`metax`	MetaX GPU
`cambricon`	Cambricon MLU
`thead`	T-Head PPU
`null`	CPU-only（无 GPU 推理）

详细说明请参见 Kubernetes (Helm) 部署指南。

环境变量参考

Worker 容器支持以下环境变量：

变量	说明	默认值
`GPUSTACK_SERVER_URL`	Server API 地址（必填）	-
`GPUSTACK_WORKER_NAME`	Worker 名称	主机名
`GPUSTACK_WORKER_IP`	Worker IP 地址	自动检测
`GPUSTACK_RUNTIME_DEPLOY`	部署模式（`Docker` / `Kubernetes`）	自动检测
`GPUSTACK_RUNTIME_DEPLOY_MIRRORED_DEPLOYMENT`	启用镜像部署模式	`true`

GPU 厂商环境变量

厂商	环境变量	说明
NVIDIA	`NVIDIA_VISIBLE_DEVICES`	可见 GPU 设备，`all` 表示全部
NVIDIA	`NVIDIA_DRIVER_CAPABILITIES`	驱动能力，推荐 `compute,utility`
NVIDIA	`NVIDIA_DISABLE_REQUIRE`	不强制要求特定 runtime
AMD	`AMD_VISIBLE_DEVICES`	AMD GPU 设备，`all` 表示全部
Ascend	`ASCEND_HOME_PATH`	Ascend 工具包路径
Hygon	`ROCM_PATH` / `ROCM_SMI_LIB_PATH`	Hygon 驱动路径
Iluvatar	`COREX_HOME`	CoreX 工具包路径
MThreads	`MTHREADS_VISIBLE_DEVICES`	MThreads GPU 设备
Cambricon	`CAMBRICON_VISIBLE_DEVICES`	Cambricon MLU 设备
T-Head	`PPU_HOME`	PPU SDK 路径
MetaX	`LD_LIBRARY_PATH`	需包含 MACA 和 MX 驱动库路径

多 Worker 部署

平台支持多个 Worker 节点同时接入 Server，Server 会自动调度和负载均衡：

                    ┌──────────┐
   ┌───────────────▶│ Worker 1 │ (GPU Node A)
   │                └──────────┘
┌──────────┐        ┌──────────┐
│  Server  ├────────▶ Worker 2 │ (GPU Node B)
└──────────┘        └──────────┘
   │                ┌──────────┐
   └───────────────▶│ Worker 3 │ (GPU Node C)
                    └──────────┘

只需在每个 Worker 节点上执行相同的部署命令，使用相同的 GPUSTACK_SERVER_URL 和注册令牌即可。

常见问题

1. Worker 注册失败

Error: Worker not registered with server

检查 GPUSTACK_SERVER_URL 是否正确
检查 Worker 能否访问 Server 的网络（curl http://<SERVER_IP>:80）
确认注册令牌有效

2. 无法检测到 GPU

No GPU devices detected

确认驱动已正确安装（nvidia-smi / rocm-smi / npu-smi 等）
确认使用了 --privileged 参数
NVIDIA 用户确认 nvidia-container-toolkit 已安装
尝试添加 -v /dev:/dev:ro 卷挂载

3. 模型推理失败

Error: CUDA out of memory

检查 GPU 显存是否充足（通过 Grafana 或 nvidia-smi 查看）
在 Server UI 中调整模型的资源配置
减少并发请求或选择更小的模型

4. Worker 频繁离线

检查网络稳定性
调整 Worker 心跳间隔（通过 GPUSTACK_WORKER_HEARTBEAT_INTERVAL 环境变量）
检查 Docker 资源限制（CPU、内存）

下一步

在 Server UI 中部署模型 → 快速开始
使用 Kubernetes 进行大规模部署 → Kubernetes (Helm) 部署指南

worker.md 8.4 KB Historia Czysty