# Proxmox VE LXC 部署(iGPU 透传)

推荐路径:PVE host → privileged LXC 容器 → 容器内 docker → 云瞰镜像。**不要直接在 PVE host 上装 docker**(Proxmox 官方不推荐,会和 PVE 的 iptables / apt 冲突)。LXC 是 namespace 隔离,性能损耗近零,/dev/dri 透传体验和 host 跑 docker 几乎一致。

## 1. 适用机型 & 推荐变体

| 机型 | 推荐变体 | iGPU 状态 |
| --- | --- | --- |
| N100 / N305 / N355 mini PC | openvino | Alder Lake-N 核显,/dev/renderD128 可用 |
| J4125 / J4105 老 NUC | openvino | Apollo Lake 核显,/dev/renderD128 可用 |
| i3-i7 11 代+ + Iris Xe | openvino | 性价比首选 |
| NVIDIA GPU PVE 主机 | cuda 或 trt | 需 PVE host 装 NVIDIA 驱动 + LXC 透传 /dev/nvidia* |

## 2. 准备工作(在 PVE host 上)

1. **确认 host 有 /dev/dri**

   PVE shell 跑 `ls -la /dev/dri/`,应有 card0/card1 + renderD128;否则 PVE 内核没加载 i915,先 `modprobe i915`

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. **查 render/video 组的 GID**

   PVE shell 跑 `getent group render` 和 `getent group video`,记下 GID(默认 render=104, video=44),后面 pct set 要用

## 3. 建 LXC 容器

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

> **⚠️ 必须 privileged + nesting=1 + keyctl=1**
>
> `--unprivileged 0` = privileged LXC,这是家用最简选择(unprivileged 跑 docker 需要 90+ 行 lxc.conf 调优)。`nesting=1` 让容器内能再跑 docker,`keyctl=1` 让 docker overlayfs 工作。

## 4. 透传 iGPU 给 LXC

```bash
# 在 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 + 跑云瞰

```bash
# 进 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 向导](/docs/quickstart)。

## 6. 升级

升级在 LXC 内操作(`pct enter 101` 进容器),和普通 Linux 裸机完全一样,没有 LXC 专属步骤。走哪条路取决于装的时候 yunkan-updater 有没有就绪:`docker ps` 看到 `yunkan` + `yunkan-updater` 两个容器 = 走方式 A;只有 `yunkan` 一个 = 走方式 B 或 C。

### 方式 A:网页一键升级(推荐)

用一键脚本部署且 updater 镜像拉取成功时默认可用。打开 Web Admin → 设置 → 系统升级,点升级即可。yunkan-updater sidecar 会自动 `docker pull` 新镜像并重建主容器,新版起不来还会自动回滚到上一版,全程不用登命令行。LXC 内 docker socket 正常,这条路完全可用。

### 方式 B:命令行升级

没装 updater,或想手动锁定版本时用。进 LXC 后到部署目录(默认 `~/skyview`)执行:

```bash
pct enter 101
cd ~/skyview

# 升到当前 tag(默认 latest)的最新镜像并重建
docker compose -p yunkan -f compose.all-in-one.yml up -d --pull always
```

要锁定到指定版本,先改 compose 里的 image tag 再重建(注意保持变体不变,见下方警告):

```bash
cd ~/skyview
# 把 0.9.9 换成目标版本号
sed -i 's|image: .*/yunkan-.*|image: registry.cn-hangzhou.aliyuncs.com/yunkan/yunkan-openvino:0.9.9|' compose.all-in-one.yml
docker compose -p yunkan -f compose.all-in-one.yml up -d --pull always --force-recreate
```

> **⚠️ 升级时别换错变体**
>
> image tag 里的变体(`openvino` / `cpu` / `cuda` / `trt`)必须和原来一致 —— LXC + iGPU 透传装的是 `openvino`,误填成 `cpu` 会丢硬件加速。不确定先 `docker ps` 看当前镜像名里是 `-openvino` 还是 `-cpu`。`data/` 与 `recordings/` 卷跨版本兼容,DB 迁移由新容器启动时自动跑,升级不丢数据。

### 方式 C:重跑安装脚本

一键脚本是幂等的,重跑会重新拉镜像(含 updater)、重新生成 compose、重建容器。最适合当初没装 updater、想补上网页一键升级能力的场景:

```bash
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. 常见问题

> **ℹ️ /dev/dri 不出现在 LXC 里**
>
> 确认 pct set 命令正确(注意 gid 数字按你 host 实际查的);重启容器 `pct reboot 101`;再不行 `pct config 101 | grep dev` 看配置有没有写进去。

> **ℹ️ docker run 报 keyctl 错**
>
> 建容器时漏加 `--features keyctl=1`。可补:`pct set 101 --features nesting=1,keyctl=1`,然后 `pct reboot 101`。

> **💡 把所有 LXC 集中管理**
>
> PVE Web UI → Datacenter → 选 LXC 101 → 可视化看 CPU/内存/磁盘/网络;比直接登 host 跑 docker stats 友好。

---

来源:https://yun-kan.com/zh-CN/docs/install-pve-lxc