# 基于源码的 Docker 部署指南

Higress 已内置于 Docker 镜像中（通过 s6-overlay 管理），无需单独部署。

---

## 一、构建镜像

### 环境要求

- Linux（x86_64 或 arm64）
- Docker 24.0+，启用 BuildKit
- Git

### 1. 克隆代码

```bash
git clone <your-repo-url> /opt/gpustack-src
cd /opt/gpustack-src
```

### 2. 初始化 buildx（首次执行）

```bash
docker run --rm --privileged tonistiigi/binfmt:qemu-v9.2.2-52 --install all
docker buildx create \
    --name gpustack \
    --driver docker-container \
    --driver-opt "network=host,default-load=true" \
    --bootstrap
```

### 3. 构建镜像

```bash
# 使用项目脚本构建（推荐）
PACKAGE_TAG=my-build PACKAGE_PUSH=false bash hack/package.sh
```

构建完成后镜像名为 `gpustack/gpustack:my-build`。

也可以直接用 docker buildx：

```bash
docker buildx build \
    --builder gpustack \
    --platform linux/amd64 \
    --tag gpustack/gpustack:my-build \
    --file pack/Dockerfile \
    --ulimit nofile=65536:65536 \
    --shm-size 16G \
    --load \
    .
```

> 构建时间较长（30~60 分钟），会下载 Higress、Prometheus、Grafana 等组件。

---

## 二、部署 Server

Server 负责 API、调度、数据库、Gateway，是集群的控制节点。

### 1. 进入 docker-compose 目录

```bash
cd /opt/gpustack-src/docker-compose
```

### 2. 创建 `.env` 文件

```bash
cat > .env <<EOF
POSTGRES_PASSWORD=your_strong_password
EOF
```

### 3. 启动 Server

```bash
docker compose -f docker-compose.server.yaml up -d --build
```

### 4. 查看初始管理员密码

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

### 5. 获取 Worker 注册 Token

Worker 节点加入集群时需要此 Token：

```bash
docker exec gpustack-server cat /var/lib/gpustack/token
```

### 6. 访问

浏览器打开 `http://<Server-IP>`，使用 `admin` 和初始密码登录。

---

## 三、部署 Worker

Worker 负责运行模型推理实例，可部署在多台 GPU 机器上。

> 前提：Server 已启动并可访问。

### 1. 在 Worker 机器上克隆代码并构建镜像

```bash
git clone <your-repo-url> /opt/gpustack-src
cd /opt/gpustack-src

PACKAGE_TAG=my-build PACKAGE_PUSH=false bash hack/package.sh
```

### 2. 启动 Worker 容器

```bash
docker run -d \
    --name gpustack-worker \
    --restart unless-stopped \
    --ulimit nofile=65535:65535 \
    -v gpustack-worker-data:/var/lib/gpustack \
    gpustack/gpustack:my-build \
    --server-url http://<Server-IP> \
    --token <上一步获取的Token>
```

### 3. 验证 Worker 注册

在 Server 的 Web UI 中查看 Workers 页面，确认新 Worker 已上线。

---

## 四、含监控部署（Prometheus + Grafana）

```bash
cat > .env <<EOF
POSTGRES_PASSWORD=your_strong_password
GRAFANA_PASSWORD=your_grafana_password
GPUSTACK_GRAFANA_URL=http://<Server-IP>:3000
EOF

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

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

---

## 五、常用运维命令

```bash
# 查看 Server 日志
docker logs -f gpustack-server

# 查看 Worker 日志
docker logs -f gpustack-worker

# 重启 Server
docker compose -f docker-compose.server.yaml restart gpustack-server

# 重启 Worker
docker restart gpustack-worker

# 重新构建并更新 Server
PACKAGE_TAG=new-build bash hack/package.sh
docker compose -f docker-compose.server.yaml up -d --build

# 重新构建并更新 Worker
PACKAGE_TAG=new-build bash hack/package.sh
docker rm -f gpustack-worker
docker run -d --name gpustack-worker ... # 同上启动命令

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

---

## 六、注意事项

1. **构建需要访问 GitHub**：Higress、s6-overlay 等组件从 GitHub 下载，网络不通时需配置代理：
   ```bash
   export HTTPS_PROXY=http://your-proxy:port
   ```

2. **磁盘空间**：构建过程需要约 20GB 空间（含构建缓存）。

3. **NVIDIA GPU 支持**：需提前安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)，Worker 启动时添加：
   ```bash
   docker run -d \
       --name gpustack-worker \
       --restart unless-stopped \
       --gpus all \
       --ulimit nofile=65535:65535 \
       -v gpustack-worker-data:/var/lib/gpustack \
       gpustack/gpustack:my-build \
       --server-url http://<Server-IP> \
       --token <Token>
   ```

4. **端口占用**：确保 Server 机器的 80 端口未被占用，Worker 机器的 40000-40063 端口（推理服务端口）未被占用。