简介：这是针对VMware ESXi 6.7.0的esxui离线升级包，面向虚拟化运维工程师和vSphere管理员，用于集中更新ESXi主机的Web UI组件。当遇到界面无法登录、菜单错乱、交互报错或“Possibly unhandled rejection: {}”等升级过程中常见故障时，该资源提供了离线修复所需的完整载体，该错误多由UI组件与主机通信异常或版本不匹配引起。压缩包共4个文件，主体为实际安装的VIB组件（版本1.33.1-12086396），配套两个XML索引分别记录组件信息和供应商来源，用于确认依赖关系与合法性；另有一个元数据压缩包存放签名与发布日期等元数据，便于校验完整性。整体仅3.63MB，适合内网或隔离环境离线安装。资源还对安装前的备份、网络与认证排查做了提示，能帮助读者按步骤规避升级风险。目前已有527人学习下载，适合需要保障Web管理界面稳定、快速处置ESXi UI升级异常的运维人员参考。
1. 先搞懂 esxui-offline-bundle：ESXi 6.x 的 UI 组件就该这么离线升级
拿到esxui-offline-bundle-6.x-12086396.zip这个文件名，第一反应不是双击解压，而是先问一句：我手上这台 ESXi 6.x 的页面到底哪里出了问题。很多搞虚拟化的人都有过这个经历——主机能 ping 通、SSH 能连、vCenter 里也显示正常，但浏览器打不开主机客户端，或者打开只有个白屏、一直转圈。这时候十有八九是 ESXi 内置的 UI 组件（Embedded Host Client）版本和系统不匹配，或者升级系统时把 UI 组件落下了。这个离线 bundle 就是干这个用的：它把 UI 相关的 VIB 打包成一个 zip，让你在没有外网、连不上官方 depot 的内网环境里，用 esxcli 命令把它补装或升级到位。适合谁？手上有 ESXi 6.0/6.5/6.7 的运维、机房没有出网权限的等保环境、还有那些被 UI 打不开折腾过一下午的人。
2. offline bundle 的结构与选型：VIB、profile 和在线 depot 的区别
2.1 这个 zip 里到底有什么：VIB 与 metadata 的最小结构
很多人习惯把 zip 直接当成“安装包”，双击解压、找 exe，这是 Windows 的习惯，放在 ESXi 上行不通。这个 offline bundle 不是一个安装程序，它内部是一个符合 vSphere 软件仓库规范的目录结构。我第一次拆开的时候也愣了一下，里面不是只有一个大文件，而是分了几层。
常见的 offline bundle 结构至少包含：
metadata.xml：描述这个 bundle 的整体信息，包括适用版本、依赖关系、发布者。*.vib：真正的安装单元，VIB 是 vSphere Installation Bundle 的缩写，UI 组件的功能代码都在这里。profile相关信息：它可能带一个 profile，表示整组 VIB 的组合快照，方便用 profile 方式统一升级。
你可以用命令直接查看一个 offline bundle 里到底带了哪些 VIB，而不用解压：
esxcli software sources vib list --depot=/tmp/esxui-offline-bundle-6.x-12086396.zip这条命令的意思是让 esxcli 读取指定 depot 源，列出里面的所有 VIB 包。depot 可以是本地路径、HTTP 地址，也可以是 zip 文件。执行后你会看到类似esx-ui、esx-ui-backend这样的包名，以及它们的版本号。
参数说明里有个细节：--depot指定的是“软件源”，它指向什么格式都行，zip 是最常见的离线格式。执行前记得确认这个 zip 是完整的，用ls -l看一下文件大小，和下载页面标注一致再动手。
2.2 为什么 6.x 的 UI 要单独打一个 bundle
ESXi 从 6.x 开始，系统的管理 UI 不再和内核捆绑得那么死。主机里 running 的是一个叫 hostd 的守护进程，负责 REST API 和页面资源的托管。系统升级、补丁安装时，有时候内核和驱动都更新了，但 UI 组件没跟着走，尤其是你在内网离线环境里用esxcli software profile update只更新了系统 profile，UI 组件可能因为依赖关系没被勾进来。
这就是为什么 VMware 会把 UI 组件单独发一个 offline bundle。它不是给整台主机打补丁，而是专门补 UI 这一块。适用版本在文件名里写得很清楚：6.x，覆盖 6.0 到 6.7 的后续维护版本。build 号 12086396 是具体的构建版本，安装时可以拿它和当前系统的 build 对比。
还有个常见的误解：有人以为这个 bundle 能提升 UI 性能或者换肤，不是。它的作用就是修复、升级、替换 UI 组件，解决的典型问题包括页面打不开、白屏、登录后报 JS 错误、某些功能按钮缺失。
2.3 offline bundle 和 online depot：选错场景会白折腾
在决定用命令之前，先说清楚 offline bundle 和 online depot 的适用边界。Online depot 指的是连接到官方更新仓库，比如https://hostupdate.vmware.com/software/VUM/PRODUCT_NAME这种地址。机器能出网、能解析域名的时候，直接指定 URL 可以拿到最新的补丁和组件，不用手动管文件。
但这套方案在内网环境里根本走不通。等保、政务云、机房物理隔离，这些地方别说访问外网，连域名解析都受限。offline bundle 的价值就是不需要任何外部连接，你把 zip 传到主机上，esxcli 就能从本地路径读取。代价是你得手动确认版本、手动校验完整性、手动处理依赖。选型逻辑很简单：能出网用 online depot 图省事，不能出网用 offline bundle 图可控。
我一般习惯把 offline bundle 再配合一个固定的本地目录当 depot 用，比如放/opt/vmware/depot下，这样以后排查问题还能回看当时装的是哪个版本。
3. 升级实操：上传、校验、esxcli 命令与参数边界
3.1 文件上传与来源校验：别把损坏的 zip 传上去
拿到 zip 之后，第一步是把它传到 ESXi 主机上。最常用的方式是 scp，Windows 上用 WinSCP 或者直接命令都可以。传到/tmp是最省事的，路径短，不会被权限挡住。
scp esxui-offline-bundle-6.x-12086396.zip root@<esxi-ip>:/tmp/传完之后，SSH 登录主机，先做两件事：看文件大小和算校验和。ESXi 自带的sha256sum可以算，把你下载页面看到的 SHA256 值和主机上算出来的对比，一致再继续。
sha256sum /tmp/esxui-offline-bundle-6.x-12086396.zip如果两边不一致，别装。这种情况最常见的原因是下载过程中断，或者用 U 盘拷的过程里文件系统有问题。文件不完整时，esxcli 后面报的错误会很让人困惑，比如提示“depot 解析失败”或者“no vib found”，排查半天发现只是文件本身坏了。
3.2 执行升级：esxcli software vib update 的参数拆解
文件校验没问题之后，执行升级。这里有一个前提动作：确认当前主机处于正常状态，最好先开启维护模式。虽然 UI 组件的 VIB 支持 live install，不需要重启，但为了避免 hostd 在升级过程中被频繁调用导致不稳定，我一般会先把维护模式打开。
esxcli system maintenanceMode set --enable true维护模式是 ESXi 的常规操作，它的作用是让集群感知这台主机在维护，会自动迁移上面的虚拟机。单机环境没有集群的话，这条命令不会动你的虚拟机，只是标记状态。
接下来才是真正的升级命令：
esxcli software vib update --depot=/tmp/esxui-offline-bundle-6.x-12086396.zip这段命令的含义是：让 esxcli 从指定 depot 读取 VIB，对主机上已有的、同名的 VIB 做更新。update和install的区别在于，update 只升级已安装的包，如果主机上没有这个包，它会直接跳过；install 则是把包装上去，不管有没有这个包都执行安装逻辑。UI 组件在 6.x 的 ESXi 里基本都已经预装，所以用 update 是符合场景的。
命令执行中的输出会分几个阶段：先是扫描 depot，再是计算依赖，然后是执行安装。看到Installation Result并且Message: The update completed successfully，就说明装完了。这个结果页还会列出你装的 VIB 的 name、version、上一个版本号，值得截图或者抄下来。
这里有个参数我要单独说明：--no-sig-check。它的作用是跳过 VIB 的签名校验。官方发布的 bundle 不需要加这个参数，加了反而会失去一层安全保障。第三方改过的 bundle、或者你自己打包的 VIB，才需要用到它。我用这个参数只干过一件事：在公司内部验证自研的小工具 VIB。生产环境装官方 UI bundle 加这个参数，属于给自己找麻烦。
3.3 两步确认：vib list 和 profile 的依赖一致性
升级完不能直接关 SSH。先确认一下 VIB 确实在主机上，并且是刚才安装的版本：
esxcli software vib list | grep -i esx-ui看到输出里有esx-ui开头的行，版本号和刚才 depot 里的一致，说明装上了。vib list列出的是当前主机已安装的所有 VIB，grep -i esx-ui只过滤 UI 相关的行。
第二步是看依赖有没有问题。VIB 升级有时候会留下“孤儿依赖”——旧版本被替换了，但其他包还引用着旧版本的 ID。这个情况用esxcli software vib get是看不出来的，要看 profile：
esxcli software profile get这个命令返回当前主机的 profile 名称和 build 号。如果 profile 显示正常，没有missing或者conflict之类的标记，说明 VIB 之间的依赖关系是完整的。这一步不能省，因为 UI 装完页面还是打不开的场景里，有很大比例不是 UI 本身坏了，是依赖没对齐。
4. 版本管理与回滚：把升级失败的 UI 拉回原样
4.1 升级前的版本快照：两条命令留下后悔药
升级前，我先记录当前 UI 组件的版本。这个动作看起来多余，但真出问题的时候，它就是后悔药。记录方法很简单：
esxcli software vib list | grep -i esx-ui esxcli software profile get把输出存到文本文件里。6.x 的 UI 版本命名并不直观，只有 build 号能准确表示，所以你必须记录完整行，不能只记“好像是个 6.7 的”。
我踩过这个坑：有一次给一台跑着 6.5 的主机升级 UI，没记版本直接 update，装完之后页面彻底打不开，想回滚却不知道原来版本号是多少。最后翻/var/log/esxupdate.log里的历史记录才找到旧版本号。从那以后，我给自己定了个规矩：任何 VIB 升级前，先跑一遍vib list重定向到文件。
4.2 回滚操作的三种姿势
回滚 UI 组件有几种做法，按适用场景排个序。
第一种，用vib install指定旧版本号直接装回去：
esxcli software vib install --vib=esx-ui:<旧版本号> --no-sig-check这个方式的逻辑是：esxcli 会从你指定的 VIB 标识里找对应的包，把当前版本替换掉。版本号必须精确到 build 号，比如esx-ui:6.5.0-12086396。注意--vib参数的格式是包名:版本号，不是文件名。install在这里做的是“覆盖安装”，它能替换已有 VIB，而update做不到降级，因为 update 只在检测到更高版本时才执行。
第二种，从本地 depots 恢复 profile：
esxcli software profile install --depot=/tmp/旧depot.zip --profile=标准profile名这个适合你手上恰好有旧系统的完整 offline bundle，可以把整组 VIB 恢复到 profile 定义的快照状态。它会比对当前已安装的 VIB 和 profile 里的差异，把多出来的降掉、缺的补上。但注意，这个操作会把主机上所有 VIB 都拉到 profile 状态，不只是 UI，所以影响面更大。
第三种，干脆重新装一遍 UI bundle 的旧版本 zip。如果你保留着旧版本的 zip，vib update --depot=旧zip是降不回去的，得用vib install --depot=旧zip，install 不判断版本高低，直接执行安装逻辑。
4.3 清理临时 depot 和日志
回滚或者升级成功之后，/tmp下的 zip 和安装日志建议清掉。ESXi 的根分区很小，/tmp挂载的空间有限，一个大 zip 放那儿不动会占掉宝贵的存储。日志文件也一样，/var/log/esxupdate.log每次都会追加，累积多了会影响后续排查。
rm -f /tmp/esxui-offline-bundle-6.x-12086396.zip echo "" > /var/log/esxupdate.log第二条命令不是删除日志，而是清空内容，因为 esxupdate.log 文件本身被 esxcli 占用，直接rm可能导致后续写入异常。用 echo 重定向清空，既保留文件句柄，又腾出空间。这个习惯在处理 ESXi 日志时通用。
5. 避坑：四个我踩过的 esxui bundle 安装坑
5.1 现象：执行 update 后提示No VIBs found，什么都没装
原因：zip 文件传输损坏，或者下载的 bundle 和当前系统版本不匹配。esxcli 解析 depot 时，如果内部 metadata 和 zip 实际内容对不上，会直接放弃扫描。
解决：重新下载文件，sha256sum对比校验值传上去再试。如果校验值一致但仍报No VIBs found，去看 zip 内部结构，确认里面确实包含.vib文件而不是只有一个目录壳。用unzip -l看不出来什么异常的话，换一个下载渠道重新拿文件。另外，版本不匹配的情况也要排查——6.x 的 zip 不一定兼容所有 6.0/6.5/6.7 的小版本，文件名里的 build 号就是干这个用的，对不上就找对应版本的文件。
5.2 现象：安装报错，提示Signature verification failed，然后中断
原因：VIB 的签名信息缺失或者被改动过。如果是官方 bundle，常见于下载来源有问题；如果是从第三方渠道拿的文件，被重新打包过，签名校验必然过不去。
解决：先确认来源，官方渠道的 zip 不需要--no-sig-check。只有明确了文件来历、确认内容无篡改，才加--no-sig-check继续装。加了这个参数，esxcli 会跳过签名验证直接安装，风险你自己担。生产环境我建议宁可不装，也不要在签名上妥协。
5.3 现象：装完了，vib list也显示新版本，但浏览器打开 UI 还是旧的或打不开
原因：浏览器缓存了旧的 JS 和 CSS 资源。ESXi 的 UI 是典型的单页应用，静态资源全部走浏览器缓存，VIB 更新的是主机上的资源文件，浏览器端不会自动失效。
解决：强制刷新或者清理浏览器缓存。Chrome 下按Ctrl+Shift+R硬刷新，或者打开 DevTools 勾选 Disable cache 再刷新一次。如果清理缓存后仍然白屏，检查 UI 服务本身是否重启过——VIB 安装过程会尝试重启相关服务，但在某些场景下 hostd 没有完全重新加载，手动重启一下：
/etc/init.d/hostd restart重启 hostd 会短暂中断当前主机的管理连接，vCenter 里可能显示短暂断开，属于正常现象，等几十秒就恢复。
5.4 现象：升级 UI 过程中提示磁盘空间不足，Storage space exhausted
原因：ESXi 的系统分区很小，/tmp和 bootbank 空间有限。zip 上传到/tmp已经占了一块，安装时还要解压临时文件到 bootbank，空间瞬间被打满。
解决：上传之前先看下空间：
df -h重点看/tmp、/bootbank和根分区的使用率。如果紧张，把 zip 放到数据存储上而不是/tmp，比如/vmfs/volumes/datastore1/，因为数据存储的空间通常比系统盘大很多。也可以先清理旧日志和 core dump 文件，du -sh /var/log/*找出大文件再决定怎么处理。
5.5 现象：升级后 UI 登录报503 Service Unavailable
原因：UI 后端服务没有正常起来。常见于 hostd 进程状态异常，或者 UI 组件依赖的某个服务没跟着启动。这个报错最容易让人误判成 VIB 没装好，然后又去重装一遍，浪费时间。
解决：先看进程状态：
/etc/init.d/hostd status如果进程没起来，启动它。如果进程是活的，去查/var/log/hostd.log，重点看ui相关的报错行。我遇到过因为时区配置异常导致 UI 服务起不来的情况，把 NTP 时间同步好、重启 hostd，问题就消失了。
6. 装完别急着关 SSH：日志、端口与页面三重验证
6.1 重载服务与端口连通性检查
UI 组件更新完成之后，我习惯按固定顺序做三重验证。第一重是服务层，确认 hostd 进程状态正常，必要时重启一次让静态资源完全重新加载。第二重是端口层，ESXi 主机客户端走的是 443 端口，和 vCenter 的 5480 不是一回事，别搞混。验证端口监听状态：
netstat -an | grep :443 | grep LISTEN只要看到 443 端口处于 LISTEN 状态，说明 Web 服务层已经就绪。如果这里没有输出，先确认 hostd 是否真的启动了，再看防火墙规则有没有把端口禁掉。
6.2 页面验证和日志回溯
第三重是页面层，直接浏览器访问：
https://<esxi-ip>/ui不用加端口号，443 是默认端口。打开后按F12打开开发者工具切到 Network 面板，刷新页面，重点看 UI 相关的请求有没有返回 404 或 500。如果页面正常显示登录框，并且 Network 里所有静态资源都返回 200，这次升级就真正完成了。
顺手再查一次安装日志确认没有遗留的错误：
grep -i error /var/log/esxupdate.log | tail -20日志文件里如果只有error关键字但没有实质报错行，说明排查干净。日常维护里我改不了这个习惯——每次装完任何 VIB，必须把服务、端口、页面这三件事都走一遍才收工，缺一项都算没装完。这套流程帮我拦住过好几次“看起来装上了，实际还是旧的”的情况，希望你也能用上。
本文还有配套的精品资源，点击获取