Proxmox VE LXC 部署(iGPU 透傳)

1. 適用機型 & 推薦變體

2. 準備工作(在 PVE host 上)

1. 1

   確認 host 有 /dev/dri

   PVE shell 執行 ls -la /dev/dri/,應該要看到 card0/card1 + renderD128;如果沒有,代表 PVE 核心沒有載入 i915,先執行 modprobe i915

2. 2

   下載 Debian 12 範本

   PVE Web UI → local → CT Templates → 按 Templates 按鈕 → 找到 debian-12-standard 下載(或執行 pveam download local debian-12-standard_12.x_amd64.tar.zst)

3. 3

   查詢 render/video 群組的 GID

   PVE shell 執行 getent group render 和 getent group video,記下 GID(預設 render=104,video=44),後面 pct set 指令會用到

3. 建立 LXC 容器

# 在 PVE host shell:建立一個 vmid=101 的容器,4 核心 4G 記憶體 40G 硬碟
pct create 101 local:vztmpl/debian-12-standard_12.12-1_amd64.tar.zst \
  --hostname yunkan \
  --cores 4 --memory 4096 --swap 1024 \
  --rootfs local-lvm:40 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp,firewall=0 \
  --unprivileged 0 \
  --features nesting=1,keyctl=1 \
  --onboot 1

pct start 101

4. 把 iGPU 透傳給 LXC

# 在 PVE host:把 renderD128 和 card1 透傳給 vmid=101
pct set 101 -dev0 /dev/dri/renderD128,gid=104   # render group
pct set 101 -dev1 /dev/dri/card1,gid=44         # video group

# 重新啟動容器讓 dev 透傳生效
pct reboot 101

# 驗證:進入容器查看 /dev/dri 是否存在
pct exec 101 -- ls -la /dev/dri/

5. 在 LXC 內安裝 docker + 執行雲瞰

# 進入 LXC
pct enter 101

# 安裝 docker
curl -fsSL https://get.docker.com | sh

# 執行雲瞰一鍵腳本(會自動選擇 openvino 變體,因為偵測到 /dev/dri)
curl -fsSL https://cdn.yun-kan.com/yunkan-install.sh | bash

腳本執行完後會給出一個 LXC IP + 連接埠(例如 http://10.0.0.148:23406/)。從同一網段的任何機器用瀏覽器開啟,即可進入 Setup 精靈。

6. 升級

升級在 LXC 內操作(pct enter 101 進容器),和普通 Linux 裸機完全一樣,沒有 LXC 專屬步驟。首選方式 A(網頁後台一鍵升級,免登命令列);想手動鎖定版本或偏好命令列時用方式 B / C。

方式 A:網頁一鍵升級(推薦)

打開 Web Admin → 設定 → 系統升級,點升級即可。系統會自動拉取新映像檔並重建主容器(升級瞬間會臨時出現一個一次性執行容器,完成後自動消失),新版起不來還會自動回滾到上一版,全程不用登命令列。LXC 內 docker socket 正常,這條路完全可用。

方式 B:命令列升級

想手動控制升級時機、鎖定特定版本時用。進 LXC 後到部署目錄(預設 ~/skyview)執行:

pct enter 101
cd ~/skyview

# 升級到目前 tag(預設 latest)的最新映像檔並重建
docker compose -p yunkan -f compose.yml up -d --pull always

要鎖定到指定版本,先修改 compose 裡的 image tag 再重建(注意要保持變體不變,見下方警告):

cd ~/skyview
# 把 0.9.9 換成目標版本號
sed -i 's|image: .*/yunkan-.*|image: registry.cn-hangzhou.aliyuncs.com/yunkan/yunkan-openvino:0.9.9|' compose.yml
docker compose -p yunkan -f compose.yml up -d --pull always --force-recreate

方式 C:重新執行安裝腳本

一鍵腳本是冪等的,重跑會重新拉映像檔、重新產生 compose、重建容器。適合想把老裝機刷成最新標準佈局(順帶清理舊版 yunkan-updater 升級容器)的場景:

pct enter 101
curl -fsSL https://cdn.yun-kan.com/yunkan-install.sh | bash

7. 備份 / 還原

• LXC 快照:升級前執行 pct snapshot 101 pre-upgrade-$(date +%Y%m%d),出問題時 pct rollback 101 <快照名> 就能秒回滾整個容器
• LXC 備份:vzdump 101 --storage local 把整個容器(含 docker volume)走 PVE 標準備份流程;或用 Web UI → 選 101 → Backup
• 還原:pct restore <新 vmid> <備份檔案> 從備份還原
• 不要用 destroy + create 重建:LXC 重建會讓 /etc/machine-id 改變,license 指紋漂移 → 佔用新的 slot 陷入死循環。要重設一律走 pct restore 從備份還原,不要新建容器

8. 常見問題