pvenode(1)

NAME

pvenode - Proxmox VE 节点管理

SYNOPSIS

pvenode <COMMAND> [ARGS] [OPTIONS]

pvenode acme account deactivate [<name>]

在 CA 处停用现有 ACME 账户。

<name>: <name> (default = default): ACME 账户配置文件名。

pvenode acme account info [<name>] [FORMAT_OPTIONS]

返回现有 ACME 账户信息。

<name>: <name> (default = default): ACME 账户配置文件名。

pvenode acme account list

ACMEAccount 索引。

pvenode acme account register [<name>] {<contact>} [OPTIONS]

向兼容的 CA 注册新的 ACME 账户。

<name>: <name> (default = default): ACME 账户配置文件名。
<contact>: <string>: 联系电子邮件地址。
--directory ^https?://.*: ACME CA directory endpoint 的 URL。

pvenode acme account update [<name>] [OPTIONS]

向 CA 更新现有 ACME 账户信息。注意：不指定任何新账户信息时会触发刷新。

<name>: <name> (default = default): ACME 账户配置文件名。
--contact <string>: 联系电子邮件地址。

pvenode acme cert order [OPTIONS]

从兼容 ACME 的 CA 申请新证书。

--force <boolean> (default = 0): 覆盖现有自定义证书。

pvenode acme cert renew [OPTIONS]

从 CA 续订现有证书。

--force <boolean> (default = 0): 即使距离过期还有 30 天以上，也强制续订。

pvenode acme cert revoke

从 CA 吊销现有证书。

pvenode acme plugin add <type> <id> [OPTIONS]

添加 ACME 插件配置。

<type>: <dns | standalone>: ACME challenge 类型。
<id>: <string>: ACME 插件 ID 名称
--api <1984hosting | acmedns | acmeproxy | active24 | ad | ali | alviy | anx | artfiles | arvan | aurora | autodns | aws | azion | azure | bookmyname | bunny | cf | clouddns | cloudns | cn | conoha | constellix | cpanel | curanet | cyon | da | ddnss | desec | df | dgon | dnsexit | dnshome | dnsimple | dnsservices | doapi | domeneshop | dp | dpi | dreamhost | duckdns | durabledns | dyn | dynu | dynv6 | easydns | edgedns | euserv | exoscale | fornex | freedns | gandi_livedns | gcloud | gcore | gd | geoscaling | googledomains | he | hetzner | hexonet | hostingde | huaweicloud | infoblox | infomaniak | internetbs | inwx | ionos | ionos_cloud | ipv64 | ispconfig | jd | joker | kappernet | kas | kinghost | knot | la | leaseweb | lexicon | limacity | linode | linode_v4 | loopia | lua | maradns | me | miab | misaka | myapi | mydevil | mydnsjp | mythic_beasts | namecheap | namecom | namesilo | nanelo | nederhost | neodigit | netcup | netlify | nic | njalla | nm | nsd | nsone | nsupdate | nw | oci | omglol | one | online | openprovider | openstack | opnsense | ovh | pdns | pleskxml | pointhq | porkbun | rackcorp | rackspace | rage4 | rcode0 | regru | scaleway | schlundtech | selectel | selfhost | servercow | simply | technitium | tele3 | tencent | timeweb | transip | udr | ultra | unoeuro | variomedia | veesp | vercel | vscale | vultr | websupport | west_cn | world4you | yandex360 | yc | zilore | zone | zoneedit | zonomi>: API 插件名称
--data 每行一个键值对的文件，存入插件配置时会进行 base64url 编码。: DNS 插件数据（base64 编码）。
--disable <boolean>: 用于禁用该配置的标志。
--nodes <string>: 集群节点名称列表。
--validation-delay <integer> (0 - 172800) (default = 30): 请求验证前额外等待的秒数。可用于应对 DNS 记录 TTL 较长的情况。

pvenode acme plugin config <id> [FORMAT_OPTIONS]

获取 ACME 插件配置。

<id>: <string>: ACME 插件实例的唯一标识符。

pvenode acme plugin list [OPTIONS] [FORMAT_OPTIONS]

ACME 插件索引。

--type <dns | standalone>: 仅列出指定类型的 ACME 插件

pvenode acme plugin remove <id>

删除 ACME 插件配置。

<id>: <string>: ACME 插件实例的唯一标识符。

pvenode acme plugin set <id> [OPTIONS]

更新 ACME 插件配置。

<id>: <string>: ACME 插件 ID 名称
--api <1984hosting | acmedns | acmeproxy | active24 | ad | ali | alviy | anx | artfiles | arvan | aurora | autodns | aws | azion | azure | bookmyname | bunny | cf | clouddns | cloudns | cn | conoha | constellix | cpanel | curanet | cyon | da | ddnss | desec | df | dgon | dnsexit | dnshome | dnsimple | dnsservices | doapi | domeneshop | dp | dpi | dreamhost | duckdns | durabledns | dyn | dynu | dynv6 | easydns | edgedns | euserv | exoscale | fornex | freedns | gandi_livedns | gcloud | gcore | gd | geoscaling | googledomains | he | hetzner | hexonet | hostingde | huaweicloud | infoblox | infomaniak | internetbs | inwx | ionos | ionos_cloud | ipv64 | ispconfig | jd | joker | kappernet | kas | kinghost | knot | la | leaseweb | lexicon | limacity | linode | linode_v4 | loopia | lua | maradns | me | miab | misaka | myapi | mydevil | mydnsjp | mythic_beasts | namecheap | namecom | namesilo | nanelo | nederhost | neodigit | netcup | netlify | nic | njalla | nm | nsd | nsone | nsupdate | nw | oci | omglol | one | online | openprovider | openstack | opnsense | ovh | pdns | pleskxml | pointhq | porkbun | rackcorp | rackspace | rage4 | rcode0 | regru | scaleway | schlundtech | selectel | selfhost | servercow | simply | technitium | tele3 | tencent | timeweb | transip | udr | ultra | unoeuro | variomedia | veesp | vercel | vscale | vultr | websupport | west_cn | world4you | yandex360 | yc | zilore | zone | zoneedit | zonomi>: API 插件名称
--data 每行一个键值对的文件，存入插件配置时会进行 base64url 编码。: DNS 插件数据（base64 编码）。
--delete <string>: 要删除的设置列表。
--digest <string>: 如果当前配置文件具有不同 digest，则阻止更改。可用于防止并发修改。
--disable <boolean>: 用于禁用该配置的标志。
--nodes <string>: 集群节点名称列表。
--validation-delay <integer> (0 - 172800) (default = 30): 请求验证前额外等待的秒数。可用于应对 DNS 记录 TTL 较长的情况。

pvenode cert delete [<restart>]

删除自定义证书链和密钥。

<restart>: <boolean> (default = 0): 重启 pveproxy。

pvenode cert info [FORMAT_OPTIONS]

获取节点证书信息。

pvenode cert set <certificates> [<key>] [OPTIONS] [FORMAT_OPTIONS]

上传或更新自定义证书链和密钥。

<certificates>: <string>: PEM 编码的证书（链）。
<key>: <string>: PEM 编码的私钥。
--force <boolean> (default = 0): 覆盖现有自定义或 ACME 证书文件。
--restart <boolean> (default = 0): 重启 pveproxy。

pvenode config get [OPTIONS]

获取节点配置选项。

--property <acme | acmedomain0 | acmedomain1 | acmedomain2 | acmedomain3 | acmedomain4 | acmedomain5 | ballooning-target | description | startall-onboot-delay | wakeonlan> (default = all): 仅返回节点配置中的指定属性。

pvenode config set [OPTIONS]

设置节点配置选项。

--acme [account=<name>] [,domains=<domain[;domain;...]>]: 节点专用 ACME 设置。
--acmedomain[n] [domain=]<domain> [,alias=<domain>] [,plugin=<name of the plugin configuration>]: ACME 域名和验证插件
--ballooning-target <integer> (0 - 100) (default = 80): ballooning 的 RAM 使用目标（占总内存百分比）
--delete <string>: 要删除的设置列表。
--description <string>: 节点描述。显示在 Web 界面的节点备注面板中，并作为注释保存在配置文件内。
--digest <string>: 如果当前配置文件具有不同 SHA1 digest，则阻止更改。可用于防止并发修改。
--startall-onboot-delay <integer> (0 - 300) (default = 0): 启动所有已启用 on-boot 的虚拟客户机之前的初始延迟秒数。
--wakeonlan [mac=]<MAC address> [,bind-interface=<bind interface>] [,broadcast-address=<IPv4 broadcast address>]: 节点专用 Wake-on-LAN 设置。

pvenode help [OPTIONS]

获取指定命令的帮助。

--extra-args <array>: 显示特定命令的帮助
--verbose <boolean>: 详细输出格式。

pvenode migrateall <target> [OPTIONS]

迁移所有虚拟机和容器。

<target>: <string>: 目标节点。
--maxworkers <integer> (1 - N): 并行迁移任务的最大数量。如果未设置，则使用 datacenter.cfg 中的 max_workers。两者必须至少设置一个！
--vms <string>: 仅考虑这些 ID 对应的客户机。
--with-local-disks <boolean>: 为本地磁盘启用在线存储迁移

pvenode startall [OPTIONS]

启动位于该节点上的所有虚拟机和容器（默认仅启动 onboot=1 的客户机）。

--force <boolean> (default = off): 即使虚拟客户机未设置 onboot 或将其设置为 off，也发出启动命令。
--vms <string>: 仅考虑此逗号分隔 VMID 列表中的客户机。

pvenode stopall [OPTIONS]

停止所有虚拟机和容器。

--force-stop <boolean> (default = 1): 超时后强制硬停止。
--timeout <integer> (0 - 7200) (default = 180): 每个客户机关闭任务的超时时间。根据 force-stop 设置，超时后关闭操作会被直接中止或强制硬停止。
--vms <string>: 仅考虑这些 ID 对应的客户机。

pvenode task list [OPTIONS] [FORMAT_OPTIONS]

读取某个节点的任务列表（已完成任务）。

--errors <boolean> (default = 0): 仅列出状态为 ERROR 的任务。
--limit <integer> (0 - N) (default = 50): 仅列出该数量的任务。
--since <integer>: 仅列出此 UNIX epoch 之后的任务。
--source <active | all | archive> (default = archive): 列出归档任务、活动任务或全部任务。
--start <integer> (0 - N) (default = 0): 从该偏移位置开始列出任务。
--statusfilter <string>: 应返回的任务状态列表。
--typefilter <string>: 仅列出此类型的任务（例如 vzstart、vzdump）。
--until <integer>: 仅列出此 UNIX epoch 之前的任务。
--userfilter <string>: 仅列出此用户的任务。
--vmid <integer> (100 - 999999999): 仅列出此虚拟机的任务。

pvenode task log <upid> [OPTIONS]

读取任务日志。

<upid>: <string>: 任务的唯一 ID。
--download <boolean>: 是否下载任务日志文件。该参数不能与其他参数同时使用。
--start <integer> (0 - N) (default = 0): 读取任务日志时从该行开始。

pvenode task status <upid> [FORMAT_OPTIONS]

读取任务状态。

<upid>: <string>: 任务的唯一 ID。

pvenode wakeonlan <node>

尝试通过 Wake-on-LAN 网络包唤醒节点。

<node>: <string>: Wake-on-LAN 网络包的目标节点

DESCRIPTION

Proxmox VE 节点管理工具（pvenode）允许你控制节点特定的设置和资源。

目前，pvenode 可用于设置节点描述、对节点上的客户机执行各种批量操作、查看节点任务历史，以及管理节点 SSL 证书；这些证书会通过 pveproxy 用于 API 和 Web GUI。

FORMAT_OPTIONS

可以使用 --output-format 参数指定输出格式。默认格式 text 使用 ASCII 字符为表格绘制边框，并会将部分值转换为便于阅读的文本，例如：

Unix epoch 会显示为 ISO 8601 日期字符串。
持续时间会显示为周/天/小时/分钟/秒的组合，例如 1d 5h。
字节大小会包含单位（B、KiB、MiB、GiB、TiB、PiB）。
小数会显示为百分比，例如 1.0 会显示为 100%。

也可以使用 --quiet 选项完全抑制输出。

--human-readable <boolean> (default = 1): 调用输出渲染函数以生成人类可读的文本。
--noborder <boolean> (default = 0): 不绘制边框（用于 text 格式）。
--noheader <boolean> (default = 0): 不显示列标题（用于 text 格式）。
--output-format <json | json-pretty | text | yaml> (default = text): 输出格式。
--quiet <boolean>: 禁止打印结果。

示例

安装外部提供的证书

pvenode cert set certificate.crt certificate.key -force

两个文件都需要使用 PEM 编码。certificate.key 包含私钥，certificate.crt 包含完整证书链。

设置 ACME 账号并为本地节点申请证书。

pvenode acme account register default mail@example.invalid
pvenode config set --acme domains=example.invalid
pvenode acme cert order
systemctl restart pveproxy

常用命令示例

以下命令可用于查看节点任务、唤醒集群节点或批量启动已配置自启动的客户机：

pvenode task list
pvenode wakeonlan <node>
pvenode startall

Wake-on-LAN

Wake-on-LAN（WoL）允许你通过发送 magic packet 来启动网络中处于睡眠状态的计算机。至少需要有一个 NIC 支持此功能，并且需要在计算机固件（BIOS/UEFI）配置中启用相应选项。选项名称可能从 Enable Wake-on-Lan 到 Power On By PCIE Device 不等；如果不确定，请查阅主板厂商手册。可以运行以下命令，使用 ethtool 检查 <interface> 的 WoL 配置：

ethtool <interface> | grep Wake-on

pvenode 允许你通过 WoL 唤醒集群中处于睡眠状态的成员，使用命令：

pvenode wakeonlan <node>

这会在 UDP 端口 9 上广播 WoL magic packet，其中包含从 wakeonlan 属性获取的 <node> MAC 地址。可以使用以下命令设置节点特定的 wakeonlan 属性：

pvenode config set -wakeonlan XX:XX:XX:XX:XX:XX

发送 WoL 数据包所使用的接口由默认路由决定。可以通过以下命令设置 bind-interface 来覆盖它：

pvenode config set -wakeonlan XX:XX:XX:XX:XX:XX,bind-interface=<iface-name>

发送 WoL 数据包时使用的广播地址（默认 255.255.255.255）还可以通过以下命令显式设置 broadcast-address 来修改：

pvenode config set -wakeonlan XX:XX:XX:XX:XX:XX,broadcast-address=<broadcast-address>

任务历史

排查服务器问题时，例如备份作业失败，查看此前运行任务的日志通常很有帮助。在 Proxmox VE 中，可以通过 pvenode task 命令访问节点的任务历史。

可以使用 list 子命令获取节点已完成任务的过滤列表。例如，要获取与虚拟机 100 相关且以错误结束的任务列表，可使用：

pvenode task list --errors --vmid 100

随后可以使用任务的 UPID 打印该任务日志：

pvenode task log UPID:pve1:00010D94:001CA6EA:6124E1B9:vzdump:100:root@pam:

批量客户机电源管理

如果有许多虚拟机/容器，可以使用 pvenode 的 startall 和 stopall 子命令对客户机执行批量启动和停止操作。默认情况下，pvenode startall 只会启动已设置为开机自动启动的虚拟机/容器（参见虚拟机的自动启动和关闭）；不过可以使用 --force 标志覆盖此行为。这两个命令也都有 --vms 选项，可将停止/启动的客户机限制为指定 VMID。

例如，要启动虚拟机 100、101 和 102，无论它们是否设置了 onboot，可以使用：

pvenode startall --vms 100,101,102 --force

要停止这些客户机（以及可能正在运行的任何其他客户机），请使用命令：

pvenode stopall

stopall 命令会先尝试执行干净关机，然后等待所有客户机成功关闭，或等待可覆盖的超时时间（默认 3 分钟）到期。到达该状态后，如果 force-stop 参数没有显式设置为 0（false），所有仍在运行的虚拟客户机都会被强制停止。

首个客户机启动延迟

如果虚拟机/容器依赖启动较慢的外部资源，例如 NFS 服务器，也可以按节点设置延迟：从 Proxmox VE 启动完成到第一个配置为自动启动的虚拟机/容器启动之间等待一段时间（参见虚拟机的自动启动和关闭）。

可以通过以下设置实现这一点（其中 10 表示以秒为单位的延迟）：

pvenode config set --startall-onboot-delay 10

批量客户机迁移

如果升级场景要求将所有客户机从一个节点迁移到另一个节点，pvenode 也提供了用于批量迁移的 migrateall 子命令。默认情况下，该命令会将系统上的每个客户机迁移到目标节点；不过也可以设置为只迁移一组客户机。

例如，要将虚拟机 100、101 和 102 迁移到节点 pve2，并启用本地磁盘在线迁移，可以运行：

pvenode migrateall pve2 --vms 100,101,102 --with-local-disks

Ballooning 的 RAM 使用率目标

自动内存分配的目标百分比默认为 80%。可以通过设置 ballooning-target 属性按节点自定义此目标。例如，要改为以 90% 主机内存使用率为目标：

pvenode config set --ballooning-target 90

版权和免责声明

本程序是自由软件：你可以依据自由软件基金会发布的 GNU Affero General Public License 条款重新分发和/或修改本程序；可使用该许可证第 3 版，或（由你选择）任何后续版本。

发布本程序是希望它能够有用，但不提供任何担保；甚至不包含对适销性或特定用途适用性的默示担保。更多详情请参见 GNU Affero General Public License。

你应当已经随本程序收到一份 GNU Affero General Public License 的副本。如果没有，请访问： https://www.gnu.org/licenses/

发布本程序是希望它能够有用，但不提供任何担保；甚至不包含对适销性或特定用途适用性的默示担保。更多详情请参见 GNU Affero General Public License。

你应当已经随本程序收到一份 GNU Affero General Public License 的副本。如果没有，请访问： https://www.gnu.org/licenses/