Veeam API Proxy安装时健康检查失败但服务随后正常

问题说明

来源与分类

• 来源渠道：Veeam对接技术支持群现场案例。
• 分类结论：安装过程中的服务启动时序和健康检查提示问题。
• 确认依据：安装日志中前两次探测显示Connection refused，第三次探测成功，API Proxy服务正常启动；另有低配置管理节点因服务初始化超过脚本约30秒的等待时间而显示健康检查失败，稍后服务正常监听16443端口。
• 内部追踪：ZSV-12324。

问题元数据

• 问题编号：ZSV-12324。
• 组件/产品：ZSphere、Cloud、Veeam API Proxy。
• 状态：服务功能通常正常，安装过程的错误提示需要结合最终探测结果判断。
• 优先级/严重程度：一般。
• 已确认版本：API Proxy 1.0.x。
• 首个修复版本：暂无明确版本；ZSV-12324用于跟踪安装提示优化。
• 问题确认日期：2026-05-29。
• 最后更新时间：2026-09-02。

问题描述

安装Veeam API Proxy时，安装脚本会在启动服务后立即探测API是否已经能够对外提供服务。由于Java服务初始化需要一定时间，最初几次连接可能显示Connection refused。如果后续探测成功，说明服务已经正常启动，前面的连接失败属于启动过程中的短暂现象。

安装脚本只在有限时间内等待API Proxy监听16443端口。在管理节点CPU、内存或磁盘性能较低时，Spring环境初始化可能超过脚本的等待时间，安装脚本最终显示Health check failed，但服务进程仍在继续启动，并可能在稍后正常监听端口。

因此，不能只根据安装输出中的单次Connection refused或Health check failed判断安装失败。需要结合最终一次探测、服务状态、端口监听、API测试和应用日志确认。

现象

• 安装过程中连续出现类似以下提示：

  Connection refused

• 前两次API探测失败，但第三次探测成功，安装后API Proxy可以正常使用。
• 安装脚本显示：

  Health check failed

• 安装结束时16443端口尚未监听，但等待一段时间后端口正常启动。
• /opt/api-proxy/logs/api-proxy.log显示Java或Spring服务仍在初始化，没有明确的启动异常堆栈。
• 低配置或负载较高的管理节点更容易出现服务初始化超过健康检查等待时间的情况。

现场截图

影响

• 操作人员可能误判API Proxy安装失败，重复执行安装或卸载操作。
• 如果服务最终正常启动，Veeam接入和后续备份、恢复功能不受前几次探测失败影响。
• 如果服务在等待后仍未启动，则属于真实的API Proxy启动失败，需要继续排查，不能按本文直接忽略。
• 当前没有证据表明短暂的健康检查失败会损坏虚拟机、备份数据或平台数据。

适用环境

• 产品：ZSphere、ZStack Cloud。
• 产品线：ZVF及Cloud相关Veeam集成场景。
• 组件：Veeam API Proxy安装脚本和API Proxy服务。
• 已确认版本：API Proxy 1.0.x。
• 触发条件：API Proxy服务尚未完成初始化，或者管理节点性能较低导致服务启动时间超过安装脚本的健康检查等待时间。

可能原因

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

• API Proxy 服务仍在初始化，安装脚本的早期探测或有限等待时间先于服务就绪。