# 部署

本頁說明以 Release 執行檔或 systemd 常駐執行 go-pve-qemu 時，工作目錄需要具備哪些檔案。

## 工作目錄需求

服務所有相對路徑都以啟動時的工作目錄為基準：

| 路徑 | 用途 | 缺少時 |
|---|---|---|
| `.env` | 環境變數 | 僅警告，改讀行程環境變數 |
| `sh/` | 以 `/sh/*` 對外提供 OS 初始化腳本 | 新 VM 下載腳本失敗，SSH 初始化階段中止並清除 VM |
| `.go_qemu_disabled` | 停用清單 | VM 清單與狀態檢查全部失敗 |
| `.go_qemu_pubkey_admin` | 額外注入的管理者公鑰 | 略過 |
| `.go_qemu_cpu_type` | CPU 類型快取 | 首次建立 VM 時自動產生 |

新 VM 透過 `http://<NODE_{MAIN_NODE}>:<PORT>/sh/<os>_<version>.sh` 下載腳本，因此 VM 網段必須能連到主節點的 `PORT`。

## Release 執行檔

推送 `v*` tag 時，GitHub Actions 在 `ubuntu-latest` 以 Go 1.25 執行 `go build -o app ./cmd/api`，並將 `app` 打包為 `go-pve-qemu@<tag>.tar.gz` 附加到該 Release。

```bash
git clone https://github.com/pardnchiu/go-pve-qemu.git /opt/go-pve-qemu
cd /opt/go-pve-qemu
curl -fsSL -o release.tar.gz \
  "https://github.com/pardnchiu/go-pve-qemu/releases/download/<tag>/go-pve-qemu@<tag>.tar.gz"
tar -xzf release.tar.gz
cp .env.example .env
touch .go_qemu_disabled
./app
```

clone 是為了取得 `sh/` 腳本與 `.env.example`；執行檔本身不內嵌這些檔案。

## systemd 常駐

```ini
[Unit]
Description=go-pve-qemu API
After=network-online.target

[Service]
User=root
WorkingDirectory=/opt/go-pve-qemu
ExecStart=/opt/go-pve-qemu/go-pve-qemu
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

```bash
systemctl daemon-reload
systemctl enable --now go-pve-qemu
journalctl -u go-pve-qemu -f
```

`WorkingDirectory` 必須指向含 `sh/` 與 `.env` 的目錄；`User=root` 是 `qm`／`pvesh` 與節點間 SSH 的前提。

## 升級

1. 取得新版執行檔（重新建置或下載新 Release）
2. `git pull` 更新 `sh/` 腳本
3. `systemctl restart go-pve-qemu`

節點硬體更換後刪除 `.go_qemu_cpu_type`，下次建立 VM 會重新偵測 [CPU 基準](/zh/cpu-baseline)。