问题说明
来源与分类
- 来源渠道：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服务仍在初始化，没有明确的启动异常堆栈。- 低配置或负载较高的管理节点更容易出现服务初始化超过健康检查等待时间的情况。
现场截图
Note:
同类现场中，安装脚本连续等待30次后报告Health check failed。该提示仍需结合服务状态、端口监听和应用日志判断，不能单独作为服务最终启动失败的结论。
影响
- 操作人员可能误判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 服务仍在初始化，安装脚本的早期探测或有限等待时间先于服务就绪。
- 管理节点资源不足或负载较高，导致 Java/Spring 服务启动时间变长。
- 如果等待后服务、端口或日志仍异常，则可能是真实的启动、配置、端口占用或依赖加载故障。
排查步骤
判断是否属于正常启动过程
- 检查安装输出的完整内容，不要只截取第一次
Connection refused：
- 后续探测成功时，前面的连接失败属于正常启动过程；
- 安装脚本最终仍显示健康检查失败时，继续执行下面的服务检查。
- 安装结束后等待1至3分钟，让Java服务完成初始化。不要在服务仍在启动时立即反复卸载和重装。
- 检查API Proxy服务状态：
systemctl status api-proxy- 检查
16443端口是否已经监听：
ss -lntp | grep 16443- 按安装包部署文档提供的健康检查URL执行
curl测试。能够连接并返回预期响应时，说明API Proxy已经可以对外提供服务。 - 查看API Proxy日志：
less /opt/api-proxy/logs/api-proxy.log- 如果日志显示服务完成初始化、
16443端口已监听且API测试正常，可以忽略安装阶段早期的Connection refused或超时提示。
服务启动较慢时的处理
- 检查管理节点CPU、内存和磁盘负载，确认是否存在资源不足或系统明显卡顿。
- 资源不足时，优先提高管理节点配置或降低同时运行的其他高负载任务，再重新验证API Proxy启动时间。
- 服务已经启动但安装脚本因等待时间不足而退出时，通常不需要重新卸载。可以先重启服务并重新执行健康检查：
systemctl restart api-proxy
systemctl status api-proxy- 等待端口监听后，再从Veeam服务器验证API Proxy地址和
16443端口的连通性。
等待后仍未恢复时的处理
如果等待后服务仍未正常监听16443端口，按真实启动失败处理：
- 检查服务状态中的退出码和失败原因：
systemctl status api-proxy
journalctl -u api-proxy --no-pager -n 200- 检查应用日志是否存在配置解析、端口占用、平台连接、证书或依赖加载异常：
tail -n 300 /opt/api-proxy/logs/api-proxy.log- 检查
16443端口是否被其他进程占用：
ss -lntp | grep 16443- 确认当前安装使用的平台地址、端口、上下文路径和其他安装参数与现场环境一致。
- 如果此前执行过卸载或多次安装，检查是否存在旧版本配置残留。优先保存现场信息并联系研发，不要直接清理数据库或删除不明确的配置文件。
- API Proxy支持覆盖安装。确认安装包和参数正确后，可按部署文档执行覆盖安装，不建议仅因健康检查提示而先卸载。
收集信息
问题仍未解决时，收集以下信息：
- ZSphere或Cloud版本、API Proxy版本和安装包来源；
- 管理节点CPU、内存配置及问题发生时的负载；
- 完整安装输出，不要只保留最后一行；
systemctl status api-proxy输出；journalctl -u api-proxy --no-pager -n 200输出；ss -lntp | grep 16443输出；/opt/api-proxy/logs/api-proxy.log；- 安装结束后等待多长时间端口开始监听；
- 从API Proxy本机和Veeam服务器执行健康检查的结果。
补充信息
注意事项
- 前几次
Connection refused后出现成功响应，属于服务启动过程，不应判定为安装失败。 - 最终显示
Health check failed也不能直接判定服务失败，应等待并检查服务、端口、API响应和日志。 - 只有服务在合理等待时间后仍未启动，或日志中存在明确异常时，才按真实启动失败继续处理。
- 不要因为一次健康检查失败反复卸载API Proxy。旧版本卸载可能存在配置残留，反而会增加排查难度。
16443是API Proxy对外服务端口，不要与API Proxy访问ZSphere或Cloud后端API所使用的端口混淆。- 证书不受信任、API Proxy连接平台超时和data-agent健康检查失败属于其他问题，应根据具体错误分别排查。
修复状态
- 当前状态：已有判断和规避方法。
- 功能状态：后续探测成功或服务稍后正常监听时，不需要功能修复。
- 产品改进：ZSV-12324跟踪安装过程中容易造成误解的健康检查提示。
- 修复版本：暂无明确版本信息。
- 关联补丁/修复包：暂无。
关联信息
- 关联Jira：ZSV-12324。
- API Proxy日志：
/opt/api-proxy/logs/api-proxy.log。 - API Proxy服务端口：
16443，以实际安装配置为准。 - 建议配图：安装时前两次
Connection refused、后续探测成功的完整输出，以及低配置管理节点中Health check failed后服务正常监听16443的验证截图。