基于源码的 Docker 部署指南

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

一、构建镜像

环境要求

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

1. 克隆代码

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

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

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. 构建镜像

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

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

也可以直接用 docker buildx：

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 目录

cd /opt/gpustack-src/docker-compose

2. 创建 `.env` 文件

cat > .env <<EOF
POSTGRES_PASSWORD=your_strong_password
EOF

3. 启动 Server

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

4. 查看初始管理员密码

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

5. 获取 Worker 注册 Token

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

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

6. 访问

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

三、部署 Worker

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

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

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

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 容器

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）

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`	-

五、常用运维命令

# 查看 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

六、注意事项

构建需要访问 GitHub：Higress、s6-overlay 等组件从 GitHub 下载，网络不通时需配置代理：
```
export HTTPS_PROXY=http://your-proxy:port
```
磁盘空间：构建过程需要约 20GB 空间（含构建缓存）。

NVIDIA GPU 支持：需提前安装 NVIDIA Container Toolkit，Worker 启动时添加：

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>

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

deployment-from-source-docker.md 4.7 KB 文件历史 原始文件