附录 A 命令行参考

A.命令行参考Command-line Interface Reference

关于本附录

PVE 的每个 CLI 工具都以 JSON schema 定义其参数 ， 官方手册中的 CLI 参考是从 schema 自动生成的 —— 包含完整的 synopsis / options / enum 取值 / 默认值， 篇幅极大（英文原文约 14 000 余行）。

为避免大段机械翻译导致走样 ， 本中文附录 不逐参数重译， 而是提供 ：每个工具的 职责概述、子命令分组、常用示例、权威参考入口。完整、最新、最准确的参数列表请查以下三个权威源之一：

• 工具自带帮助 ：<tool> help [command]（例如 qm help set）— 与 PVE 版本严格同步
• man 页 ：man qm、 man pct、 man pvesm……
• 官方在线 API Viewer：pve.proxmox.com/pve-docs/api-viewer/ — REST API 与 CLI 共享 schema

CLI 工具总览

PVE 的 CLI 分为 子命令型（tool <COMMAND> [ARGS] [OPTIONS]）与 单命令型 两类：

通用模式

所有 PVE CLI 共享一些约定 ， 熟悉之后查 help 即可即用：

• 帮助：<tool> help 列出子命令 ； <tool> help <cmd> 看某子命令的完整参数（含 enum / 默认 / 别名）。
• 输出格式：多数可读型子命令支持 --output-format <text|json|json-pretty>， 便于脚本处理。
• 参数来源：CLI 内部调用 REST API —— 字段名与 REST 完全一致 ， 可用 API Viewer 查每个参数的类型 / 约束 / 是否可选。
• VM / CT 配置键：qm / pct 的 set 子命令参数名与 /etc/pve/qemu-server/<vmid>.conf、 /etc/pve/lxc/<ctid>.conf 中键名一致（如 --net0、 --scsi0、 --agent）。
• 存储引用：storage:content 语法（如 local:iso/debian.iso、 local-lvm:vm-100-disk-0）各工具通用。

qm —— QEMU VM（最常用）

子命令按职能分组：

• 生命周期：create / destroy / start / stop / shutdown / reboot / reset / suspend / resume / wait
• 配置：config（读）、 set（改）、 pending（看待生效项）、 unlock、 resize
• 列表 / 状态：list、 status、 cpusets、 showcmd、 mtunnel
• 克隆 / 模板 / 快照：clone、 template、 snapshot、 delsnapshot、 listsnapshot、 rollback
• 迁移 / 移动：migrate、 move-disk（旧 move_disk）、 remote-migrate、 disk import、 importovf、 importdisk
• 磁盘维护：rescan、 disk unlink（旧 unlink）、 disk rebase
• Cloud-Init：cloudinit dump、 cloudinit pending、 cloudinit update
• Guest Agent：guest cmd、 guest exec、 guest exec-status、 guest passwd
• 控制台：terminal、 monitor、 mtunnel、 sendkey、 vncproxy

入门示例 ：

# 创建一台 VM
qm create 100 --name test --memory 2048 --net0 virtio,bridge=vmbr0 \
    --scsihw virtio-scsi-single --scsi0 local-lvm:32

# 启动 / 停止 / 配置
qm start 100
qm set 100 --cores 4 --memory 4096
qm config 100

# 克隆为模板
qm clone 100 200 --name base-template --full 1
qm template 200

# 在线迁移
qm migrate 100 node2 --online 1

# 快照
qm snapshot 100 before-upgrade
qm rollback 100 before-upgrade

pct —— LXC 容器

结构与 qm 对称 ， 常用子命令：

• 生命周期：create / destroy / start / stop / shutdown / reboot / suspend / resume
• 配置：config、 set、 pending、 resize、 unlock、 cpusets
• 克隆 / 模板 / 快照：clone、 template、 snapshot、 rollback、 delsnapshot、 listsnapshot
• 迁移 / 移动：migrate、 move-volume（旧 move_volume）
• 交互：console、 enter、 exec、 push / pull（向容器推 / 拉文件）
• 恢复：restore（从 vzdump）、 listsnapshot
• 挂载 / 调试：mount、 unmount、 fsck、 df

# 从模板建容器
pct create 101 local:vztmpl/debian-12-standard_12.2-1_amd64.tar.zst \
    --hostname web01 --cores 2 --memory 1024 \
    --rootfs local-lvm:8 --net0 name=eth0,bridge=vmbr0,ip=dhcp

# 启动并进入
pct start 101
pct enter 101

# 把主机上的文件塞进容器
pct push 101 /etc/hosts /root/hosts.from-host

pvesm —— 存储

• 存储管理：add、 set、 remove、 status、 list
• 扫描：scan nfs / scan cifs / scan iscsi / scan lvm / scan lvmthin / scan zfs / scan pbs（老别名 nfsscan / cifsscan 等仍保留）
• 卷操作：alloc、 free、 path、 export、 import、 extractconfig
• 保留策略：prune-backups（含 dry-run）
• 诊断：apiinfo

# 列出所有存储状态
pvesm status

# 在 pool 上分配 10 GB 卷
pvesm alloc local-lvm 100 vm-100-disk-1 10G

# 预览剪枝（不实际删除）
pvesm prune-backups local --dry-run 1 --keep-daily 7 --keep-weekly 4

pvecm —— 集群

常用 ：create / add / addnode / delnode / status / nodes / expected / mtunnel / updatecerts / qdevice setup|remove。详见 第 5 章。

pveum —— 用户

按资源类型分组 ：user add|modify|delete|list|permissions|tfa ...、 group ...、 role ...、 acl modify|delete|list、 realm add|modify|delete|sync、 user token add|modify|remove|permissions、 passwd、 pool ...。详见 第 14 章。

pveceph —— Ceph

对应每一类 Ceph 组件的 create / destroy：mon、 mgr、 mds、 osd、 pool、 fs；加上 init、 install、 lspools、 status、 start / stop、 purge。详见 第 8 章。

pvenode —— 节点

• acme account deactivate | info | list | register | update
• acme cert order | renew | revoke
• acme plugin add | config | list | remove | set
• cert info | set | delete
• task list | status | log | cancel
• wakeonlan、 migrateall、 startall、 stopall
• config get | set

pvesh —— REST API Shell

通用动词 —— 与 REST 方法对应：

pvesh get    <path> [--output-format ...]
pvesh set    <path> [options...]       # ↔ HTTP PUT
pvesh create <path> [options...]       # ↔ HTTP POST
pvesh delete <path>
pvesh help   <path>                    # 看某路径支持的方法与参数
pvesh usage  <path> -v                 # 详细用法

示例 ：

pvesh get /nodes
pvesh get /cluster/resources --type vm
pvesh create /nodes/pve1/qemu/100/snapshot --snapname weekly
pvesh set /cluster/options -console html5

ha-manager —— HA

子命令 ：add / remove / set / config / status / migrate / relocate / groupadd / groupset / groupremove / groupconfig / rules add|set|remove|list|config / crm-command。详见 第 15 章。

pvesr —— 存储复制

子命令 ：create / update / delete / list / status / read / run / enable / disable / finalize-local-job / schedule-now / set-state / prepare-local-job。详见 第 9 章。

其他命令

pveam

模板仓库 ：available、 download、 list、 remove、 update（更新可用列表）。 OCI 镜像也受此工具管理（见 §11.3.3）。

pvesubscription

get / set / set-offline-key / update / delete。

qmrestore

单命令 ：qmrestore <archive> <vmid> [options]。常用选项 ：--storage、 --bwlimit、 --live-restore（见 §16.9.2）、 --unique（重新生成 MAC）。

vzdump

单命令 ：vzdump <vmid|--all> [options]。完整选项同 /etc/vzdump.conf 的键（见 §16.10）。

pveperf

单命令 ：pveperf [PATH]（默认 /）。指标见 §19.2。

pveversion

打印当前 PVE 版本；加 -v 列出所有 PVE 相关包的版本（等价于 pveversion --verbose， 常用于提交 bug 报告）。

pvereport

生成系统报告（合并网络 / 存储 / 订阅 / 日志等信息）， 常用于支持工单。

pvebanner

刷新登录时的 issue banner（显示节点 IP / Web UI 地址等）。

pve8to9 / pve7to8

大版本升级前的预检工具 —— 发现阻塞问题。

实用提示

• 先 --dry-run，再真跑：pvesm prune-backups、大量 pveum 批处理、 qm importovf 等支持时尽量先 dry-run。
• 输出 JSON 再 jq：pvesh get /nodes --output-format json | jq '.[] | .node' —— 脚本化首选。
• 任务异步：长耗时操作（备份、迁移、恢复）会返回 UPID —— 用 pvenode task status <UPID> / log <UPID> 跟踪。
• 大版本升级前：先 pve8to9 --full 看是否有阻塞。
• 配置字段 = REST schema：不确定 --net0 某子键怎么写 ？ 打开 API Viewer → POST /nodes/{node}/qemu 查 net[n] 的正则 / enum 取值。