你的虚拟机启动时,客户看到的是什么

你以自己的名义出售虚拟机。 客户开机,屏幕上出现的第一样东西却是别人的 logo。

这就是一台原装的 Proxmox 虚拟机。 什么都没坏,Proxmox 也没做错任何事:这是他们的产品、他们的名字,固件和显示它的界面都是他们写的,他们完全有权把名字放在那里,就像服务器厂商把自家铭牌钉在机箱正面一样。 只是那不是你的。

logo 只是开始。 下面是一台原装 UEFI 客户机在 Proxmox 当前固件 pve-edk2-firmware 4.2026.08-1 上报告的内容,在客户机内部用 dmidecode 读出:

客户机看的地方读到的内容谁的名字
启动画面Proxmox 的 logoProxmox
固件厂商(SMBIOS 类型 0)Proxmox distribution of EDK IIProxmox
固件版本4.2026.08-1Proxmox 的软件包版本
系统制造商(类型 1)QEMUQEMU
产品名(类型 1)Standard PC (Q35 + ICH9, 2009)QEMU
机箱制造商(类型 3)QEMUQEMU
主板(类型 2)根本不存在谁都不是
管理 Web 界面左上角的 Proxmox logoProxmox

启动 logo 也不止于固件。 UEFI 固件会通过一张叫 BGRT(Boot Graphics Resource Table,启动图形资源表)的 ACPI 表,把它画过的图像交给操作系统,这张表存在的目的就是说明“an image was drawn on the screen during boot”1,然后操作系统会在它自己的启动画面上再画一遍。 Fisher-Price OS (Windows) 把它放在转圈动画的上方,Microsoft 称 BGRT 为“the standard interface that Windows uses to access the logo”2。 Fedora 默认的 Plymouth 主题在 Linux 上也这么做3。 所以,一台跑在 Proxmox 固件上的客户机,在任何人登录之前就把 Proxmox 的 logo 显示了两遍。

这些改起来都不难。 难的是让它保持改过的样子。 下一次 apt full-upgrade 会悄悄把其中一半放回去,而它没放回去的那一半,才是你应该担心的那一半,本文大部分篇幅讲的就是这个。

每一处品牌在启动的哪一步进入开机QEMU 根据配置构建 SMBIOS和 ACPI 表固件OVMF 画出内置 logo,SeaBIOS 显示启动画面交接SMBIOS 表,ACPI 含 BGRT和 MSDM系统启动画面重画固件 logo取自 BGRT运行中的客户机读取字符串,激活程序读取MSDM 密钥虚拟机配置软件包文件虚拟机配置软件包文件虚拟机配置在 /etc/pve 中,每次升级后都还在在 /usr/share 下,apt 会替换它
品牌信息在启动过程中从五个地方进入。其中三个出自虚拟机自己的配置,apt 怎么折腾都留得住。另外两个来自某个 Proxmox 软件包拥有的文件,升级会把它们收回去的就是这两个。

交接过程中的那张 MSDM 表根本不是品牌。 它装的是许可证密钥,把它搬进虚拟机另有一篇文章:Moving an OEM Licence Into a Proxmox VM。

/usr/share 下的一切都归 apt 所有

一条规则决定了下面的每一个选择。 软件包安装的文件就是软件包的文件。 你就地修改它,下一次这个软件包升级就会一声不吭地覆盖你的修改,因为在 dpkg 看来,它只是把自己的文件放回原处而已。

所以每一处品牌都必须放在 apt 不拥有的地方。 一个 Proxmox 节点上有三个这样的地方,各有各的代价:

放在哪里怎么放进去升级后是否还在你付出的代价
/etc/pve 里的虚拟机配置smbios1,其他一切用 args是,配置从不会被软件包碰args 只有 root 能设,而且 GUI 里不显示
一个已告诉 dpkg 别动的文件dpkg-divert是,软件包的那份改装到一个 .distrib 名字下升级再也到不了这个文件,而当这个文件是固件时,这就要紧了
你自己的目录,在软件包目录树之外/usr/local,从 args 引用是,没有软件包拥有它得你自己放到每个节点上

Debian 自己对 diversion 的描述最清楚:“a way of forcing dpkg not to install a file into its location, but to a diverted location”4。 Web 界面就靠它解决。 对固件来说,它是两个选项之一,而且是更危险的那个。

机箱不过是几个字符串加一道权限检查

SMBIOS 是一台机器用来描述自己的表:谁造的,什么型号,序列号,主板和机箱是什么5。 dmidecode 读它,你在网络上用过的每一个资产盘点工具都读它,Fisher-Price OS (Windows) 的系统信息面板读它,大多数决定某个软件能不能在某台机器上运行的许可证检查也读它。 在虚拟机上,写它的是 QEMU。 所以上表里才是 QEMU 和 Standard PC。

类型 1 走 smbios1

Proxmox 在虚拟机配置里暴露了一个 SMBIOS 结构:类型 1,System Information,即 smbios16。 它接受 manufacturer、product、version、serial、sku、family 和 uuid。

坑在 qemu-server 里,不在文档里。 除了 uuid,每个字段都必须匹配一个 base64 模式 [A-Za-z0-9+\/]+={0,2},所以一个带空格的普通值会被直接拒绝。 真正的字符串要做 base64 编码,并设上 base64=1,qemu-server 在构造 QEMU 命令行之前会再把它们解码回来7。 GUI 的 SMBIOS 编辑器每次保存都这么做,代码注释写着“smbios values can be arbitrary, so encode and mark config as such”8。 在命令行上,这就是你的活了:

b() { printf %s "$1" | base64 -w0; }
qm set 9000 --smbios1 "uuid=$(qm config 9000 | sed -n 's/.*uuid=\([0-9a-f-]*\).*/\1/p'),base64=1,\
manufacturer=$(b 'Example Cloud Ltd'),product=$(b 'EC Compute Instance'),\
version=$(b '2026.10'),family=$(b 'General Purpose'),sku=$(b 'ec-gp-4c16g')"

注意 uuid 被放了回去。 它是客户机的机器身份,而你传给 --smbios1 的东西会作为整个选项保存下来,所以要先读出来并保留。

给模板打品牌,而不是给每台虚拟机打。 Proxmox 克隆会生成一个新的 UUID,并保留 smbios1 的其他所有字段,所以每个克隆出来都有自己的身份和你的字符串9,只有一个例外,见下文。

类型 0、2、3 和 11 走 args

smbios1 止步于类型 1。 固件厂商、主板、机箱和 OEM 字符串都要走 args,也就是 Proxmox 原样传给 QEMU 的那一行,Proxmox 自己的文档称之为“for experts only”6。 QEMU 的 -smbios 选项接受每种类型的字段10:

args: -smbios 'type=0,vendor=Example Cloud Ltd,version=EC-FW 1.0,date=10/04/2026,uefi=on' -smbios 'type=2,manufacturer=Example Cloud Ltd,product=EC Virtual Board,version=1.0' -smbios 'type=3,manufacturer=Example Cloud Ltd,version=1.0,asset=EC-ASSET-123,sku=ec-gp' -smbios 'type=11,value=example-cloud:instance=123'

在 QEMU 上带着这些行启动后,客户机的 dmidecode 读到:

结构字段原装打品牌后
类型 0VendorProxmox distribution of EDK IIExample Cloud Ltd
类型 0Version4.2026.08-1EC-FW 1.0
类型 1ManufacturerQEMUExample Cloud Ltd
类型 1Product NameStandard PC (Q35 + ICH9, 2009)EC Compute Instance
类型 1Family未指定General Purpose
类型 2Manufacturer没有这个结构Example Cloud Ltd
类型 2Product Name没有这个结构EC Virtual Board
类型 3ManufacturerQEMUExample Cloud Ltd
类型 3Asset Tag未指定EC-ASSET-123
类型 11String 1没有这个结构example-cloud:instance=123

一路上冒出了四个陷阱。四个都悄无声息。

提供类型 0 会让“UEFI is supported”消失。 只有当 QEMU 没有提供类型 0 时,OVMF 才写它自己的类型 0;遍历 QEMU 表的那个循环一遇到类型 0 就把 NeedSmbiosType0 = FALSE 设上11。 你的厂商字符串替换了 Proxmox 的,这正是目的。 但 QEMU 的类型 0 也替换了 OVMF 的固件特性,没有 uefi=on 的话,“UEFI is supported”这一行就从 dmidecode 里消失了。 用 uefi=on 把它加回来。 对 UEFI 客户机,厂商字符串反正有个更好的去处,就在固件本身里面,后文会讲。

机箱类型设不了。 QEMU 的类型 3 只接受 manufacturer、version、serial、asset 和 sku,别的都不接受10。 它会一直是 Other。

同一类型的两份定义会合并,后面的胜出。 qemu-server 把它的 -smbios type=1 放在命令行靠前的位置,把你的 args 放在最末尾12,所以 args 里的第二个 -smbios type=1,manufacturer=… 并不会把第一个扔掉:QEMU 逐字段合并它们,manufacturer 来自 args,UUID 还是 smbios1 设的那个。 这一点对第四个陷阱很要紧。

两半的主人不同。 qemu-server 逐个选项检查权限。 smbios1 归在硬件选项里,需要 VM.Config.HWType,而 args 落到最底下那个兜底分支,写着“only root can set”13。 主板、机箱、固件厂商和 OEM 字符串只有你能改。 类型 1 不是。 任何你给过硬件权限的人都能改写它,而在托管产品上,这个人很可能就是客户。 如果制造商字符串要紧,就在 args 里也设一遍。后面的定义胜出。

序列号早就在配置里了

类型 1 里该放的东西,大部分已经躺在虚拟机配置里了。 名字是个很好的序列号,因为 qemu-server 在那里只接受 DNS 名14:短,可打印,绝不含逗号,而且是这台虚拟机上客户唯一认得的东西。

类型 1 字段取自对一台名为 web-01、标签 production;web 的 4 核 16 GiB 虚拟机
Serial Numbernameweb-01
SKU Numbercores × sockets,以及 memoryec-4c16g
Familytags 里的第一项production
UUID它已有的 smbios1 UUID不变
Manufacturer、Product你自己的固定字符串Example Cloud Ltd、EC Compute Instance

有两样东西不放进去。 节点每次迁移都会变,而 vmgenid 本来就该变:它全部的工作就是告诉客户机,它是从快照恢复的,或者是从模板构建的15。 两者都不是身份。

#!/bin/bash
# /usr/local/sbin/ec-smbios VMID: rebuild smbios1 from the VM's own config.
set -euo pipefail
id=$1
cfg=$(qm config "$id" --current)
get() { sed -n "s/^$1: //p" <<<"$cfg"; }
b() { printf %s "$1" | base64 -w0; }

name=$(get name)
[ -n "$name" ] || { echo "VM $id has no name to use as a serial" >&2; exit 1; }
cores=$(get cores); sockets=$(get sockets); vcpu=$(( ${cores:-1} * ${sockets:-1} ))
mem=$(get memory); mem=${mem#current=}; mem=${mem%%,*}; mem=${mem:-512}
(( mem % 1024 )) && size="${mem}m" || size="$(( mem / 1024 ))g"
tag=$(get tags); tag=${tag%%;*}
uuid=$(get smbios1 | grep -o 'uuid=[0-9a-fA-F-]*' | cut -d= -f2 || true)
uuid=${uuid:-$(cat /proc/sys/kernel/random/uuid)}

s="uuid=$uuid,base64=1,manufacturer=$(b 'Example Cloud Ltd'),product=$(b 'EC Compute Instance')"
s+=",serial=$(b "$name"),sku=$(b "ec-${vcpu}c${size}")"
[ -n "$tag" ] && s+=",family=$(b "$tag")"
qm set "$id" --smbios1 "$s"

默认值用的是 qemu-server 自己的,一个核、一个插槽、512 MiB16,所以一份省略了它们的配置照样得到正确的 SKU。 用上表里的配置去跑它,qm 换成一个供出这份配置的脚本,它写出的那一行按 qemu-server 的方式解码后交给 QEMU,客户机的 dmidecode 读回了 web-01、ec-4c16g、production 和它原有的 UUID。 没有名字的虚拟机会被拒绝,而不是给一个空序列号。

最显而易见的去处是 hookscript。 那是错的去处。 qemu-server 在为启动虚拟机而拿到的配置锁里运行 pre-start 钩子,并且用钩子运行之前加载的配置来构造 QEMU 命令行17。 一个改写序列号的钩子改变的是下一次启动,不是这一次。

所以要从你的开通流程里运行它,在它的输入会变化的四个时刻:创建、克隆、重命名和调整规格。 咬人的是克隆。 克隆保留 smbios1 除 UUID 以外的每个字段9,所以漏掉这一步,每台从 web-template 构建的虚拟机都会把模板的名字报告成自己的序列号。

启动 logo 住在两个不同的地方

客户机显示哪个 logo,取决于它的固件。 Proxmox 自带的两种固件,从完全不同的地方拿 logo:

SeaBIOS(bios: seabios,默认)OVMF(bios: ovmf,UEFI)
logo 从哪里来QEMU 在启动时交过去的一张 JPEG编译进固件里的一张位图
Proxmox 的文件/usr/share/qemu-server/bootsplash.jpg,640×480Logo.bmp,400×120,8 位,编译进 OVMF_CODE_4M*.fd
所属软件包qemu-serverpve-edk2-firmware-ovmf
按虚拟机修改args: -boot splash=…用 args 让虚拟机指向别的固件
不重新构建任何东西就能改能不能
通过 BGRT 到达客户机操作系统否是

SeaBIOS:命令行上的一张 JPEG

qemu-server 给它启动的每台虚拟机都加上同一个 -boot 选项:menu=on,strict=on,reboot-timeout=1000,splash=/usr/share/qemu-server/bootsplash.jpg18。 QEMU 的文档说,这张图会在“when option splash=sp_name is given and menu=on, If firmware/BIOS supports them. Currently Seabios for X86 system support it”时显示10。 OVMF 从中只拿 splash-time,用作启动菜单的超时,OvmfPkg 里没有任何地方引用这个 splash 文件19。

替换它只需在虚拟机配置里加一行:

args: -boot splash=/etc/pve/branding/splash.jpg

第二个 -boot 不会和第一个打架。 QEMU 用合并 -smbios 的同样方式合并它,后面的值胜出;给两个 splash 文件时,截图显示的是第二个。 /etc/pve 是放这个文件的正确位置,因为它是集群文件系统,每个节点看到的都是同一张 splash,而它每个文件 1 MiB 的上限,离一张 640×480 的 JPEG 还远着呢20。

图像本身必须满足三个条件,任何一个弄错,你就会丢掉 logo 或者它的颜色:

条件为什么否则会怎样
JPEG 或 24 位 BMPQEMU 在虚拟机启动前检查文件splash file … format not recognized; must be JPEG or 24 bit BMP
Baseline JPEG,4:2:0 色度SeaBIOS 的解码器别的都处理不了21ERR_NOT_SEQUENTIAL_DCT 或 ERR_NOT_YCBCR_221111,外加一块黑屏
640×480,和 Proxmox 自己的一样SeaBIOS 向 VGA BIOS 要一个和图片尺寸完全一致的模式没有匹配的模式,就没有 splash

大多数图像工具默认写 baseline 4:2:0,所以丢掉 logo 的常见方式,是某个“存储为 Web 格式”之类的选项悄悄打开了渐进式编码,在你所有的图片查看器里看起来一模一样,而 SeaBIOS 却什么都画不出来。

颜色陷阱

这个花了我一个下午。 同一张 JPEG,用两个 SeaBIOS 1.17.0 构建渲染,出来是两种不同的颜色:

Example Cloud 的 splash 三连:带蓝色 logo 方块的源 JPEG,Proxmox 自带的 SeaBIOS 显示同样的蓝色,以及一个以每像素 32 位运行的 SeaBIOS 构建把蓝色变成了金色

问题在 SeaBIOS 的 jpeg.c 里。 每像素 24 位的写入函数有一个小端分支,把蓝色放在每个像素的第一个字节,而每像素 32 位的写入函数 PIC_32 没有这个分支,在那里写的是红色21。 在小端的帧缓冲上,这就把红和蓝对调了。 蓝色出来是金色,橙色出来会是蓝色。

运行哪个写入函数,取决于 VGA BIOS 提供的视频模式:

固件640×480 的 VBE 模式每像素位数颜色
QEMU 上游预编译的 SeaBIOS 1.17.0,即 pve-qemu-kvm 11.0.3-4 自带的0x11116正确,量化到 65,536 色
Fedora 44 自己构建的 seabios 1.17.0-100x14232红蓝对调

模式编号来自 SeaBIOS 自己的表22,Proxmox 那一行是对照软件包里的二进制本身核对过的:和 QEMU 预编译的 rel-1.17.0-0-gb52ca86e094d 逐字节相同。 所以在 Proxmox 上你的颜色是对的,只是只有 65,536 种,细腻的渐变会出现色带。 而如果你的 logo 哪天在别的 hypervisor 上颜色不对,那不是你 JPEG 的问题。

UEFI logo 是编译进固件里的

UEFI 客户机是更难的那一半,而在如今的 Proxmox 上,大多数客户机都是 UEFI。

没有 splash 选项可以覆盖。 logo 是固件镜像里的一张位图,Proxmox 的构建用 debian/rules 里的一行把它放进去:

debian/setup-build-stamp:
	cp -a debian/Logo.bmp MdeModulePkg/Logo/Logo.bmp

这会在 edk2 构建之前,把他们那张 400×120、8 位的 Logo.bmp 覆盖到 TianoCore 的那张上23。 同一个文件还把固件厂商设成一个构建时常量 PcdFirmwareVendor=L"Proxmox distribution of EDK II",第一张表里的类型 0 厂商就是从这里来的23。

新 logo,就是新固件。 要得到一个行为和 Proxmox 完全一样的固件,办法就是完全照 Proxmox 的方式构建:他们的源码树,签出与他们所发布软件包相对应的标签,他们的补丁,他们的标志,只换一张位图。 pve-edk2-firmware 4.2026.08-1 把 edk2 固定在 2970e56,也就是上游的 edk2-stable202608 标签23。

git clone https://git.proxmox.com/git/pve-edk2-firmware.git
cd pve-edk2-firmware
git checkout f37039e52d228a7844a90aa2aaf1e161ebd04fcd   # 4.2026.08-1
git submodule update --init --recursive
cd edk2
QUILT_PATCHES=../debian/patches quilt push -a
cp /path/to/your/Logo.bmp MdeModulePkg/Logo/Logo.bmp
. ./edksetup.sh && make -C BaseTools

F="-DNETWORK_HTTP_BOOT_ENABLE=TRUE -DNETWORK_IP6_ENABLE=TRUE -DNETWORK_TLS_ENABLE
   -DSECURE_BOOT_ENABLE=TRUE -DPVSCSI_ENABLE=TRUE -DTPM2_ENABLE=TRUE
   --pcd PcdUninstallMemAttrProtocol=TRUE -DFD_SIZE_4MB"
P=(--pcd "PcdFirmwareVendor=LExample Cloud Ltd\\0"
   --pcd "PcdFirmwareVersionString=L4.2026.08-1+ec1\\0")

build -a IA32 -a X64 -t GCC -p OvmfPkg/OvmfPkgIa32X64.dsc $F "${P[@]}" -b RELEASE
cp Build/Ovmf3264/RELEASE_GCC/FV/OVMF_CODE.fd OVMF_CODE_4M.fd
rm -rf Build/Ovmf3264
build -a IA32 -a X64 -t GCC -p OvmfPkg/OvmfPkgIa32X64.dsc $F -DSMM_REQUIRE=TRUE "${P[@]}" -b RELEASE
cp Build/Ovmf3264/RELEASE_GCC/FV/OVMF_CODE.fd OVMF_CODE_4M.secboot.fd

这些标志取自该提交下的 debian/rules。 注意厂商字符串:他们的 Makefile 用双引号写它,make 的 shell 把引号剥掉,edk2 收到的是不带引号的,所以这里就这样传,再加一层引号会导致构建错误。 位图保持和他们一样的 400×120、8 位,启动画面上其他东西就都不会挪位。

两个镜像你都需要。 qemu-server 用 OVMF_CODE_4M.secboot.fd(要求 SMM 的那个构建)启动任何带 4M EFI 磁盘的 Q35 虚拟机,普通的 OVMF_CODE_4M.fd 只用于 i440fx24。 在当前的 Proxmox 上,几乎每台 UEFI 客户机跑的都是 secboot 那个。

这样构建,与 Proxmox 的源码树相比只改了位图和两个字符串,SMM 镜像启动起来是这样的:

由重新构建的 OVMF 镜像绘制的客户机启动画面,原本是 Proxmox logo 的地方显示着 Example Cloud 的 logo

客户机对自身固件的认知也随之改变,命令行上一个 -smbios 选项都不用:

在客户机内部读到的Proxmox 的 4.2026.08-1用同一源码树重新构建
固件厂商Proxmox distribution of EDK IIExample Cloud Ltd
固件版本4.2026.08-14.2026.08-1+ec1
“UEFI is supported”列出列出
ACPI 表BGRT、WSMT 等等同一组

这让构建时设定的厂商成为 UEFI 客户机更好的答案。 它是 OVMF 自己的类型 0,所以 UEFI 那一位原地不动,谁都不用记着 uefi=on。 类型 0 走 args 的那条路,是给 SeaBIOS 客户机的,以及给根本不重建固件的人的。

把新固件交给虚拟机的两种方式

qemu-server 把它找固件的位置写死了:OVMF.pm 里有一张 /usr/share/pve-edk2-firmware/ 下的路径表,按机器类型和 Secure Boot 选项索引,而虚拟机配置、GUI 或 API 里没有任何一个选项能选别的文件24。 剩下两条路。

构建品牌化 OVMF,以及交给虚拟机的两种方式Proxmox 的源码树pve-edk2-firmware 4.2026.08-1你的品牌Logo.bmp + 厂商字符串同样的构建,同样的标志OVMF_CODE_4M.fd + .secboot.fdA:在每个节点上 divert每台 UEFI 虚拟机都用上,不改虚拟机配置B:按虚拟机通过 args逐台虚拟机选择启用,Proxmox 的文件不动apt full-upgradeProxmox 的新固件装上了,你的还是旧的Post-Invoke 钩子版本不同,下次启动前重新构建
一次构建,两条进入的路。无论走哪条,下一次升级都会把 Proxmox 的新固件装在你的旁边,而你的原封不动,这就是底部那个钩子存在的原因。

路线 A:在每个节点上 divert。 告诉 dpkg,Proxmox 的两个代码镜像现在归到别处,然后把你的放到它们原来的位置:

D=/usr/share/pve-edk2-firmware
for f in OVMF_CODE_4M.fd OVMF_CODE_4M.secboot.fd; do
  dpkg-divert --package example-branding --add --rename --divert "$D/$f.distrib" "$D/$f"
  install -m 0644 "/root/branding/$f" "$D/$f"
done

从下一次启动起,这个节点上的每台 UEFI 虚拟机都用你的固件启动。 虚拟机配置一点都不用改。

路线 B:让选定的虚拟机指向它。 把镜像放在你自己的目录里,一次一台虚拟机地覆盖固件。 改用 -blockdev 之后,qemu-server 把代码镜像作为一个叫 pflash0 的块节点挂上,并在 -machine 里指名它24,而 QEMU 合并第二个 -machine 的方式和合并 -boot 一样,所以 args 可以加一个自己的节点,让 pflash0 改指向它:

args: -blockdev driver=raw,node-name=brandcode,read-only=on,file.driver=file,file.filename=/usr/local/share/example-branding/OVMF_CODE_4M.secboot.fd -machine pflash0=brandcode

这是绕远路测试过的。 先把 Proxmox 的 secboot 固件完全按 qemu-server 的方式挂成 pflash0,开着 SMM,然后在后面加上那行 args,客户机启动的是品牌化的镜像,logo 和厂商字符串都在,上面那张截图就是这么来的。

路线 A,divert路线 B,按虚拟机加 args
哪些虚拟机得到它节点上的每台 UEFI 虚拟机只有你设置了的虚拟机
Proxmox 的文件移到 .distrib不动
虚拟机配置不变一行 args,只有 root 能设
机器类型必须匹配已处理,两个镜像都 divert 了你的事:Q35 用 secboot 镜像
撤销dpkg-divert --remove --rename删掉那一行
迁移目标节点也必须 divert目标节点必须有这个文件

代码镜像大约 3.5 MB,而 pmxcfs 每个文件的上限是 1 MiB20。 所以它放不进 /etc/pve,无论走哪条路,都得放到每个节点上。 把虚拟机迁到一个没有它的节点上,根据路线不同会有两种结果之一:路线 A 下,Proxmox 自己的固件和 logo 又回来了;路线 B 下,虚拟机根本启动不了,因为 QEMU 打不开一个不存在的文件。

把你甩在后面的升级

diversion 是对付 logo 的正确工具。 固件不一样。

diversion 意味着 Proxmox 的升级再也到不了这个文件。 这正是你要的。 这也正是让 edk2 安全修复到不了你客户机的原因:Proxmox 4.2026.08-1 的变更日志开头就是“Besides many bug and security fixes”,接着列出了 CVE-2024-13745 的修复25,而一个基于上一版构建的品牌化固件,这些一样都没有。 没有任何东西告诉你。

这是测试过的,不是假设的。 在一个配了 Proxmox 软件源的 Debian trixie 容器里,装上 pve-edk2-firmware-ovmf 4.2025.05-3,两个代码镜像都 divert,然后把软件包升级到 4.2026.08-1:

升级之后结果
dpkg-query -W pve-edk2-firmware-ovmf4.2026.08-1
Proxmox 的新镜像装成了 OVMF_CODE_4M.fd.distrib,哈希变了
品牌化镜像没变,仍然基于 4.2025.05-3 构建
控制台上关于此事的任何提示什么都没有,直到加上下面这个钩子

所以加个钩子。 apt 在每次 dpkg 运行之后执行一串 DPkg::Post-Invoke 命令26。 记下你基于哪个 Proxmox 版本构建,每次之后比较一下:

cat > /usr/local/sbin/example-branding-check <<'EOF'
#!/bin/sh
built=$(cat /usr/local/share/example-branding/ovmf.built-from 2>/dev/null)
now=$(dpkg-query -W -f '${Version}' pve-edk2-firmware-ovmf 2>/dev/null)
[ "$built" = "$now" ] && exit 0
echo "W: branded OVMF was built from pve-edk2-firmware-ovmf $built, Proxmox now ships $now." >&2
echo "W: guests still boot the old firmware. Rebuild before the next VM restart." >&2
exit 0
EOF
chmod +x /usr/local/sbin/example-branding-check
echo 'DPkg::Post-Invoke { "/usr/local/sbin/example-branding-check"; };' \
  > /etc/apt/apt.conf.d/80example-branding

在同一次升级上,它打印出:

W: branded OVMF was built from pve-edk2-firmware-ovmf 4.2025.05-3, Proxmox now ships 4.2026.08-1.
W: guests still boot the old firmware. Rebuild before the next VM restart.

它故意以 0 退出。 Post-Invoke 命令失败的话 apt 会中止26,而一个品牌检查不值得让节点停在升级到一半的状态。 一句响亮的警告就够了。

还有一件事。 重启。 客户机只有在它的 QEMU 进程重启时才会用上新固件,所以重新构建之后,需要从 Proxmox 停机再启动,而不是从客户机内部重启,Proxmox 自己的固件更新到达运行中的虚拟机也正是这样。 只不过它们不需要你先记着去重新构建。

或者,别碰 Proxmox 的固件

到目前为止,每一种换 logo 的路线都要改固件,上一节就是这样做的账单。 有一种不用改,为了这篇文章做了原型。

QEMU 里的 PCI 设备可以带一个 option ROM,就是你用 romfile= 指定的任何文件27,OVMF 会运行它在里面找到的 EFI 驱动。 Proxmox 的构建不管它有没有签名都会运行:OVMF 把 PcdOptionRomImageVerificationPolicy 设成 0x00,也就是总是执行28。 OVMF 在启动设备选择的后期才画它自己的 logo29,并且只在 ReadyToBoot 时,也就是交给引导程序之前的那一刻,才构建 BGRT。 而 edk2 的 BGRT 驱动通过 EDKII_BOOT_LOGO2_PROTOCOL 接收替换图像,只要图像变了,就在 ReadyToBoot 时重建这张表30。

需要的就这么多。 驱动在 TPL_NOTIFY 上等待 ReadyToBoot,这比 BGRT 驱动自己的 TPL_CALLBACK 处理程序先运行,它清屏,画上自己的 logo,再把同一张图交过去。 构建出来是一个 8 KB 的文件,一行就挂上:

args: -device pci-testdev,romfile=/etc/pve/branding/brandrom.rom

8 KB 远在 pmxcfs 的 1 MiB 上限之内20,所以和 3.5 MB 的固件镜像不同,它可以放在 /etc/pve 里,跟着虚拟机去每一个节点。

它是对着 Proxmox 自己的固件测试的,直接取自 pve-edk2-firmware-ovmf 4.2026.08-1:OVMF_CODE_4M.secboot.fd,OVMF_VARS_4M.ms.fd 里预先注册了 Microsoft 的密钥,Q35 加 SMM,通过 Fedora 签名的 shim 启动,这样 Secure Boot 是开着的并且在强制执行:

从客户机里读到的不挂 ROM挂上 ROM
SecureBoot 变量11
屏幕上Proxmox 的 logoProxmox 的约 250 毫秒,然后是你的
BGRT 图像,400×120,位于 440,340Proxmox 的,SHA-256 be5afe4b…ROM 的,SHA-256 6c494576…
改动的固件文件无无

挂上 option ROM 后客户机从 BGRT 表里读回的图像:一个 Example Cloud 的 logo,标注着由 option ROM 绘制

关键在最后一行。 Proxmox 的固件没被动过,所以他们下一个安全版本会在下一次重启时到达你的客户机,上一节的事一件都不适用。

这不是免费的:

代价原因
Proxmox 的 logo 会显示大约四分之一秒OVMF 在任何 option ROM 驱动拿到屏幕之前就把它画了;只有重新构建才能避免
客户机多看到一个 PCI 设备,没有驱动ROM 必须挂在某个设备上,而 pci-testdev 是 QEMU 那个什么都不做的设备
类型 0 仍然写着 Proxmox厂商字符串是编译进去的;像上面那样,在 uefi=on 下通过 args 设置
只有 root 能做这是一行 args

而它底下的那个发现需要直说。 一个未签名的驱动,在一台注册了 Microsoft 密钥、强制执行 Secure Boot 的客户机上,在固件里运行了,因为 Proxmox 的 OVMF 不检查 option ROM。 在这里这是有用的。 但它也意味着,在这个固件上,Secure Boot 检查的是引导程序,而不是虚拟机硬件配置挂上去的随便什么东西。既然只有 root 能写 args,这就成了一个谁在你的节点上握有 root 的问题。

这是一个原型。 它在 QEMU 10.2.2 加 Proxmox 的固件上跑过,还没在 Proxmox 节点上跑过,下面给的是源代码,不是产品:

github.com/damo2929/RebrandPCIRom:option ROM 驱动、logo 转换器和容器构建。

Web 界面是两个软件包

Web 界面左上角的 logo 不在 pve-manager 里。 Workspace.js 请求的是一个前缀为 pwt 的 proxmoxLogoSvg 组件,它在 proxmox-widget-toolkit 里,Backup Server 和 Mail Gateway 也共用这个包31。 只有标签页图标在 pve-manager 里:

什么文件软件包
页头 logo,按 200×35 绘制/usr/share/javascript/proxmox-widget-toolkit/images/proxmox_logo.svgproxmox-widget-toolkit
浏览器标签页图标/usr/share/pve-manager/images/favicon.icopve-manager
128×128 图标,也用作触摸图标/usr/share/pve-manager/images/logo-128.pngpve-manager

三个都是普通文件,所以这是 dpkg-divert 的活儿,而且上一节的代价在这里完全不适用,因为 logo 没有安全修复可错过,一个节点还在提供上个月的 favicon,也不会让任何人的客户机更不安全。

divert() {
  dpkg-divert --package example-branding --add --rename --divert "$1.distrib" "$1"
  install -m 0644 "$2" "$1"
}
divert /usr/share/javascript/proxmox-widget-toolkit/images/proxmox_logo.svg /root/branding/logo.svg
divert /usr/share/pve-manager/images/favicon.ico   /root/branding/favicon.ico
divert /usr/share/pve-manager/images/logo-128.png  /root/branding/logo-128.png

在同一个容器里,对着真实的软件包测试过:

步骤结果
在 proxmox-widget-toolkit 5.2.9 上 divert,装上自己的 SVGProxmox 的 SVG 被改名为 proxmox_logo.svg.distrib
升级到 5.2.10自己的 SVG 仍在原处,Proxmox 的 5.2.10 版本在 .distrib 里
dpkg --verify proxmox-widget-toolkit没有报错,dpkg 知道这个 diversion
apt-get install --reinstall proxmox-widget-toolkit自己的 SVG 仍在原处
dpkg-divert --remove --renameProxmox 的原件回来了,逐字节一致

有两样仍然是 Proxmox 的。 页头图像画在一个固定的 200×35 框里,所以你的 SVG 要按这个形状画,否则会被挤扁。 另外 alt 文本写的是 Proxmox,图像链接到 https://www.proxmox.com,这两样都写在 JavaScript 组件里,而不是一个你能 divert 的文件里31。 要改它们,就得给一个压缩过的 bundle 打补丁,而它每次升级都会坏。 为了 alt 文本,不值得。

Proxmox 的许可证和商标对你有什么要求

Proxmox VE 采用 AGPL 第 3 版许可32,该许可证第 13 条是网络条款:“if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network … an opportunity to receive the Corresponding Source of your version”33。 换掉三张图片算不算修改了程序? 那得问律师。 省事的答案是把你的图片和 divert 脚本放到公开的地方,在登录页上放个链接。 一分钱都不花,问题也就了结了。

商标这边更清楚。 Proxmox 的媒体资料包写着“Don’t alter the logo or incorporate the logo or symbol into your logo”34。 所以用你自己的 logo 把他们的整个换掉,绝不要用他们 logo 的改色版或改造版,也别让 Proxmox 出现在你产品的名字里。

写上你的名字,就意味着由你来维护

给虚拟机打品牌很便宜。 几个 SMBIOS 字符串、一张 JPEG、一张位图、Web 界面里的三张图片:一个下午的活儿,大部分时间花在弄清楚东西都放在哪里。

维持住它才是真正的工作。 也正是常被跳过的那部分。

SMBIOS 字符串和启动画面会自己照顾自己,因为它们住在任何软件包都不会碰的配置里;Web 界面的 logo 也会自己照顾自己,因为 dpkg 已经被告知了它的存在。 固件不会。 从你把 logo 放进固件镜像的那天起,你就接管了别人发布流程中的一部分。Proxmox 构建、测试并发布带有安全修复的新固件,他们的客户在下一次升级时就能拿到,而你的客户要等你抽出空来重新构建才能拿到。

明知如此做出这个取舍,没问题。 一家托管公司,客户机启动的固件落后两个版本,因为 logo 比变更日志更重要,那它造出来的不是产品。 是一张贴纸。

如果启动画面上是你的名字,那它背后的固件就该由你保持最新,不管是谁写的。 没人会检查。 正因如此,才必须去做。


  1. UEFI Forum, ACPI Specification 6.6, §5.2.23 Boot Graphics Resource Table — “The Boot Graphics Resource Table (BGRT) is an optional table that provides a mechanism to indicate that an image was drawn on the screen during boot”。存档副本;在线页面对自动请求返回 403。 ↩︎

  2. Microsoft Learn, Boot screen components — “This is the standard interface that Windows uses to access the logo.” ↩︎

  3. Fedora Project, Changes/FlickerFreeBoot — “a new plymouth theme which incorporates the firmware’s bootsplash image”;Fedora 的 plymouth.spec 把 bgrt 设为默认主题。 ↩︎

  4. Debian, dpkg-divert(1), trixie — “File diversions are a way of forcing dpkg(1) not to install a file into its location, but to a diverted location.” ↩︎

  5. DMTF, DSP0134 System Management BIOS Reference Specification 3.10.0 — 类型 1 系统信息,类型 2 主板,类型 3 “the system’s mechanical enclosure(s)",类型 11 “free-form strings defined by the OEM”。 ↩︎

  6. Proxmox VE, qm.conf(5) — smbios1:“Specify SMBIOS type 1 fields”;args:“Arbitrary arguments passed to kvm … this option is for experts only.” ↩︎ ↩︎

  7. qemu-server, src/PVE/QemuServer.pm, the smbios1 format and command-line builder — 除 uuid 外的每个字段都匹配模式 [A-Za-z0-9+\/]+={0,2};设置了 base64 时值会被解码。 ↩︎

  8. pve-manager, www/manager6/Parser.js, printQemuSmbios1 — “smbios values can be arbitrary, so encode and mark config as such”。 ↩︎

  9. qemu-server, src/PVE/API2/Qemu.pm, clone — “auto generate a new uuid”,smbios1 的其他字段保留。 ↩︎ ↩︎

  10. QEMU, System Emulation, Invocation — 各类型的 -smbios 字段;-acpitable “For file=, take whole ACPI table from the specified files, including all ACPI headers”;-boot “Currently Seabios for X86 system support it.” ↩︎ ↩︎ ↩︎

  11. edk2-stable202608, OvmfPkg/SmbiosPlatformDxe/SmbiosPlatformDxe.c — 只有在遍历完 QEMU 的表之后 NeedSmbiosType0 仍然置位时,OVMF 才会添加它自己的类型 0。 ↩︎

  12. qemu-server, src/PVE/QemuServer.pm, custom args — args 被拆分后追加到命令行末尾。 ↩︎

  13. qemu-server, src/PVE/API2/Qemu.pm, config permission checks — smbios1 是硬件类选项,需要 VM.Config.HWType;兜底分支 “catches args, lock, etc.",并以 “only root can set” 报错退出。 ↩︎

  14. qemu-server, src/PVE/QemuServer.pm, the name option — format => 'dns-name'。 ↩︎

  15. qemu-server, src/PVE/QemuServer.pm, vmgenid — “notify the guest operating system when the virtual machine is executed with a different configuration (e.g. snapshot execution or creation from a template)"。 ↩︎

  16. qemu-server, src/PVE/QemuServer/Memory.pm — 内存 default => 512;QemuServer.pm 里 cores 和 sockets 默认为 1。 ↩︎

  17. qemu-server, src/PVE/QemuServer.pm, vm_start — 第 5457 行 lock_config,第 5581 行 exec_hookscript($conf, $vmid, 'pre-start', 1),第 5634 行 config_to_command 用的是同一个 $conf,中间没有重新加载。 ↩︎

  18. qemu-server, src/PVE/QemuServer.pm, -boot — menu=on,strict=on,reboot-timeout=1000,splash=/usr/share/qemu-server/bootsplash.jpg。 ↩︎

  19. edk2-stable202608, OvmfPkg/Library/QemuBootOrderLib/QemuBootOrderLib.c — OVMF 只从 -boot 读取 etc/boot-menu-wait,即 splash-time 的值,别的都不读。 ↩︎

  20. pve-cluster, src/pmxcfs/memdb.h — #define MEMDB_MAX_FILE_SIZE (1024 * 1024) // 1 MiB。 ↩︎ ↩︎ ↩︎

  21. SeaBIOS, src/jpeg.c — 在小端机器上 PIC 先写蓝色,第 946 行的 PIC_32 先写红色且没有字节序分支;ERR_NOT_SEQUENTIAL_DCT 和 ERR_NOT_YCBCR_221111 是仅有的两种被拒绝的格式。 ↩︎ ↩︎

  22. SeaBIOS, vgasrc/svgamodes.c — 模式 0x111 是 640×480、16 位,0x142 是 640×480、32 位。 ↩︎

  23. pve-edk2-firmware, debian/rules at 4.2026.08-1 — cp -a debian/Logo.bmp MdeModulePkg/Logo/Logo.bmp、PcdFirmwareVendor 字符串以及 OVMF 的构建标志。 ↩︎ ↩︎ ↩︎

  24. qemu-server, src/PVE/QemuServer/OVMF.pm — /usr/share/pve-edk2-firmware/ 下写死的固件表、SMM 的选择,以及 pflash0 块节点。 ↩︎ ↩︎ ↩︎

  25. pve-edk2-firmware, debian/changelog — 4.2026.08-1:“Besides many bug and security fixes … fix CVE-2024-13745”。 ↩︎

  26. Debian, apt.conf(5), trixie — “Pre-Invoke, Post-Invoke: This is a list of shell commands to run before/after invoking dpkg(1) … should any fail APT will abort.” ↩︎ ↩︎

  27. QEMU v11.0.3, hw/pci/pci.c — DEFINE_PROP_STRING("romfile", PCIDevice, romfile),每个 PCI 设备都有的属性。 ↩︎

  28. edk2-stable202608, OvmfPkg/OvmfPkgIa32X64.dsc — gEfiSecurityPkgTokenSpaceGuid.PcdOptionRomImageVerificationPolicy|0x00,Proxmox 构建所用的平台文件。 ↩︎

  29. edk2-stable202608, OvmfPkg/Library/PlatformBootManagerLib/BdsPlatform.c — BootLogoEnableLogo (),从 PlatformBootManagerAfterConsole 调用。 ↩︎

  30. edk2-stable202608, BootGraphicsResourceTableDxe.c — 第 239 行的 SetBootLogo2 复制图像;第 417 行的 ReadyToBoot 处理程序 “If BGRT data change happens” 就卸载并重新安装这张表。 ↩︎

  31. proxmox-widget-toolkit, src/Logo.js — proxmoxLogoSvg,200×35,alt: 'Proxmox',链接到 proxmox.com;由 pve-manager Workspace.js 以 prefix: 'pwt' 调用。 ↩︎ ↩︎

  32. Proxmox VE wiki, FAQ — “Proxmox VE code is licensed under the GNU Affero General Public License, version 3.” ↩︎

  33. GNU Affero General Public License v3, §13 Remote Network Interaction — 正文中已完整引用。 ↩︎

  34. Proxmox, Media kit — “Don’t alter the logo or incorporate the logo or symbol into your logo.” ↩︎