宋慈面前耍柳叶刀最近把一个测试环境的 VMware Cloud Foundation 从 9.0.0 往 9.0.1 升，结果卡在一个看起来很简单、实际却很绕的报错上：界面提示找不到 ESX 镜像。第一反应是“Bundle 没传上去”，但打开 SDDC Manager 的 Bundle 列表，文件明明就在那里。反复折腾了一天才把整条链路里和镜像相关的部分全部捋顺，最后发现根因不在上传环节，而是 VCF 的 BOM 与本地 depot 里 Bundle 解析结果不匹配，导致 SDDC Manager 在预检查阶段没有把对应 ESXi 镜像纳入可选项。这篇就当一次完整排障记录，把“镜像找不到”背后的机制、排查顺序和实际操作都写清楚，给正打算做 VCF 9.0.x 升级的同学一个可直接照做的参考。
1. 先把问题说清楚：“找不到 ESX 镜像”到底卡在哪一步
1.1 我当时的操作路径与报错位置
这次升级大体分为三个阶段：把 VCF 9.0.1 的离线 Bundle 上传到 SDDC Manager，检查 Bundle 状态，然后从 Lifecycle Management 里发起管理域和工作负载域的升级。
到了第三步，UI 里能识别出 VCF 9.0.1 的升级包，也能勾选工作负载域，但预检查阶段直接弹出一条类似 “No ESXi image found / 找不到匹配的 ESXi 镜像” 的错误。当时第一反应是检查上传的 Bundle 是否完整、状态是否正常，结果 Bundle Management 里明明显示这个包里已经包含 ESXi 组件，可升级向导里就是匹配不上。
这里必须先把问题定位准：报错不一定发生在“上传 Bundle”的界面，更多时候发生在“升级预检查”阶段。两个入口的排查思路完全不一样。如果只是上传后 Bundle 状态异常，通常属于导入环节；如果 Bundle 状态正常但升级向导找不到镜像，那就是 VCF 版本匹配或镜像仓库解析的问题。
1.2 VCF 里的 “ESX 镜像” 和 Linux ISO 完全不是一回事
很多第一次接触 VCF 的同学会拿管理 Linux 发行版镜像的经验来套，认为只要有个 ESXi ISO、传到某个路径就能升级。但 VCF 里的 ESXi 镜像并不是传统意义上的安装 ISO，而是以 Bundle 形式存在的软件包，里面不仅有 ESXi 的基础镜像，还带了各种驱动、VIB 和元数据文件。SDDC Manager 收到 Bundle 后要做解析、校验、入库，生成可供 vSphere Lifecycle Manager 使用的镜像。
换句话说，你手上有一个 9.0.1 的官方 Bundle，不代表 SDDC Manager 已经把它里面那颗 ESXi 镜像“消化”成可用状态。上传只是第一步，后续的 metadata 解析、BOM 对照、版本匹配才是决定“能不能找到镜像”的关键。
1.3 “找不到”其实分三种情况
排查过程中我逐步把问题拆成了三类，方向对了才不会瞎折腾：
第一种是 Bundle 本身没有完整导入，SDDC Manager 的 depot 目录里没有能识别的 ESXi 组件。第二种是 Bundle 已经导入，但其中的 ESXi 组件版本、build number 与 VCF 9.0.1 官方 BOM 不一致，SDDC Manager 认版本号，不认文件名。第三种是 SDDC Manager 和 vCenter 之间的镜像推送链路出了问题，SDDC Manager 这边能看到目标镜像，但目标 vCenter 的 vLCM 镜像仓库里根本没有这个 ESXi 镜像。
我这次属于第二种，名字对、版本不对，所以升级向导宁可直接报“找不到”，也不会拿一个不匹配的构建号硬上。
提示：见到“镜像找不到”先别重传文件，先判断是哪一类。三者对应的处理方式差别很大，盲传三五遍 Bundle 只会浪费时间。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 升级前最容易被忽略的三个前置问题
2.1 版本号对了，build number 不一定对
VCF 是一个组合产品，9.0.1 这个版本号下面包含的 vCenter、ESXi、NSX 组件都有自己独立的版本和 build number。SDDC Manager 在升级前会拿着官方 BOM（Bill of Materials）逐项核对，也就是说它不光要看到“ESXi 8.x”，还要看到那个组件标注的精确 build number 是否符合预期。
我这次出的问题就是历史后台任务里残留了一个旧的 ESXi 组件包，名字看起来差不多，但 build number 比官方 BOM 要求的旧了一截。SDDC Manager 在解析时只认 BOM 里的构建号，本地 depot 里没有匹配项，于是直接判定“ESXi 镜像不存在”。
解决办法倒不复杂：去 Broadcom 支持门户下载 VCF 9.0.1 对应的完整离线 Bundle，不要手动从 vCenter 或单独下载的 ESXi 离线包凑数。VCF 升级必须走同一套 Bundle，否则很容易出现这种局部版本不匹配的问题。
2.2 Bundle 导入完成不等于导入成功
SDDC Manager 的 Bundle Management 界面里，一个 Bundle 会经历几种状态：上传中、解析中、可用、失败。很多人在“上传进度到 100%”之后就认为万事大吉，实际上上传完成后 SDDC Manager 还要做完整性校验和解压分析。如果文件在传输过程中损坏，或者磁盘空间不够导致解压中断，Bundle 可能显示为失败甚至停留在某个中间状态。
状态不正常的 Bundle 不会进入可被升级向导调用的“镜像仓库”。这一点在界面上很容易被忽略，因为 Bundle 名称依然会出现在列表里，只是状态列没有显示 Ready。我建议在发起升级前，先到 Bundle Management 里确认目标 Bundle 的状态是 Ready 或 Available，并且点进去看一下 component 列表里是否包含 ESXi 组件。
2.3 SDDC Manager 和 vCenter 的磁盘余量
VCF 升级过程对空间的要求比想象中要高。Bundle 上传后要解压暂存，SDDC Manager 要把 ESXi 镜像推送并转存到 vCenter 的影像仓库，中间会同时存在几份副本。如果看到“镜像找不到”的同时还伴随 “Upload failed” 或 “Proxy error”，大概率是磁盘满了，尤其是 vCenter 的存储分区。
最简单的做法是升级前先用 df -h 检查 SDDC Manager、vCenter、各 ESXi 主机相关的存储位置，保留至少 20%–30% 的余量作为安全阈值。这个看似不起眼的检查，实际能省掉很多莫名其妙的排障时间。
3. 镜像与 Bundle 的核心逻辑：为什么 VCF 不直接拿 ISO 升级
3.1 Bundle 才是 VCF 升级的“唯一入口”
VCF 里升级任何组件，不管是 vCenter 也好、ESXi 也好、NSX 也好，都需要通过 SDDC Manager 统一编排。离线环境下，官方会把预打包好的组件以 Bundle 形式发布，比如 VMware Cloud Foundation 9.0.1 离线包。这个 Bundle 内部通常包含 SDDC Manager 自升级组件、vCenter 升级组件、ESXi 镜像、NSX 升级组件等若干子项。
SDDC Manager 要做的第一件事是解析这个 Bundle，把里面的子组件按类型拆开，放入自己的软件仓库。ESXi 组件被单独提取出来后，会进一步被处理成 vLCM 映像格式，然后才能在后续升级中推送给目标 vCenter 和集群。整个过程不是简单复制文件，SDDC Manager 需要同步更新自己的元数据库，记录“当前版本 9.0.0 的哪些集群可以使用哪一版镜像升级到 9.0.1”。
3.2 manifest 与 BOM 如何影响“镜像是否可见”
Bundle 内有一个描述文件，记录着每个组件的名称、版本、build number、适用场景，这个文件会被 SDDC Manager 拿来与官方 BOM 做对照。如果某个组件缺失，或者 build number 不匹配，升级向导就不会在可选项里展示对应的镜像。
这也是为什么很多人纳闷“文件都在，为什么系统说没镜像”。SDDC Manager 不是按文件名找镜像的，而是按 manifest 里的元数据索引镜像。文件名再像目标版本，只要内部记录的 build number 不对，它在系统里就是另一个东西。
3.3 从 SDDC Manager 到 vCenter 的镜像推送链路
还有一层容易忽略：升级向导最终不是在 SDDC Manager 上直接安装 ESXi，而是把 ESXi 映像交给目标 vCenter 的 vSphere Lifecycle Manager。SDDC Manager 会先把 ESXi 映像从自己的镜像仓库推送到 vCenter，再由 vCenter 按集群的 desired state 执行主机升级。
因此，“镜像找不到”也可能发生在 vCenter 侧。如果管理域中的 vCenter 还没有升级到 VCF 9.0.1 所要求的版本，它可能无法正确识别新镜像；或者 vCenter 的 vLCM 映像仓库没有同步到 SDDC Manager 推送过来的镜像。此时哪怕 SDDC Manager 本地一切正常，升级向导也会因为拿不到反馈而报错。
提示：遇到“镜像找不到”，要多问一句“是 SDDC Manager 找不到，还是目标 vCenter 找不到”，这决定了你后续是查本机 Bundle，还是需要先处理 vCenter 升级顺序。
4. 镜像修复完整实操：从版本核对到真正把升级跑通
4.1 第一步：用官方 BOM 核对当前环境版本与 build number
不要急着删除或重新上传任何内容。先去 Broadcom 支持门户找到 VCF 9.0.1 的 Release Notes 和 BOM 文档，记录目标版本要求的关键组件版本号，尤其是以下三项：
- SDDC Manager 版本号和 build number
- vCenter Server 版本号和 build number
- ESXi 版本号和 build number
接着登录 SDDC Manager，在 Settings 或 System 页面里查看当前各组件的实际版本和 build number。如果当前 vCenter 或 ESXi 与 BOM 要求差距太大，升级向导可能在预检查阶段就终止，而不是等到报“镜像找不到”。先确认基线版本符合要求，再做后续处理。
4.2 第二步：重新获取一套完整的 VCF 9.0.1 离线 Bundle
这一步建议直接使用官方下载的完整离线包，避免用之前缓存的半截文件。下载后计算校验值，与官网给出的哈希值做对比，确保文件没有在传输过程中损坏。推荐在本地终端执行 sha256sum 或 sha256 命令：
bash复制sha256sum VMware-Cloud-Foundation-9.0.1.0-xxxx.tar.gz
我这里出现问题的根因就是本地曾残留过同名但 build number 偏旧的 Bundle，所以这一步要对齐的不只是版本名，还有完整 build number。
4.3 第三步：检查磁盘空间并上传 Bundle
在 SDDC Manager 的 Lifecycle Management 或 Bundle Management 界面中，选择导入 Bundle，上传刚下载的离线包。上传过程会根据网络环境持续一段时间，期间不要刷新页面或中断连接。上传完成后系统会自动进入校验与解析状态，通常需要等待几分钟。
如果界面上传一直不稳定，官方文档里也提供了通过 API 或命令行上传的方式。不同版本的 SDDC Manager 对命令行的支持略有差异，登录 SDDC Manager 后执行 vcf bundle 相关子命令，通过 --help 查看当前环境的具体参数即可。总之不要跳过校验步骤，直接看 Bundle 最终状态是 Ready 才算通过。
4.4 第四步：确认 Bundle 内部的 ESXi 组件状态
打开刚导入的 Bundle 详情，逐项检查 component 列表。正常情况下应该能看到类似 ESXi、vCenter Server、NSX 等条目。重点看 ESXi 组件的版本号和 build number 是否与官方 BOM 一致。
如果组件列表里 ESXi 条目缺失，或者状态显示 Failed，说明 Bundle 上传不完整或者解析过程有问题。此时先把该 Bundle 移除，再重新上传一次。不要尝试手动修改 Bundle 内部文件，官方包有签名，改动后反而会导致校验失败。
4.5 第五步：触发一次扫描，确认升级向导能识别镜像
回到 Lifecycle Management 的升级界面，重新发起一次预检查或扫描，观察目标版本 9.0.1 是否出现在可用列表，ESXi 镜像是否被识别。如果这一步成功，那么之前报“镜像找不到”的根因基本排除，可以继续走正式升级。
如果扫描后依然找不到镜像，需要 ssh 登录 SDDC Manager，去日志目录里看最原始的报错信息。不同版本的 VCF 日志路径会有差异，通常在 /opt/vmware/vcf 目录结构下。搜索关键词找 “bundle” “esxi” “image not found” 或“depot”，定位到底是 SDDC Manager 本地解析失败，还是在调用目标 vCenter 时失败。
4.6 第六步：按正确顺序完成正式升级
升级顺序不能乱，原则上先管理域、后工作负载域。管理域中的 vCenter 和 ESXi 会先被升级，之后 SDDC Manager 才能通过新的 vCenter 实例去升级工作负载域。如果尝试跳级或反过来升级，很容易在某个环节因镜像版本不匹配而中断。
正式升级期间尽量不要在界面上并发执行其他生命周期管理操作，也不要做 vCenter 层面的手动更新。VCF 编排任务对状态很敏感，手动干预可能导致 SDDC Manager 记录的期望状态与实际状态不一致，后续排查更麻烦。
5. 常见报错提示与排查操作速查表
5.1 “镜像找不到”常见场景对照表
下面这张表是我在这次升级以及之前几次 VCF 版本升级里遇到的典型情况，按报错现象、主要原因和处理动作整理，可以直接当成排查手册用。
| 报错现场 | 主要原因 | 推荐处理动作 |
|---|---|---|
| Bundle 列表中可见，但升级向导里找不到 ESXi 镜像 | Bundle 内部组件解析不完整，或 build number 与 BOM 不匹配 | 核对官方 BOM，重新下载并导入完整 Bundle |
| Bundle 状态 Failed 或 Stuck | 上传文件损坏、磁盘空间不足或中断 | 删除该 Bundle，清理空间后重新上传 |
| 升级预检查提示 vCenter 版本不兼容 | 管理域 vCenter 未先升级到 BOM 对应版本 | 先完成管理域升级，再处理工作负载域 |
| vCenter 的 vLCM 映像列表里没有目标 ESXi 版本 | SDDC Manager 未把镜像推送到该 vCenter，或推送中断 | 检查 SDDC Manager 到 vCenter 的连通性，重新触发扫描 |
| 集群只有部分主机报错“找不到镜像” | 集群内存在异构或不兼容主机，vLCM desired state 无法覆盖所有主机 | 检查主机版本和硬件兼容性，先移除不支持的主机 |
这张表的核心思想只有一个：先判断问题出在哪一层，再决定执行什么命令。不要一上来就重装 vCenter 或重导 ESXi 镜像，那样只会引入更多变量。
5.2 一个真实的修复过程记录
这次环境里最终修复过程是这样的：我重新从官方下载了 VCF 9.0.1 对应的完整 Bundle，sha256 校验通过后上传到 SDDC Manager。等到 Bundle 状态变为 Ready，再次打开升级向导，发现 9.0.1 的 ESXi 镜像已经出现在可用列表里。随后先升级管理域，管理域里的 vCenter 和 ESXi 完成升级后再处理工作负载域，整个流程顺利跑通。
回看整个过程，浪费最多时间的其实是在确认“为什么旧的 Bundle 文件还在且显示正常”。后来查看组件详情才发现旧 Bundle 里 ESXi 的 build number 不对，只是因为同版本号覆盖场景相似，界面上看起来很有迷惑性。
5.3 日志排查入口与几个建议收集的信息
遇到同样问题，先收集以下几类信息，能大幅缩短排查时间：
- VCF 版本：SDDC Manager 当前版本和升级目标版本
- 各组件 build number：vCenter、ESXi、NSX 分别记录
- Bundle 上传时间和状态：Bundle Management 里显示的状态变化
- 报错截图：升级预检查时的完整提示
- SDDC Manager 日志：重点找包含 “bundle” “depot” “image” 的日志行
有了这些信息，无论是自行排查还是联系官方支持，都能快速定位到具体环节。在日志里搜索关键词时不要只搜 “esxi”，也会漏掉很多有效信息；建议同时搜 “image” 和对应版本的 build number 片段。
6. 操作中容易忽略的隐藏坑
6.1 vCenter 升级顺序不对会导致“镜像同步失败”
升级管理工作负载域时，如果管理域里的 vCenter 还没升级到位，SDDC Manager 去调用 vCenter 的 vLCM 接口时就会失败。vCenter 版本的 API 行为在不同版本之间有差异，旧版 vCenter 甚至可能不识别新版 ESXi 映像的格式，直接返回空列表。
我遇到过一种情况：SDDC Manager 本地 depot 一切正常，但目标 vCenter 上死活看不到 ESXi 新镜像。后来发现是因为管理域里的 vCenter 还停留在旧版本，VCF 升级向导先升级了这台 vCenter，再重新扫描，镜像列表就出现了。所以“镜像找不到”有时候并不是镜像的问题，而是升级顺序的问题。
6.2 集群内主机状态不一致会影响镜像匹配
如果你的集群内混有已经脱离 VCF 管理范围的主机，或者某台主机处于维护模式、disconnected 状态，升级向导在计算集群 desired state 时也可能因为部分主机无法匹配而报“找不到镜像”。
这类问题在纯 VCF 环境中不是最常见，但一旦出现就很隐蔽。处理前先检查集群内所有主机的状态，确保主机都处于 VCF 纳管、连接正常且版本一致。如果之前手动对某台主机做过升级或降级，需要先把该主机恢复到与集群其他主机相同的版本，再交给 SDDC Manager 编排。
6.3 “镜像”在不同界面里含义不同，别被名称误导
在 SDDC Manager 界面看到的“Bundle 内含组件”，和在 vCenter 的“ESXi 镜像”选项卡里看到的“映像”，以及 vLCM 集群的“desired image”，并不是同一个层级的概念。升级过程中，同一个 9.0.1 版本会以不同形态在不同组件中流转。
如果只在某个界面看到“镜像”，不能直接得出其他界面也一定能看到的结论。建议每个阶段结束后都去下一个组件里确认状态，比如 SDDC Manager 升级完成后去 vCenter 看版本，vCenter 升级完成后再去集群的映像管理里确认 9.0.1 的镜像是否已出现。这种逐级确认的做法，能让你在最早的时间点发现问题，而不是等到最后执行时才爆出来。
7. 升级完成后还需要做的事
7.1 清理临时 Bundle 与旧组件
升级完成后，SDDC Manager 里可能会保留多个版本的 Bundle。虽然旧 Bundle 本身不影响运行，但会占用存储空间，也给后续维护留下干扰项。建议在确认所有域都升级成功、系统稳定运行一段时间后，再清理不再需要的旧 Bundle。
清理时保留与当前版本相关的 Bundle，不要顺手删除。如果后续需要回滚或做补丁操作，这些 Bundle 仍然有用。判断标准很简单：当前 VCF 版本对应的最新可升级 Bundle 保留，历史版本可以删除。
7.2 检查集群 desired state 是否达到预期
升级并不是 vCenter 和 ESXi 的版本号变了就算完成。VCF 9 的生命周期管理中，集群维护着一个 expected state。升级完成后去集群的映像管理界面看一眼，确认集群当前状态与目标镜像状态一致，没有出现 drift 或 compliance 异常。
这一步很重要。如果集群里某台主机因为维护模式没能完成重建，会出现界面显示版本已更新，但实际仍有主机未打齐补丁的情况。VCF 的合规状态页面能直接显示每台主机是否符合预期，扫一遍比一个个登录主机确认高效得多。
7.3 验证业务网络和数据面功能
升级 ESXi 后，主机上的虚拟机虽然会被 vLCM 做维护模式迁移和处理，但还是建议抽几个关键业务虚拟机做一次快速验证，确认网络连通、存储访问正常。VCF 升级往往涉及管理域和工作负载域两条链路，任何一步的配置漂移都可能影响最终效果。
我在这次升级后特意查看了一下主机的 vSAN 健康状态和网络适配器状态，确认没有出现驱动版本不匹配或 vSAN 组件告警。ESXi 升级时如果厂商驱动没有随镜像打包，有可能出现某些 PCIe 设备无法识别的问题。VCF 官方 BOM 已经涵盖了主流兼容驱动，但如果是小众硬件，还是值得多留个心眼。
8. 关于 VCF 9.0.1 升级的几点个人经验
8.1 升级前别省预检查，也别只在 UI 上看结果
VCF 升级向导的预检查会做大量验证，包括版本兼容性、存储空间、网络连通性、BOM 核对等。很多人喜欢跳过预检查直接开始，但遇到“镜像找不到”这类问题时，预检查的输出其实是最有价值的线索。下次升级时，建议保留预检查报告截图或导出内容。
虽然预检查能发现一部分问题，但它也不是万能的。它只能检查当前能感知到的静态状态，对于 Bundle 内部构建号不匹配这类问题，还是需要人工核对 BOM。所以预检查要跑，官方 BOM 也要查，两者结合才是完整的升级前检查。
8.2 命名相似不代表版本正确，多核对 build number
VCF 生态里的版本号体系比较严格，一个 VCF 版本会对应一组组件的精确版本组合。升级用的 Bundle 文件名可能看起来都是 9.0.1，但不同发布批次、不同 hotfix 组合会导致 build number 微小差异。这个数字一旦不一致，SDDC Manager 就不会把镜像纳入可用范围。
我自己的习惯是建一个简单的表格，把当前环境各组件版本、升级目标版本、官方 BOM 要求版本一项项列出来，逐项打勾后再开始升级。这个动作看似繁琐，实际上能把很多中后期问题消灭在萌芽阶段。
8.3 升级窗口要预留足够余量，别把“镜像问题”拖到半夜才处理
VCF 升级从管理域到工作负载域，通常不是一两个小时能完成的事。如果中途遇到镜像、Bundle、网络等问题，实际耗时会更长。这次我准备的窗口是 8 小时，结果前面排查旧 Bundle 匹配问题就花了大半天，幸好预留了缓冲。
建议不要把升级窗口压得太满，至少留出 20% 到 30% 的额外时间用于应对异常。如果环境较大、集群较多，升级前最好先在测试环境完整跑一遍同一版本升级，把可能遇到的问题提前暴露出来。测试环境通过的路径，生产环境不一定完全一致，但至少能排除掉一部分典型的版本和镜像匹配问题。