# Linux 部署指南

## 环境要求

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

---

## 一、安装依赖

```bash
# 系统依赖
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
```

---

## 二、准备代码

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

---

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

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

---

## 四、准备数据库

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

```sql
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/`：

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

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

---

## 六、启动服务

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

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

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

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

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

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

---

## 八、Systemd 服务（裸机部署）

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

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

```bash
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` | 初始管理员密码 | 随机生成 |

---

## 十、验证部署

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

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

---

## 注意事项

1. **80 端口权限**：Linux 下监听 1024 以下端口需要 root 权限，或使用 `setcap`：
   ```bash
   setcap 'cap_net_bind_service=+ep' /opt/gpustack/.venv/bin/python3.11
   ```

2. **Gateway 模式**：`embedded` 模式需要 Higress 组件（仅 Docker 镜像内置），裸机部署建议使用 `--gateway-mode disabled`，通过 Nginx 反向代理到 `api-port`。

3. **Nginx 反向代理示例**：
   ```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;
       }
   }
   ```