Linux 部署指南

环境要求

OS：Ubuntu 22.04 / 24.04（推荐）或 CentOS 8+
Python：3.11
PostgreSQL：16+（外部实例或自建）
uv：Python 包管理器

一、安装依赖

# 系统依赖
apt-get update && apt-get install -y \
    python3.11 python3.11-venv python3.11-dev \
    build-essential libssl-dev libffi-dev \
    libpq-dev git curl

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

二、准备代码

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

三、创建虚拟环境并安装依赖

cd /opt/gpustack
uv venv .venv --python 3.11
source .venv/bin/activate
uv pip install -e .

四、准备数据库

使用已有 PostgreSQL 实例，确保数据库和用户已创建并授权：

CREATE USER gpustack WITH PASSWORD 'your_password';
CREATE DATABASE gpustack OWNER gpustack;
GRANT ALL ON SCHEMA public TO gpustack;
GRANT ALL PRIVILEGES ON DATABASE gpustack TO gpustack;

五、准备前端 UI

将前端构建产物放到 /opt/gpustack/gpustack/ui/：

# 在前端项目目录执行构建
cd /path/to/maas-base-ui
npm install && npm run build

# 将 dist 目录复制为 ui 目录
cp -r dist /opt/gpustack/gpustack/ui

六、启动服务

开发/测试模式（禁用 Gateway，直接暴露 API）

cd /opt/gpustack
source .venv/bin/activate

gpustack start \
  --database-url "postgresql://gpustack:your_password@db_host:5432/gpustack" \
  --gateway-mode disabled \
  --api-port 80 \
  --debug

生产模式（含 Higress Gateway，推荐 Docker）

见下方 Docker 部署。

七、Docker 部署（生产推荐）

项目提供了完整的 Docker 镜像，内置 PostgreSQL、Higress、Prometheus、Grafana。

使用外部 PostgreSQL

docker run -d \
  --name gpustack \
  --restart unless-stopped \
  -p 80:80 \
  -v gpustack-data:/var/lib/gpustack \
  -e GPUSTACK_DATABASE_URL="postgresql://gpustack:your_password@db_host:5432/gpustack" \
  gpustack/gpustack:latest

使用内置 PostgreSQL

docker run -d \
  --name gpustack \
  --restart unless-stopped \
  -p 80:80 \
  -v gpustack-data:/var/lib/gpustack \
  gpustack/gpustack:latest

查看初始管理员密码

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

八、Systemd 服务（裸机部署）

创建 /etc/systemd/system/gpustack.service：

[Unit]
Description=GPUStack Server
After=network.target postgresql.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/gpustack
Environment="PATH=/opt/gpustack/.venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/opt/gpustack/.venv/bin/gpustack start \
    --database-url postgresql://gpustack:your_password@db_host:5432/gpustack \
    --gateway-mode disabled \
    --api-port 80
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable gpustack
systemctl start gpustack
systemctl status gpustack

九、常用参数说明

参数	说明	默认值
`--database-url`	PostgreSQL 连接 URL	内置 SQLite
`--gateway-mode`	Gateway 模式：`embedded`/`disabled`	`auto`
`--api-port`	API 服务端口	`30080`
`--port`	Gateway 对外端口（embedded 模式）	`80`
`--debug`	开启调试日志	`false`
`--data-dir`	数据目录	`~/.local/share/gpustack`
`--bootstrap-password`	初始管理员密码	随机生成

十、验证部署

# 检查 API 是否正常
curl http://localhost:80/v2/users/me

# 查看 API 文档
open http://localhost:80/docs

注意事项

80 端口权限：Linux 下监听 1024 以下端口需要 root 权限，或使用 setcap：
```
setcap 'cap_net_bind_service=+ep' /opt/gpustack/.venv/bin/python3.11
```
Gateway 模式：embedded 模式需要 Higress 组件（仅 Docker 镜像内置），裸机部署建议使用 --gateway-mode disabled，通过 Nginx 反向代理到 api-port。

Nginx 反向代理示例：

server {
   listen 80;
   location / {
       proxy_pass http://127.0.0.1:30080;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_read_timeout 300s;
   }
}

deployment-linux.md 4.4 KB Historie Surový