南瓜丶奇迹师先把这次的坑说清楚：一个客户的VCF 9.0.0环境，UI里点升级到9.0.1，任务一跑起来就卡在预检查阶段，报错信息直指“ESXi镜像找不到”。运维同事第一反应是想着去补个vCenter层面的ESXi补丁，实际上完全不是这么回事。VMware Cloud Foundation从9.0.0升到9.0.1，涉及到的ESXi镜像问题本质上属于SDDC Manager的LCM（生命周期管理）bundle选型与depot同步问题。这篇文章就把我在处理这个问题时的整个排查链路、根因定位、手动补救步骤，以及升级完成后的收尾检查完整整理出来，给正在做VCF 9.0.x升级，或者准备做离线升级的同行一个可以直接参考的操作手册。
本文覆盖的内容包括：VCF升级任务中ESXi镜像的定位方式、bundle在depot中的存储逻辑、为什么目标镜像明明“存在”却提示找不到、如何用SDDC Manager的命令行工具把缺失的ESXi镜像手动导入，以及升级完成后的版本校验和遗留文件清理。不管是小白还是已经搞过几次VCF升级的工程师，按这个思路排查，基本能少走一半弯路。
1. 先搞清楚：VCF升级时“ESXi镜像”到底指的是什么
很多第一次做VCF升级的人都会在“ESXi镜像找不到”这个问题上卡住，根本原因不是操作不对，而是对这个概念的理解有偏差。VCF升级和传统意义上的vCenter通过Update Manager打ESXi补丁，完全是两套逻辑。
1.1 LCM机制与bundle的概念
VCF 9.0.1的升级动作，核心是SDDC Manager的LCM服务在驱动。SDDC Manager会先从depot（软件仓库）里拉取升级所需的bundle，bundle里面包含的是一个升级路径上所有组件的更新包，比如vCenter Server、NSX、VCF平台本身的组件，以及最重要的ESXi镜像。这里的“ESXi镜像”不是一个简单的ISO安装包，而是对应某个特定build号的ESXi离线镜像zip包，也就是你在Broadcom支持门户下载的那种“VMware vSphere ESXi Offline Bundle”。
VCF升级时，LCM会根据目标版本解析出一个依赖矩阵：VCF 9.0.1的platform bundle会要求ESXi升级到某一个具体build号。如果depot里没有这个build的ESXi bundle，或者有bundle但build号与VCF 9.0.1期望的不匹配，就会在预检查阶段给出“找不到ESXi镜像”之类的报错。
1.2 在线depot和离线depot的区别
处理这个报错之前，先确认你的环境是哪种depot模式：
- 在线depot：SDDC Manager直接连Broadcom的官方软件仓库，升级时自动同步bundle。这种情况一般不会缺镜像，除非网络代理配置有问题，或者账户凭证过期导致同步中断。
- 离线depot：也就是我这次实际遇到的环境，SDDC Manager通过共享仓库路径（如NFS）或本地目录存放提前下载好的bundle文件。离线模式下，升级前置条件完全依赖手动导入的bundle是否齐全，只要漏下任何一个镜像，预检查就直接失败。
我这次处理的环境就是离线depot。VCF 9.0.0版本刚部署完，bundle仓库里只有当时部署用的ESXi 8.0镜像，9.0.1升级路径所需的ESXi版本还没有下载导入，UI上点升级，预检查一扫描完就报“未在depot中找到匹配的ESXi镜像”。
1.3 升级路径中镜像匹配的底层逻辑
VCF中bundle之间不是简单的“版本号相同就能用”的关系。LCM在匹配时，会检查platform bundle中的esxiImage属性，比如要求ESXi版本为8.0 U3d（build XXXXXXXX）。而depot中已有的ESXi bundle如果build号不一致，哪怕大版本相同，LCM也认为不匹配。
这就解释了为什么很多人的报错信息里，明明能看到depot中有一堆ESXi镜像，但升级预检查依然卡住。因为他们只有一个旧build，没有目标build。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 报错现象、日志位置与初始判断
先说我这次遇到的具体表现，大家可以对照一下。
2.1 UI层面的报错表现
在SDDC Manager的UI中，点击升级到9.0.1后，升级任务会进入Pre-check阶段，几秒钟后任务失败，UI弹出版本报告信息，大致意思是：
The ESXi image bundle required for the platform upgrade is not available in the depot. Please upload the required ESXi bundle and retry.
有经验的工程师都知道，UI上的提示往往只是冰山一角，很多关键细节必须去日志里翻才能看到。所以第二步永远是看日志。
2.2 日志定位
LCM相关日志位于SDDC Manager的/var/log/vcf/lcm/lcm.log，每轮升级任务运行时，可以通过时间戳或者transaction id过滤关键报错。我在lcm.log里看到的具体报错类似于：
code复制2025-xx-xx XX:XX:XX,XXX ERROR [lcm-esx-upgrade]
No ESXi image found matching required version: 8.0.3, build 23277880.
Searched bundle types: [VMWARE_ESXI], status: [DOWNLOADED, READY].
这里有两个关键信息：一是期望的ESXi版本和build号；二是扫描范围是VMWARE_ESXI类型的bundle。换句话说，LCM已经在depot里找过ESXi类型的bundle了，但没找到匹配的build。
2.3 初始判断：排除网络和凭证问题
在动手补镜像之前，先排除两个容易混淆的方向：
- 网络连通性：如果是在线depot，检查SDDC Manager到Broadcom仓库的网络、443端口和代理设置。离线depot直接跳过这步。
- depot凭证：如果LCM的depot配置是online模式，但账户凭证过期，会报“download failed”而不是“not found”。这类报错的排查方向完全不同。
我这次确认环境是离线depot，网络与凭证问题不存在，所以方向直接锁定在“depot里没东西，或者有但版本不匹配”。
3. 逐层排查：从bundle列表到depot状态
既然方向明确，接下来的操作就变成：把bundle列表拉出来，看看到底缺什么。
3.1 查询depot中现有的bundle列表
SDDC Manager上可以用API或者CLI方式查询bundle列表。我习惯用CLI，因为输出更直接，适合在排查时反复执行。
VCF 9.0.x的SDDC Manager上，可以直接用LCM CLI查询：
bash复制/opt/vmware/vcf/lcm/lcm-app/bin/vcf bundle list
如果命令路径在你的环境里稍有不同，可以通过find /opt/vmware/vcf -name "vcf*"确认。执行后输出中会包含bundle的名称、类型、版本、build号和当前状态。
我这次看到的情况是：depot中的bundle列表很少，只有VCF 9.0.0初始部署时的那几个bundle，ESXi相关的只有一个旧build的离线包，9.0.1目标版本对应的ESXi bundle完全没有。
3.2 确认LCM depot的可用状态
接下来检查depot状态，这是很多人容易忽略的一步。通过API或者/opt/vmware/vcf/lcm/lcm-app/bin/vcf depot status可以查看depot类型、路径和当前状态。离线depot的状态必须为READY，如果你配置了共享路径但路径失效，状态会是UNREACHABLE，这种情况下无论你怎么补bundle，LCM都扫描不到。
确认depot状态无误后，再检查离线bundle存放目录：
bash复制ls -lh /var/lib/vmware/vcf/steam/offline_bundles/
正常情况下，已经导入的bundle文件会以zip形式出现在目录下或者通过LCM的元数据注册表管理。如果目录里空无一物，说明之前的bundle根本没有被正确导入。
3.3 核对目标ESXi build号
这一步是整个排查中最关键的部分。在升级VCF 9.0.0到9.0.1之前，需要明确知道9.0.1的platform bundle到底要求哪个ESXi build号。
最靠谱的方法是在VCF的升级预检查报告中查看，或者在Broadcom的支持门户中查询VCF 9.0.1的兼容性矩阵。兼容性矩阵上会列出VCF 9.0.1支持的ESXi版本和build号，对照lcm.log中报错要求的版本，确定要下载的镜像。
提示：不要凭经验猜测build号。VCF对ESXi build号的匹配很严格，下载错一个patch级别，导入后照样报找不到镜像。
3.4 排查的结果汇总
我这次的排查结论汇总如下：
| 检查项 | 结果 | 说明 |
|---|---|---|
| depot类型 | offline | 使用本地bundle仓库 |
| depot状态 | READY | 路径可达，扫描正常 |
| 现有bundle列表 | 仅9.0.0部署相关 | 缺9.0.1目标ESXi镜像 |
| 期望ESXi版本 | 8.0 U3d build xxxxxxxx | 来自lcm.log报错 |
| 现有ESXi版本 | 旧build | 与期望build不匹配 |
结论很清晰：必须手动导入目标build的ESXi离线镜像bundle。
4. 手动导入缺失的ESXi镜像：完整操作步骤
确认了缺失的具体镜像后，接下来的操作就是手动补救。很多人到了这一步会犹豫，担心手动导入会不会破坏LCM自身的bundle管理逻辑。实际并不会，VCF本身就提供了导入离线bundle的受支持路径，只是UI层面没有入口，需要通过CLI完成。
4.1 下载正确的ESXi镜像
登录Broadcom支持门户，找到VCF 9.0.1对应的ESXi镜像下载页。注意要下载的是离线bundle格式的zip包，一般是VMware-ESXi-8.0U3d-xxxxxxxx-offline-bundle-xxxxxxxx.zip这类命名规则，不要下载ISO格式。
下载之前确认两个信息：
- VCF 9.0.1 compatibility matrix列出的ESXi build号
- 你环境中ESXi当前所处的版本大版本（VCF 9.0.x要求ESXi 8.x系列）
如果下载的zip包build号与lcm.log中期望的不一致，导入后依然无效，我就遇到过因为下载成U3c而不是U3d导致重复操作的场景。
4.2 上传zip包到SDDC Manager
将下载好的zip包上传到SDDC Manager的临时目录，比如/tmp/esxi-bundle/：
bash复制scp VMware-ESXi-8.0U3d-xxxxxxxx-offline-bundle-xxxxxxxx.zip \
root@sddc-manager-ip:/tmp/esxi-bundle/
文件不大，一般就几百MB到1GB左右。上传完成后确认校验值是否与Broadcom提供的MD5一致，这点在离线环境尤其重要，避免传输过程中文件损坏导致导入失败。MD5校验命令：
bash复制md5sum VMwar-ESXi-8.0U3d-xxxxxxxx-offline-bundle-xxxxxxxx.zip
4.3 导入bundle到LCM depot
接下来执行导入操作。在SDDC Manager上切换到LCM目录，运行导入命令：
bash复制cd /opt/vmware/vcf/lcm/lcm-app/bin
./vcf bundle import --bundle-type esxi --path /tmp/esxi-bundle/VMwar-ESXi-8.0U3d-xxxxxxxx-offline-bundle-xxxxxxxx.zip
命令执行后，LCM会解析zip包中的元数据，将ESXi bundle注册到depot中。导入过程通常需要几分钟，日志中会出现bundle import completed successfully或类似信息。
如果没有找到vcf bundle这条命令，另一个备选方案是通过LCM的REST API导入：
bash复制curl -k -u admin:password \
-F "file=@/tmp/esxi-bundle/VMwar-ESXi-8.0U3d-xxxxxxxx-offline-bundle-xxxxxxxx.zip" \
https://localhost:443/v1/bundles
无论使用哪种方式，导入完成后都可以重新执行bundle list确认新bundle已经出现。
4.4 触发depot重新扫描并验证
有些版本在导入bundle后不会立即触发depot的元数据刷新，需要手动触发一次扫描。这一步可以通过LCM CLI或者SDDC Manager的UI完成。UI中的操作路径是：Lifecycle Management -> Depot -> Sync，点击同步即可。
同步完成后再次执行：
bash复制/opt/vmware/vcf/lcm/lcm-app/bin/vcf bundle list
确认新导入的ESXi bundle状态为READY，并且bundle类型是VMWARE_ESXI。此时bundle列表中应该出现与9.0.1目标匹配的ESXi镜像条目。
4.5 重新发起升级任务
从检查到导入再到验证，整个补救动作完成。回到SDDC Manager的UI，重新发起VCF 9.0.1升级任务。这次预检查阶段不会再报“ESXi镜像找不到”，任务会顺利进入下一步。
我这边在执行升级任务时，预检查一次性通过，升级任务进入了download和validate阶段，整体流程没有再次受阻。
5. 升级跑起来之后的观察点与收尾检查
bundle补上、预检查通过，这只是走通了一半。VCF升级任务真正跑起来之后，还有几个地方需要盯着，毕竟升级到一半再发现问题比预检查时发现问题要麻烦得多。
5.1 升级过程中需要关注的日志节点
升级任务的执行过程大致分为几个阶段：download（下载bundle）、extract（解压）、precheck（预检查）、apply（应用到各组件）、rolling（滚动升级ESXi集群）、postcheck（后置检查）。
每个阶段在lcm.log中都有对应的阶段标识，建议在升级运行期间用tail -f持续关注日志滚动：
bash复制tail -f /var/log/vcf/lcm/lcm.log | grep -E "ERROR|WARN|stage|esx-upgrade"
最容易出问题的阶段是apply之后的rolling环节。ESXi集群会在维护模式下逐台升级，如果某台主机没有进入维护模式，LCM会暂停当前批次。这种情况不是本文的报错，但值得一并提醒。
5.2 验证ESXi版本和build号是否真的到位
升级全部完成后，到vCenter Server里确认每台ESXi主机的版本和build号是否达到了VCF 9.0.1兼容矩阵中的目标值。可以通过vCenter UI查看，也可以用PowerCLI批量确认：
powershell复制Get-VMHost | Select-Object Name, Version, Build
确认所有主机build号一致，且与LCM报错中要求的build号一致，这一步才算完全闭环。
5.3 清理临时文件与安全注意事项
导入bundle时使用的临时目录，在升级完成后可以清理掉。离线depot中的bundle文件本身要保留，因为后续VCF的补丁升级或者主机修复操作还会依赖它们。只清理/tmp下自己上传的zip副本，避免占用SDDC Manager系统盘空间。
SDDC Manager的系统盘空间是比较脆弱的，很多VCF环境的故障都源自/分区被日志和bundle文件撑满。升级前最好也顺手检查一下磁盘使用率：
bash复制df -h /
如果系统盘剩余空间不足20%，建议先做日志归档和清理，再发起升级任务，否则bundle解压阶段很可能直接失败。
5.4 升级后depot的维护建议
这次升级结束后，我顺手做了一轮depot中所有bundle的盘点，确认当前depot里包含了VCF 9.0.1所需的全套bundle，并记录了bundle名称、版本、build号和导入时间，方便后续排查时直接对表。
另外，如果环境是离线depot模式，建议每次升级前都在Broadcom门户确认好目标版本对应的所有bundle清单，一次性下载齐全再开始操作，避免升级过程中反复中断。
6. 这次踩坑之后，我整理的VCF升级前检查清单
经历了一次“ESXi镜像找不到”的半夜紧急处理，后续凡是再做VCF升级，我都会先跑一遍下面的检查，可以帮同行们少走弯路。
6.1 离线depot环境必查项
离线环境是所有“镜像找不到”类问题的重灾区。升级前挨个确认：
- [ ] 目标VCF版本对应的platform bundle已导入
- [ ] 目标ESXi build镜像已导入
- [ ] vCenter Server对应版本的镜像或bundle已导入（如果升级范围包含vCenter）
- [ ] NSX相关bundle已导入（如果环境中部署了NSX）
- [ ] depot状态为
READY，共享存储路径可正常读写
每一项都可以通过vcf bundle list快速确认，整个检查过程不超过十分钟，但能避免一次升级中断的代价。
6.2 bundle清单的维护习惯
VCF升级不像普通软件升级那么简单，bundle的依赖关系是很严格的。建议每半年检查一次depot中的bundle清单，记录到一个表格里维护。我自己的习惯是在环境交付时建立一份bundle inventory，包含字段：
- bundle名称
- bundle类型
- 版本号
- build号
- 导入日期
- 备注（用于哪个VCF版本升级）
有了这份表，升级前对照目标版本的兼容矩阵，一眼就能看出缺哪个包。
6.3 关于在线depot的一个提醒
如果环境用的是在线depot，理论上不会出现“ESXi镜像找不到”的问题，因为LCM会自动拉取目标bundle。但有一种情况例外：SDDC Manager配置了代理，代理缓存了旧的depot响应，导致新bundle的元数据无法刷新。这种时候报文可能也是“not available”，但解决方式是刷新代理缓存或者临时绕过代理同步，而不是手动补镜像。
一句话总结排查思路：先确认depot类型，再确认bundle列表，最后对照build号。只要这三个环节不出错，VCF 9.0.1升级里的ESXi镜像问题基本都能在十分钟内定位，半小时内解决。希望这次记录能帮到正在和VCF升级较劲的同行，省掉半夜翻日志的辛苦。