npx skills add https://github.com/bastos/skills --skill proxmox-adminProxmox VE 是一个基于 Debian 构建的服务器虚拟化平台。它通过 Web UI 或 CLI 工具管理 KVM 虚拟机和 LXC 容器。本技能涵盖使用 qm(虚拟机)、pct(容器)和支持工具进行基于 CLI 的管理。
不适用于: 仅使用 Web UI 的工作流(请使用下面列出的 CLI 等效工具)。
| 工具 | 用途 |
|---|---|
qm | 管理 KVM 虚拟机 |
pct | 管理 LXC 容器 |
pvesm | 管理存储 |
Proxmox VE is a server virtualization platform built on Debian. It manages KVM virtual machines and LXC containers through a web UI or CLI tools. This skill covers CLI-based administration using qm (VMs), pct (containers), and supporting utilities.
Not for: Web UI-only workflows (use the CLI equivalents below).
| Tool | Purpose |
|---|---|
qm | Manage KVM virtual machines |
pct |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
pvecm | 管理集群 |
pveam | 管理应用/模板下载 |
pvesh | 从 shell 访问 Proxmox API |
pveperf | 基准测试主机性能 |
qm 管理虚拟机# 创建 ID 为 100 的虚拟机
qm create 100 --name my-vm --memory 2048 --cores 2 --sockets 1 \
--net0 virtio,bridge=vmbr0 --ostype l26
# 在 local-lvm 存储上创建带 SCSI 磁盘的虚拟机(32GB)
qm create 100 --name my-vm --memory 4096 --cores 4 \
--scsi0 local-lvm:32 --scsihw virtio-scsi-pci \
--net0 virtio,bridge=vmbr0 --ostype l26
# 附加 ISO 以进行安装
qm set 100 --cdrom local:iso/ubuntu-22.04-server.iso --boot order=ide2
| 命令 | 用途 |
|---|---|
qm start <vmid> | 启动虚拟机 |
qm shutdown <vmid> | 优雅的 ACPI 关机 |
qm stop <vmid> | 强制停止(类似拔掉电源) |
qm reboot <vmid> | 重启虚拟机 |
qm reset <vmid> | 硬重置 |
qm suspend <vmid> | 挂起到 RAM |
qm resume <vmid> | 从挂起状态恢复 |
qm destroy <vmid> | 删除虚拟机及其磁盘 |
qm destroy <vmid> --purge | 删除虚拟机、磁盘及所有相关任务 |
# 显示当前配置
qm config 100
# 修改硬件
qm set 100 --memory 8192
qm set 100 --cores 4
qm set 100 --balloon 2048 # 动态内存(最小值)
qm set 100 --cpu cputype=host # 透传主机 CPU 特性
qm set 100 --machine q35 # 使用 Q35 芯片组(用于 PCIe 透传)
# 添加/调整磁盘大小
qm set 100 --scsi1 local-lvm:50 # 添加 50GB 磁盘
qm disk resize 100 scsi0 +20G # 将现有磁盘扩大 20GB
# 网络
qm set 100 --net0 virtio,bridge=vmbr0,tag=10 # VLAN 标记
qm set 100 --net1 virtio,bridge=vmbr1 # 第二个网卡
# Cloud-init(用于自动化配置)
qm set 100 --ide2 local-lvm:cloudinit
qm set 100 --ciuser admin --cipassword 'secret'
qm set 100 --ipconfig0 ip=10.0.0.50/24,gw=10.0.0.1
qm set 100 --sshkeys ~/.ssh/authorized_keys
qm set 100 --boot order=scsi0
# EFI / UEFI 引导
qm set 100 --bios ovmf --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=1
# 串行控制台(无头模式)
qm set 100 --serial0 socket --vga serial0
# PCI 透传(GPU、NIC 等)
qm set 100 --hostpci0 0000:01:00.0,pcie=1
# 创建快照
qm snapshot 100 before-upgrade --description "内核升级前"
# 列出快照
qm listsnapshot 100
# 回滚到快照
qm rollback 100 before-upgrade
# 删除快照
qm delsnapshot 100 before-upgrade
# 克隆虚拟机(完整复制)
qm clone 100 101 --name cloned-vm --full
# 克隆为链接克隆(共享基础磁盘,更快)
qm clone 100 101 --name linked-vm
# 将虚拟机转换为模板(不可逆)
qm template 100
# 从模板创建虚拟机(链接克隆)
qm clone 100 200 --name from-template
# 从模板创建虚拟机(完整克隆)
qm clone 100 200 --name from-template --full
# 在线迁移到另一个节点
qm migrate 100 node2 --online
# 离线迁移
qm migrate 100 node2
# 虚拟机状态
qm status 100
# 列出所有虚拟机
qm list
# 显示运行进程/代理信息
qm agent 100 ping
qm agent 100 get-osinfo
# 监控界面(QEMU 监控器)
qm monitor 100
pct 管理容器# 首先下载模板
pveam update
pveam available --section system
pveam download local debian-12-standard_12.2-1_amd64.tar.zst
# 创建 ID 为 200 的容器
pct create 200 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
--hostname my-ct --memory 1024 --cores 2 \
--rootfs local-lvm:8 \
--net0 name=eth0,bridge=vmbr0,ip=dhcp \
--password 'secret' --unprivileged 1
# 使用静态 IP 创建
pct create 201 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
--hostname web-ct --memory 2048 --cores 2 \
--rootfs local-lvm:16 \
--net0 name=eth0,bridge=vmbr0,ip=10.0.0.51/24,gw=10.0.0.1 \
--nameserver 1.1.1.1 --unprivileged 1
| 命令 | 用途 |
|---|---|
pct start <ctid> | 启动容器 |
pct shutdown <ctid> | 优雅关机 |
pct stop <ctid> | 强制停止 |
pct reboot <ctid> | 重启容器 |
pct destroy <ctid> | 删除容器及其卷 |
pct enter <ctid> | 在容器内打开 shell |
pct exec <ctid> -- <cmd> | 在容器内运行命令 |
pct console <ctid> | 附加到容器控制台 |
# 显示配置
pct config 200
# 修改资源
pct set 200 --memory 4096
pct set 200 --cores 4
pct set 200 --swap 1024
# 添加挂载点(从主机绑定挂载)
pct set 200 --mp0 /mnt/data,mp=/data
# 添加额外的存储卷
pct set 200 --mp1 local-lvm:50,mp=/var/lib/data
# 网络
pct set 200 --net0 name=eth0,bridge=vmbr0,ip=10.0.0.60/24,gw=10.0.0.1
pct set 200 --net1 name=eth1,bridge=vmbr1,ip=dhcp
# 特性(嵌套、FUSE、NFS)
pct set 200 --features nesting=1
pct set 200 --features nesting=1,fuse=1,mount=nfs
# DNS
pct set 200 --nameserver "1.1.1.1 8.8.8.8" --searchdomain example.com
# 开机启动
pct set 200 --onboot 1 --startup order=1,up=30
# 快照
pct snapshot 200 clean-install
# 回滚
pct rollback 200 clean-install
# 克隆
pct clone 200 201 --hostname cloned-ct --full
# 列出存储池
pvesm status
# 列出存储的内容
pvesm list local
pvesm list local-lvm
# 添加存储(示例)
pvesm add dir my-backup --path /mnt/backup --content backup
pvesm add nfs nfs-share --server 10.0.0.5 --export /exports/pve --content images,vztmpl
pvesm add lvm my-lvm --vgname my-vg --content rootdir,images
pvesm add zfspool my-zfs --pool rpool/data --content rootdir,images
# 移除存储
pvesm remove my-backup
# 下载 ISO
wget -P /var/lib/vz/template/iso/ https://example.com/image.iso
# 列出网络接口
cat /etc/network/interfaces
# 常见网桥配置(在 /etc/network/interfaces 中)
# auto vmbr0
# iface vmbr0 inet static
# address 10.0.0.1/24
# bridge-ports eno1
# bridge-stp off
# bridge-fd 0
# 应用网络更改
ifreload -a
# 创建新集群
pvecm create my-cluster
# 加入现有集群
pvecm add 10.0.0.1
# 显示集群状态
pvecm status
# 列出集群节点
pvecm nodes
# 移除节点(从剩余节点运行)
pvecm delnode nodename
# 检查仲裁
pvecm expected 1 # 强制仲裁(危险,仅用于单节点恢复)
# 在数据中心级别启用/禁用防火墙
pve-firewall start
pve-firewall stop
pve-firewall status
# 通过配置文件管理规则
# 数据中心:/etc/pve/firewall/cluster.fw
# 节点: /etc/pve/nodes/<node>/host.fw
# 虚拟机/容器: /etc/pve/firewall/<vmid>.fw
# 备份虚拟机
vzdump 100 --storage local --mode snapshot --compress zstd
# 备份容器
vzdump 200 --storage local --mode stop --compress zstd
# 备份所有客户机
vzdump --all --storage local --mode snapshot --compress zstd --mailto admin@example.com
# 恢复虚拟机
qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 100
# 恢复容器
pct restore 200 /var/lib/vz/dump/vzdump-lxc-200-*.tar.zst
# 恢复到不同的存储
qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 100 --storage local-lvm
# 1. 创建基础虚拟机并安装操作系统,然后转换为模板
qm template 9000
# 2. 克隆并使用 cloud-init 自定义
qm clone 9000 110 --name web-server --full
qm set 110 --ciuser deploy --sshkeys ~/.ssh/authorized_keys
qm set 110 --ipconfig0 ip=10.0.0.110/24,gw=10.0.0.1
qm set 110 --nameserver 1.1.1.1
qm start 110
for i in $(seq 1 5); do
CTID=$((300 + i))
pct create $CTID local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
--hostname "worker-${i}" --memory 1024 --cores 2 \
--rootfs local-lvm:8 \
--net0 name=eth0,bridge=vmbr0,ip=10.0.0.$((60 + i))/24,gw=10.0.0.1 \
--unprivileged 1 --start 1
done
# 下载云镜像
wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
# 导入到虚拟机
qm importdisk 100 jammy-server-cloudimg-amd64.img local-lvm
# 附加导入的磁盘
qm set 100 --scsi0 local-lvm:vm-100-disk-0
qm set 100 --boot order=scsi0
| 问题 | 解决方案 |
|---|---|
| 虚拟机无法启动 | 检查 qm config <vmid>,使用 pvesm status 验证存储是否存在 |
| "TASK ERROR: can't lock file" | rm /run/lock/qemu-server/lock-<vmid>.conf(首先确认虚拟机未运行) |
| 容器无网络 | 检查网桥是否存在:brctl show;验证防火墙规则 |
| 存储磁盘已满 | 使用 pvesm status 检查使用情况;lvs 用于 LVM 精简池 |
| 集群仲裁丢失 | 在存活的节点上运行 pvecm expected 1(仅用于单节点恢复) |
| 迁移失败 | 确保 CPU 类型相同或使用 --online 进行实时迁移;检查节点间网络 |
| 备份因锁定错误失败 | qm unlock <vmid> 或 pct unlock <ctid> |
| 虚拟机磁盘 I/O 慢 | 使用带 iothread=1 和 discard=on 的 virtio-scsi-pci 控制器 |
| 客户机代理无响应 | 在虚拟机中安装 qemu-guest-agent 并启用:qm set <vmid> --agent 1 |
| 路径 | 内容 |
|---|---|
/etc/pve/ | 集群范围配置(pmxcfs) |
/etc/pve/qemu-server/<vmid>.conf | 虚拟机配置文件 |
/etc/pve/lxc/<ctid>.conf | 容器配置文件 |
/etc/pve/storage.cfg | 存储定义 |
/etc/pve/nodes/ | 每个节点的配置 |
/var/lib/vz/ | 默认本地存储根目录 |
/var/lib/vz/template/iso/ | ISO 镜像 |
/var/lib/vz/template/cache/ | 容器模板 |
/var/lib/vz/dump/ | 备份文件 |
/var/log/pve/tasks/ | 任务日志 |
每周安装次数
100
代码仓库
首次出现
2026年1月31日
安全审计
安装于
opencode88
gemini-cli87
codex84
github-copilot80
amp73
kimi-cli73
| Manage LXC containers |
pvesm | Manage storage |
pvecm | Manage cluster |
pveam | Manage appliance/template downloads |
pvesh | Access the Proxmox API from the shell |
pveperf | Benchmark host performance |
qm# Create a VM with ID 100
qm create 100 --name my-vm --memory 2048 --cores 2 --sockets 1 \
--net0 virtio,bridge=vmbr0 --ostype l26
# Create with SCSI disk on local-lvm storage (32GB)
qm create 100 --name my-vm --memory 4096 --cores 4 \
--scsi0 local-lvm:32 --scsihw virtio-scsi-pci \
--net0 virtio,bridge=vmbr0 --ostype l26
# Attach an ISO for installation
qm set 100 --cdrom local:iso/ubuntu-22.04-server.iso --boot order=ide2
| Command | Purpose |
|---|---|
qm start <vmid> | Start a VM |
qm shutdown <vmid> | Graceful ACPI shutdown |
qm stop <vmid> | Force stop (like pulling power) |
qm reboot <vmid> | Reboot a VM |
qm reset <vmid> | Hard reset |
qm suspend <vmid> | Suspend to RAM |
qm resume <vmid> | Resume from suspend |
qm destroy <vmid> | Delete VM and its disks |
qm destroy <vmid> --purge | Delete VM, disks, and all related jobs |
# Show current config
qm config 100
# Modify hardware
qm set 100 --memory 8192
qm set 100 --cores 4
qm set 100 --balloon 2048 # dynamic memory (min)
qm set 100 --cpu cputype=host # pass through host CPU features
qm set 100 --machine q35 # use Q35 chipset (for PCIe passthrough)
# Add/resize disks
qm set 100 --scsi1 local-lvm:50 # add 50GB disk
qm disk resize 100 scsi0 +20G # grow existing disk by 20GB
# Networking
qm set 100 --net0 virtio,bridge=vmbr0,tag=10 # VLAN tagged
qm set 100 --net1 virtio,bridge=vmbr1 # second NIC
# Cloud-init (for automated provisioning)
qm set 100 --ide2 local-lvm:cloudinit
qm set 100 --ciuser admin --cipassword 'secret'
qm set 100 --ipconfig0 ip=10.0.0.50/24,gw=10.0.0.1
qm set 100 --sshkeys ~/.ssh/authorized_keys
qm set 100 --boot order=scsi0
# EFI / UEFI boot
qm set 100 --bios ovmf --efidisk0 local-lvm:1,efitype=4m,pre-enrolled-keys=1
# Serial console (headless)
qm set 100 --serial0 socket --vga serial0
# PCI passthrough (GPU, NIC, etc.)
qm set 100 --hostpci0 0000:01:00.0,pcie=1
# Create a snapshot
qm snapshot 100 before-upgrade --description "Before kernel upgrade"
# List snapshots
qm listsnapshot 100
# Rollback to snapshot
qm rollback 100 before-upgrade
# Delete a snapshot
qm delsnapshot 100 before-upgrade
# Clone a VM (full copy)
qm clone 100 101 --name cloned-vm --full
# Clone as linked clone (shares base disk, faster)
qm clone 100 101 --name linked-vm
# Convert VM to template (irreversible)
qm template 100
# Create VM from template (linked clone)
qm clone 100 200 --name from-template
# Create VM from template (full clone)
qm clone 100 200 --name from-template --full
# Online migration to another node
qm migrate 100 node2 --online
# Offline migration
qm migrate 100 node2
# VM status
qm status 100
# List all VMs
qm list
# Show running processes/agent info
qm agent 100 ping
qm agent 100 get-osinfo
# Monitor interface (QEMU monitor)
qm monitor 100
pct# Download a template first
pveam update
pveam available --section system
pveam download local debian-12-standard_12.2-1_amd64.tar.zst
# Create container with ID 200
pct create 200 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
--hostname my-ct --memory 1024 --cores 2 \
--rootfs local-lvm:8 \
--net0 name=eth0,bridge=vmbr0,ip=dhcp \
--password 'secret' --unprivileged 1
# Create with static IP
pct create 201 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
--hostname web-ct --memory 2048 --cores 2 \
--rootfs local-lvm:16 \
--net0 name=eth0,bridge=vmbr0,ip=10.0.0.51/24,gw=10.0.0.1 \
--nameserver 1.1.1.1 --unprivileged 1
| Command | Purpose |
|---|---|
pct start <ctid> | Start container |
pct shutdown <ctid> | Graceful shutdown |
pct stop <ctid> | Force stop |
pct reboot <ctid> | Reboot container |
pct destroy <ctid> | Delete container and its volumes |
pct enter <ctid> | Open a shell inside the container |
pct exec <ctid> -- <cmd> | Run a command inside the container |
pct console <ctid> | Attach to container console |
# Show config
pct config 200
# Modify resources
pct set 200 --memory 4096
pct set 200 --cores 4
pct set 200 --swap 1024
# Add mount point (bind mount from host)
pct set 200 --mp0 /mnt/data,mp=/data
# Add additional storage volume
pct set 200 --mp1 local-lvm:50,mp=/var/lib/data
# Networking
pct set 200 --net0 name=eth0,bridge=vmbr0,ip=10.0.0.60/24,gw=10.0.0.1
pct set 200 --net1 name=eth1,bridge=vmbr1,ip=dhcp
# Features (nesting, FUSE, NFS)
pct set 200 --features nesting=1
pct set 200 --features nesting=1,fuse=1,mount=nfs
# DNS
pct set 200 --nameserver "1.1.1.1 8.8.8.8" --searchdomain example.com
# Start on boot
pct set 200 --onboot 1 --startup order=1,up=30
# Snapshot
pct snapshot 200 clean-install
# Rollback
pct rollback 200 clean-install
# Clone
pct clone 200 201 --hostname cloned-ct --full
# List storage pools
pvesm status
# List content of a storage
pvesm list local
pvesm list local-lvm
# Add storage (examples)
pvesm add dir my-backup --path /mnt/backup --content backup
pvesm add nfs nfs-share --server 10.0.0.5 --export /exports/pve --content images,vztmpl
pvesm add lvm my-lvm --vgname my-vg --content rootdir,images
pvesm add zfspool my-zfs --pool rpool/data --content rootdir,images
# Remove storage
pvesm remove my-backup
# Download ISO
wget -P /var/lib/vz/template/iso/ https://example.com/image.iso
# List network interfaces
cat /etc/network/interfaces
# Common bridge configuration (in /etc/network/interfaces)
# auto vmbr0
# iface vmbr0 inet static
# address 10.0.0.1/24
# bridge-ports eno1
# bridge-stp off
# bridge-fd 0
# Apply network changes
ifreload -a
# Create a new cluster
pvecm create my-cluster
# Join an existing cluster
pvecm add 10.0.0.1
# Show cluster status
pvecm status
# List cluster nodes
pvecm nodes
# Remove a node (run from a remaining node)
pvecm delnode nodename
# Check quorum
pvecm expected 1 # force quorum (dangerous, single-node recovery only)
# Enable/disable firewall at datacenter level
pve-firewall start
pve-firewall stop
pve-firewall status
# Manage rules via config files
# Datacenter: /etc/pve/firewall/cluster.fw
# Node: /etc/pve/nodes/<node>/host.fw
# VM/CT: /etc/pve/firewall/<vmid>.fw
# Backup a VM
vzdump 100 --storage local --mode snapshot --compress zstd
# Backup a container
vzdump 200 --storage local --mode stop --compress zstd
# Backup all guests
vzdump --all --storage local --mode snapshot --compress zstd --mailto admin@example.com
# Restore a VM
qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 100
# Restore a container
pct restore 200 /var/lib/vz/dump/vzdump-lxc-200-*.tar.zst
# Restore to different storage
qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 100 --storage local-lvm
# 1. Create base VM and install OS, then convert to template
qm template 9000
# 2. Clone and customize with cloud-init
qm clone 9000 110 --name web-server --full
qm set 110 --ciuser deploy --sshkeys ~/.ssh/authorized_keys
qm set 110 --ipconfig0 ip=10.0.0.110/24,gw=10.0.0.1
qm set 110 --nameserver 1.1.1.1
qm start 110
for i in $(seq 1 5); do
CTID=$((300 + i))
pct create $CTID local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
--hostname "worker-${i}" --memory 1024 --cores 2 \
--rootfs local-lvm:8 \
--net0 name=eth0,bridge=vmbr0,ip=10.0.0.$((60 + i))/24,gw=10.0.0.1 \
--unprivileged 1 --start 1
done
# Download a cloud image
wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
# Import to a VM
qm importdisk 100 jammy-server-cloudimg-amd64.img local-lvm
# Attach the imported disk
qm set 100 --scsi0 local-lvm:vm-100-disk-0
qm set 100 --boot order=scsi0
| Problem | Solution |
|---|---|
| VM won't start | Check qm config <vmid>, verify storage exists with pvesm status |
| "TASK ERROR: can't lock file" | rm /run/lock/qemu-server/lock-<vmid>.conf (verify VM is not running first) |
| Container has no network | Check bridge exists: brctl show; verify firewall rules |
| Disk full on storage | pvesm status to check usage; lvs for LVM thin pools |
| Cluster quorum lost | pvecm expected 1 on surviving node (single-node recovery only) |
| Migration fails | Ensure same CPU type or use --online with live migration; check network between nodes |
| Backup fails with lock error | qm unlock <vmid> or pct unlock <ctid> |
| Slow disk I/O in VM | Use virtio-scsi-pci controller with iothread=1 and discard=on |
| Guest agent not responding | Install qemu-guest-agent in the VM and enable: qm set <vmid> --agent 1 |
| Path | Contents |
|---|---|
/etc/pve/ | Cluster-wide config (pmxcfs) |
/etc/pve/qemu-server/<vmid>.conf | VM configuration files |
/etc/pve/lxc/<ctid>.conf | Container configuration files |
/etc/pve/storage.cfg | Storage definitions |
/etc/pve/nodes/ | Per-node configuration |
/var/lib/vz/ | Default local storage root |
/var/lib/vz/template/iso/ | ISO images |
/var/lib/vz/template/cache/ | Container templates |
/var/lib/vz/dump/ | Backup files |
/var/log/pve/tasks/ | Task logs |
Weekly Installs
100
Repository
First Seen
Jan 31, 2026
Security Audits
Installed on
opencode88
gemini-cli87
codex84
github-copilot80
amp73
kimi-cli73
Cloudflare D1数据库迁移指南 - Drizzle ORM工作流与问题解决方案
335 周安装
Claude API 结构化输出与错误预防指南 - 保证JSON模式一致性,提升AI应用开发效率
325 周安装
Go 代码风格核心原则与最佳实践 | Google/Uber 权威指南
331 周安装
Cloudflare Vectorize 完整指南:全球分布式向量数据库,实现语义搜索与RAG应用
326 周安装
Cloudflare Agents SDK:构建AI驱动的自主智能体,支持可恢复流式传输与持久化状态
326 周安装
Snowflake平台技能:使用CLI、Cortex AI函数和Snowpark构建AI数据云应用
326 周安装