# 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 必需，[安装指南](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) |
| 网络连接 | 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 端获取注册令牌

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

### 2. 在 Worker 节点上启动

```bash
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. 验证部署

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

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

---

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

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

```bash
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 服务：

```yaml
  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 节点。

```bash
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) 部署指南](./kubernetes.md)。

---

## 环境变量参考

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 中部署模型 → [快速开始](../README.md#快速开始)
- 使用 Kubernetes 进行大规模部署 → [Kubernetes (Helm) 部署指南](./kubernetes.md)