Proxmox VE Administration

Proxmox VE 管理

Overview

概述

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.

Proxmox VE是基于Debian构建的服务器虚拟化平台，可通过Web UI或CLI工具管理KVM虚拟机和LXC容器。本技能涵盖使用

qm

（虚拟机）、

pct

（容器）及配套工具的CLI管理方式。

When to Use

适用场景

Creating, configuring, or managing KVM virtual machines
Spawning and administering LXC containers
Managing Proxmox storage, networking, or clustering
Automating VM/container provisioning via scripts
Troubleshooting Proxmox host or guest issues

Not for: Web UI-only workflows (use the CLI equivalents below).

创建、配置或管理KVM虚拟机
创建和管理LXC容器
管理Proxmox的存储、网络或集群
通过脚本自动化虚拟机/容器置备
排查Proxmox主机或客户机问题

不适用： 仅使用Web UI的工作流（请使用下方对应的CLI操作）。

Quick Reference

速查参考

Tool	Purpose
`qm`	Manage KVM virtual machines
`pct`	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`	管理KVM虚拟机
`pct`	管理LXC容器
`pvesm`	管理存储
`pvecm`	管理集群
`pveam`	管理应用/模板下载
`pvesh`	从Shell访问Proxmox API
`pveperf`	基准测试主机性能

VM Management with

qm

使用

qm

管理虚拟机

Creating a VM

创建虚拟机

bash

undefined

bash

undefined

Create a VM with ID 100

创建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)

在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

Attach an ISO for installation

挂载ISO镜像用于安装

qm set 100 --cdrom local:iso/ubuntu-22.04-server.iso --boot order=ide2

undefined

qm set 100 --cdrom local:iso/ubuntu-22.04-server.iso --boot order=ide2

undefined

VM Lifecycle

虚拟机生命周期管理

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

命令	用途
`qm start <vmid>`	启动虚拟机
`qm shutdown <vmid>`	优雅ACPI关机
`qm stop <vmid>`	强制停止（类似拔电源）
`qm reboot <vmid>`	重启虚拟机
`qm reset <vmid>`	硬重置
`qm suspend <vmid>`	挂起到内存
`qm resume <vmid>`	从挂起恢复
`qm destroy <vmid>`	删除虚拟机及其磁盘
`qm destroy <vmid> --purge`	删除虚拟机、磁盘及所有相关任务

VM Configuration

虚拟机配置

bash

undefined

bash

undefined

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)

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透传）

Add/resize disks

添加/扩容磁盘

qm set 100 --scsi1 local-lvm:50 # add 50GB disk qm disk resize 100 scsi0 +20G # grow existing disk by 20GB

qm set 100 --scsi1 local-lvm:50 # 添加50GB磁盘 qm disk resize 100 scsi0 +20G # 现有磁盘扩容20GB

Networking

网络配置

qm set 100 --net0 virtio,bridge=vmbr0,tag=10 # VLAN tagged qm set 100 --net1 virtio,bridge=vmbr1 # second NIC

qm set 100 --net0 virtio,bridge=vmbr0,tag=10 # VLAN标记 qm set 100 --net1 virtio,bridge=vmbr1 # 第二块网卡

Cloud-init (for automated provisioning)

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 boot

EFI / UEFI启动

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.)

PCI透传（GPU、网卡等）

qm set 100 --hostpci0 0000:01:00.0,pcie=1

undefined

qm set 100 --hostpci0 0000:01:00.0,pcie=1

undefined

Snapshots and Cloning

快照与克隆

bash

undefined

bash

undefined

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

undefined

qm clone 100 101 --name linked-vm

undefined

Templates

模板管理

bash

undefined

bash

undefined

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

undefined

qm clone 100 200 --name from-template --full

undefined

Migration

迁移

bash

undefined

bash

undefined

Online migration to another node

在线迁移到其他节点

qm migrate 100 node2 --online

Offline migration

离线迁移

qm migrate 100 node2

undefined

qm migrate 100 node2

undefined

Monitoring

监控

bash

undefined

bash

undefined

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)

监控接口（QEMU监视器）

qm monitor 100

undefined

qm monitor 100

undefined

Container Management with

pct

使用

pct

管理容器

Creating a Container

创建容器

bash

undefined

bash

undefined

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

创建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

创建带静态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

undefined

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

undefined

Container Lifecycle

容器生命周期管理

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

命令	用途
`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>`	连接到容器控制台

Container Configuration

容器配置

bash

undefined

bash

undefined

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)

特性配置（嵌套、FUSE、NFS）

pct set 200 --features nesting=1 pct set 200 --features nesting=1,fuse=1,mount=nfs

DNS

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

undefined

pct set 200 --onboot 1 --startup order=1,up=30

undefined

Container Snapshots and Cloning

容器快照与克隆

bash

undefined

bash

undefined

Snapshot

创建快照

pct snapshot 200 clean-install

Rollback

回滚快照

pct rollback 200 clean-install

Clone

克隆容器

pct clone 200 201 --hostname cloned-ct --full

undefined

pct clone 200 201 --hostname cloned-ct --full

undefined

Storage Management

存储管理

bash

undefined

bash

undefined

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

下载ISO镜像

wget -P /var/lib/vz/template/iso/ https://example.com/image.iso

undefined

wget -P /var/lib/vz/template/iso/ https://example.com/image.iso

undefined

Networking

网络管理

bash

undefined

bash

undefined

List network interfaces

列出网络接口

cat /etc/network/interfaces

Common bridge configuration (in /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

Apply network changes

应用网络变更

ifreload -a

undefined

ifreload -a

undefined

Cluster Management

集群管理

bash

undefined

bash

undefined

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)

undefined

pvecm expected 1 # 强制法定人数（仅单节点恢复时使用，有风险）

undefined

Firewall

防火墙

bash

undefined

bash

undefined

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

数据中心：/etc/pve/firewall/cluster.fw

Node: /etc/pve/nodes/<node>/host.fw

节点： /etc/pve/nodes/<node>/host.fw

VM/CT: /etc/pve/firewall/<vmid>.fw

虚拟机/容器： /etc/pve/firewall/<vmid>.fw

undefined

undefined

Backup and Restore

备份与恢复

bash

undefined

bash

undefined

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

undefined

qmrestore /var/lib/vz/dump/vzdump-qemu-100-*.vma.zst 100 --storage local-lvm

undefined

Common Provisioning Patterns

常见置备模式

Cloud-Init VM from Template

从模板创建Cloud-init虚拟机

bash

undefined

bash

undefined

1. Create base VM and install OS, then convert to template

1. 创建基础虚拟机并安装系统，然后转换为模板

qm template 9000

2. Clone and customize with cloud-init

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

undefined

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

undefined

Batch Create Containers

批量创建容器

bash

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

bash

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

Import Disk Image (e.g., cloud image)

导入磁盘镜像（如云镜像）

bash

undefined

bash

undefined

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

undefined

qm set 100 --scsi0 local-lvm:vm-100-disk-0 qm set 100 --boot order=scsi0

undefined

Troubleshooting

故障排查

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`

问题	解决方案
虚拟机无法启动	检查 `qm config <vmid>` ，通过 `pvesm status` 验证存储是否存在
"TASK ERROR: can't lock file"	删除 `/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缓慢	使用 `virtio-scsi-pci` 控制器并开启 `iothread=1` 和 `discard=on`
客户机代理无响应	在虚拟机中安装 `qemu-guest-agent` 并启用： `qm set <vmid> --agent 1`

Useful Paths

常用路径

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

路径	内容
`/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/`	任务日志

proxmox-admin

Original

Translation

Proxmox VE Administration

Proxmox VE 管理

Overview

概述

When to Use

适用场景

Quick Reference

速查参考

VM Management with qm

使用qm管理虚拟机

Creating a VM

创建虚拟机

Create a VM with ID 100

创建ID为100的虚拟机

Create with SCSI disk on local-lvm storage (32GB)

在local-lvm存储上创建带SCSI磁盘的虚拟机（32GB）

Attach an ISO for installation

挂载ISO镜像用于安装

VM Lifecycle

虚拟机生命周期管理

VM Configuration

虚拟机配置

Show current config

查看当前配置

Modify hardware

修改硬件配置

Add/resize disks

添加/扩容磁盘

Networking

网络配置

Cloud-init (for automated provisioning)

Cloud-init（自动化置备）

EFI / UEFI boot

EFI / UEFI启动

Serial console (headless)

串行控制台（无图形界面）

PCI passthrough (GPU, NIC, etc.)

PCI透传（GPU、网卡等）

Snapshots and Cloning

快照与克隆

Create a snapshot

创建快照

List snapshots

列出快照

Rollback to snapshot

回滚到快照

Delete a snapshot

删除快照

Clone a VM (full copy)

克隆虚拟机（完整复制）

Clone as linked clone (shares base disk, faster)

克隆为链接克隆（共享基础磁盘，速度更快）

Templates

模板管理

Convert VM to template (irreversible)

将虚拟机转换为模板（不可逆）

Create VM from template (linked clone)

从模板创建虚拟机（链接克隆）

Create VM from template (full clone)

从模板创建虚拟机（完整克隆）

Migration

迁移

Online migration to another node

在线迁移到其他节点

Offline migration

离线迁移

Monitoring

监控

VM status

虚拟机状态

List all VMs

列出所有虚拟机

Show running processes/agent info

查看运行进程/代理信息

Monitor interface (QEMU monitor)

监控接口（QEMU监视器）

Container Management with pct

VM Management with
`qm`

使用
`qm`
管理虚拟机

Container Management with
`pct`

使用
`pct`
管理容器