问题说明

来源与分类

• 来源渠道：Veeam对接技术支持群现场案例和内部复现。
• 分类结论：虚拟机元数据配置问题；部分旧版API Proxy批量备份场景可能同时存在兼容问题。
• 确认依据：现场Windows虚拟机在平台中只设置为笼统的Windows操作系统类型时，Veeam无法将新备份点识别为可执行Windows文件级恢复；将操作系统类型调整为与虚拟机实际系统一致的具体版本，例如Windows Server 2019，并重新执行备份后，文件级恢复可以选择。
• 内部追踪：暂无关联Jira。

问题元数据

• 问题编号：暂无。
• 组件/产品：ZSphere、Cloud、Veeam API Proxy、Veeam Backup & Replication。
• 状态：主要场景已有处理方案。
• 优先级/严重程度：一般。
• 已确认环境：Cloud 5.4.8、Veeam 12、API Proxy 1.0.x；ZSphere对接场景也应检查相同的操作系统类型信息。
• 首个修复版本：操作系统类型问题不涉及代码修复；旧版API Proxy批量备份兼容问题由后续1.0.3版本跟进，具体支持范围以对应发布说明为准。
• 问题确认日期：2026-07-06。
• 最后更新时间：2026-09-01。

问题描述

在Veeam中为ZSphere或Cloud上的Windows虚拟机创建备份后，进入备份点的恢复操作时，文件级恢复按钮可能显示为灰色，无法选择。即使源虚拟机实际运行Windows，Veeam也可能没有将该备份点识别为Windows备份。

现场确认的主要原因是平台中的虚拟机操作系统类型只设置为笼统的Windows，或者迁移后的虚拟机没有保留准确的操作系统版本信息。Veeam在生成备份点时会使用平台提供的虚拟机元数据判断客户机类型；操作系统类型不够具体或与实际系统不一致时，备份任务可以成功，但文件级恢复入口可能不会启用。

修改平台中的虚拟机操作系统类型只会影响后续产生的备份点。已有备份点中的客户机识别信息不会自动更新，因此修改后需要重新执行备份，再使用新备份点验证文件级恢复。

此外，Veeam 12配合早期API Proxy版本进行多虚拟机批量备份时，群内曾出现文件级恢复按钮置灰的兼容问题。若操作系统类型已经正确但问题仍然存在，应继续检查API Proxy版本和备份方式。

现象

• Windows虚拟机备份任务可以完成，但在Veeam中选择备份点后，文件级恢复按钮显示为灰色。
• 同一次批量备份中的多个Windows虚拟机均无法选择文件级恢复。
• Veeam没有将备份点识别为Windows客户机，或者恢复界面只允许执行整机、磁盘等其他恢复方式。
• 源虚拟机实际运行Windows，但在ZSphere或Cloud中只设置为Windows，没有选择Windows Server 2019等具体版本。
• 迁移进入平台的Windows虚拟机更容易保留笼统、缺失或不准确的操作系统类型。
• 将操作系统类型调整为实际Windows版本并重新备份后，新备份点可以选择文件级恢复。

现场截图

影响

• 无法通过Veeam恢复备份点中的单个文件或文件夹。
• 用户可能只能采用整机恢复、磁盘恢复或其他恢复方式，增加恢复时间和操作影响。
• 该现象不等于备份任务失败，也不能仅凭按钮置灰判断备份数据已经损坏。
• 修改虚拟机操作系统类型不会修复已有备份点，需要重新备份才能验证。
• Veeam访问客户机网络、客户机凭据等问题可能影响后续文件写回，但与文件级恢复入口是否启用不是同一个阶段的问题。

适用环境

• 产品：ZSphere、ZStack Cloud、Veeam Backup & Replication。
• 产品线：ZVF及Cloud相关Veeam集成场景。
• 组件：虚拟机操作系统元数据、Veeam API Proxy、Veeam文件级恢复。
• 已确认环境：Cloud 5.4.8、Veeam 12、API Proxy 1.0.x。
• 触发条件：平台中的Windows虚拟机操作系统类型过于笼统、缺失或不准确；部分旧版API Proxy多虚拟机批量备份场景也可能触发。

可能原因

该现象可能由以下一种或多种情况导致：

• 平台记录的 Windows 操作系统类型过于笼统、缺失或与虚拟机实际系统不一致。
• 修改操作系统类型后仍使用旧备份点验证，旧备份点中的客户机识别信息没有更新。
• 操作系统类型正确时，旧版 API Proxy 的多虚拟机批量备份兼容问题也可能导致入口置灰。

排查步骤

确认问题范围

1. 记录以下版本和场景信息：

• ZSphere或Cloud版本；
• API Proxy版本；
• Veeam完整版本号，不要只记录主版本12或13；
• 单虚拟机备份还是多虚拟机批量备份；
• 当前使用的是修改配置前的旧备份点，还是修改后重新生成的新备份点。

2. 确认备份任务本身已经成功完成。若备份任务失败，应先处理备份失败问题。
3. 在Veeam中打开目标备份点，确认只有文件级恢复入口置灰，而不是所有恢复操作均不可用。

检查并修正虚拟机操作系统类型

1. 登录ZSphere或Cloud管理界面，打开受影响Windows虚拟机的详情或编辑页面。
2. 查看虚拟机的操作系统类型。如果只显示为笼统的Windows、信息为空，或者与虚拟机实际运行的系统不一致，需要进行修正。
3. 按虚拟机内实际安装的系统选择对应的具体版本。例如虚拟机实际运行Windows Server 2019时，应选择对应的Windows Server 2019类型。
4. 不要为了启用文件级恢复而随意选择与实际系统不一致的版本。应先进入虚拟机或通过现有资产信息确认真实操作系统。
5. 保存修改后，在Veeam中重新执行一次该虚拟机的备份任务，生成新的备份点。
6. 使用新备份点重新进入恢复操作，确认Windows文件级恢复按钮可以选择，并验证能够浏览备份中的文件和文件夹。

操作系统类型正确但按钮仍然置灰

1. 确认API Proxy版本。Veeam 12配合早期API Proxy版本进行多虚拟机批量备份时，可能存在兼容问题。
2. 按对应产品版本的发布说明升级到已提供相关修复的API Proxy版本。群内该问题由API Proxy 1.0.3版本进行过跟进；如果现场已有更新版本，应优先使用当前正式发布版本。
3. API Proxy支持覆盖安装，升级前保存当前安装参数和日志，不建议仅为升级而先执行旧版本卸载。
4. 升级后重新创建备份任务或重新执行备份，使用新备份点验证。不要只使用升级前生成的旧备份点判断修复是否生效。
5. 将批量备份临时调整为单虚拟机备份进行对比：

• 单虚拟机新备份点可以文件级恢复，而批量备份点不可以时，优先排查批量备份兼容问题；
• 单虚拟机和批量备份均不可以时，继续检查操作系统识别、Veeam版本和虚拟机元数据。

文件级恢复入口可用但恢复执行失败

如果按钮已经可以选择，但浏览文件、挂载备份或写回客户机失败，应转入Veeam文件级恢复执行阶段排查，重点检查：

• Veeam服务器或Mount Server与目标Windows虚拟机之间的网络连通性；
• Windows客户机凭据和本机或域认证方式；
• Veeam所需服务、共享和防火墙策略；
• Veeam任务日志中的具体挂载或写回错误。

该类问题不属于本文处理的“按钮置灰”问题。

仍然失败时收集信息

收集以下信息并联系研发或技术支持：

• ZSphere或Cloud版本、API Proxy版本和Veeam完整版本号；
• 受影响虚拟机UUID、实际操作系统及平台中配置的操作系统类型；
• 虚拟机是否由其他平台迁移进入；
• 单虚拟机备份和批量备份的对比结果；
• 修改操作系统类型前后的备份点创建时间；
• Veeam中按钮置灰的完整界面截图；
• Veeam备份任务日志；
• /opt/api-proxy/logs/api-proxy.log中对应备份任务的日志。

补充信息

注意事项

• 必须使用修改操作系统类型后生成的新备份点验证，旧备份点不具备验证意义。
• 平台中的操作系统类型应与虚拟机实际系统一致，不能只为了绕过界面限制而填写错误版本。
• “Windows文件级恢复按钮置灰”与“整机恢复时L3网卡占用”是两个不同问题。Cloud环境中API Proxy 1.0.3出现的L3网卡占用问题由后续1.0.4版本修复，不应混入本文处理流程。
• 文件级恢复按钮已经可用后出现的网络、凭据或Mount Server错误，需要按照Veeam原生文件级恢复流程继续排查。
• 从VMware迁移或恢复到ZSphere/Cloud的Windows虚拟机，还应检查VMware GuestTools残留，但该项不是本文已确认的按钮置灰直接原因。

修复状态

• 当前状态：主要场景已有处理方案。
• 配置处理：将虚拟机操作系统类型设置为与实际系统一致的具体Windows版本，并重新生成备份点。
• 插件处理：旧版API Proxy批量备份兼容问题应升级至包含相关修复的正式版本；群内由1.0.3版本进行过跟进，最终以对应产品发布说明为准。
• 修复限制：修改虚拟机元数据或升级API Proxy均不会自动修改已有备份点的识别信息。

关联信息

• API Proxy日志：/opt/api-proxy/logs/api-proxy.log。
• 相关版本：API Proxy 1.0.3曾跟进Veeam 12批量备份后的文件级恢复问题。
• 独立问题：Cloud环境中API Proxy 1.0.3整机恢复时的L3网卡占用问题由1.0.4修复。
• 建议配图：Veeam文件级恢复按钮置灰界面、平台中笼统的Windows操作系统类型、修改为具体Windows版本后的配置界面，以及新备份点中恢复按钮可用的验证界面。