来源与分类

• 来源渠道：Veeam对接技术支持群现场案例。
• 分类结论：配置和环境问题。
• 确认依据：现场ZSphere使用HTTP和非默认访问端口，API Proxy未配置实际的平台地址、端口和上下文路径，导致Java服务连接平台超时；按实际参数覆盖安装API Proxy后恢复正常。
• 内部追踪：暂无关联Jira。

问题元数据

• 问题编号：暂无。
• 组件/产品：ZSphere、Cloud、Veeam API Proxy。
• 状态：已有处理方案。
• 优先级/严重程度：一般。
• 受影响版本：已在API Proxy 1.0.x现场环境中确认；其他版本在使用非默认平台访问地址时也应检查实际配置。
• 首个修复版本：不适用。本问题通过正确配置平台访问参数解决。
• 问题确认日期：2026-06-05。
• 最后更新时间：2026-09-01。

问题描述

Veeam通过API Proxy连接ZSphere或Cloud时，API Proxy需要访问平台管理API。安装脚本通常按照默认的协议、端口和上下文路径生成服务配置。

如果现场平台使用HTTP、非默认端口或自定义上下文路径，而安装API Proxy时没有显式指定这些参数，API Proxy可能继续按照默认地址访问平台。即使管理节点与目标IP之间网络可达，Java服务仍会因为访问了错误的协议、端口或路径而连接超时，Veeam侧也无法正常加载或管理平台资源。

需要区分以下两条连接：

• Veeam服务器访问API Proxy，通常使用API Proxy对外服务地址和16443端口。
• API Proxy访问ZSphere或Cloud管理API，使用平台实际的管理节点或VIP、协议、后端端口和上下文路径。

只验证Veeam能够访问16443，不能证明API Proxy已经能够访问平台管理API。

现象

• 在Veeam中添加或刷新ZSphere/Cloud平台失败。
• API Proxy日志中出现Java连接平台超时，或者平台API请求长时间无响应。
• 管理节点与目标IP之间可以ping或telnet，但API Proxy仍无法正常连接平台。
• 现场平台通过HTTP访问，而不是默认HTTPS；后端服务实际使用8080端口和zstack上下文路径。
• 使用实际平台API地址执行以下测试可以正常返回：

  curl -v http://<MN-IP>:8080/zstack

• API Proxy安装时未指定实际的zstack.host、zstack.port和zstack.context-path。

现场截图

影响

• Veeam无法添加或刷新ZSphere/Cloud平台。
• Veeam可能无法获取平台虚拟机、集群和存储等资源信息。
• 依赖API Proxy的备份、恢复和Worker管理操作无法继续。
• 该问题是连接参数不匹配导致的控制面访问失败，没有证据表明会直接损坏已有备份数据或虚拟机磁盘数据。

处理方案

确认平台实际访问参数

1. 确认API Proxy部署在ZSphere或Cloud管理节点上。
2. 确认当前环境使用单管理节点还是双管理节点，并记录API Proxy应访问的管理节点IP或VIP。
3. 确认平台管理API实际使用的协议、端口和上下文路径。不要仅根据浏览器地址或默认端口推断。
4. 在API Proxy所在管理节点执行实际地址测试。例如平台使用HTTP、8080端口和zstack上下文路径时，执行：

   curl -v http://<MN-IP>:8080/zstack

5. 检查ZStack服务状态：

   zstack-ctl status

6. 查看API Proxy日志，确认超时发生在API Proxy访问平台的链路，而不是Veeam访问API Proxy的链路：

   less /opt/api-proxy/logs/api-proxy.log

按实际参数覆盖安装API Proxy

1. 进入API Proxy安装包解压目录。
2. 使用现场实际参数覆盖安装。命令格式如下：

   APP_OPTS="--zstack.host=<MN-IP或VIP> --zstack.port=<平台实际端口> --zstack.context-path=<平台上下文路径>" \
     ./install-api-proxy.sh --install

3. 例如现场平台使用管理节点192.168.20.13、HTTP后端端口8080和zstack上下文路径时，执行：

   APP_OPTS="--zstack.host=192.168.20.13 --zstack.port=8080 --zstack.context-path=zstack" \
     ./install-api-proxy.sh --install

4. 覆盖安装后检查并重启API Proxy服务：

   systemctl status api-proxy
   systemctl restart api-proxy

5. 再次查看日志，确认不再出现平台连接超时：

   tail -f /opt/api-proxy/logs/api-proxy.log

6. 从Veeam服务器验证API Proxy对外服务地址和16443端口可达，然后在Veeam中重新执行添加平台、刷新资源或原失败操作。

仍然失败时收集信息

如果按实际参数覆盖安装后仍然失败，收集以下信息：

• ZSphere或Cloud版本，以及单管理节点或双管理节点部署方式；
• API Proxy版本和安装命令，敏感凭据需要脱敏；
• 平台实际协议、管理节点IP或VIP、端口和上下文路径；
• zstack-ctl status输出；
• 从API Proxy节点访问平台API的curl -v结果；
• 从Veeam服务器访问API Proxy 16443端口的测试结果；
• /opt/api-proxy/logs/api-proxy.log中覆盖安装后重新复现问题对应的日志。

如需记录详细API调用，可以在部署时启用API日志，再重新复现问题：

./install-api-proxy.sh --install --enable-api-logging

执行前应以当前安装包内的帮助信息为准，确认参数顺序和组合方式。

注意事项

• 不要把API Proxy对外的16443端口与平台管理API的后端端口混为一谈。
• 不要仅凭ping或telnet成功判断平台API可用，应使用包含协议、端口和上下文路径的完整URL进行验证。
• API Proxy支持覆盖安装，通常不需要先卸载。已知部分旧版本卸载可能残留配置，优先使用覆盖安装可以降低残留配置带来的风险。
• 双管理节点环境应根据现场部署方式选择正确的VIP或管理节点地址，不要直接照抄示例IP。
• 如果curl只提示证书不受信任，但能够连接到正确服务，这是证书信任问题，与本文的端口或上下文路径不匹配不是同一类故障。

受影响产品

• 产品：ZSphere、ZStack Cloud。
• 产品线：ZVF及Cloud相关Veeam集成场景。
• 组件：Veeam API Proxy。
• 已确认版本：API Proxy 1.0.x。
• 触发条件：平台使用HTTP、非默认端口或自定义上下文路径，且API Proxy安装配置仍使用默认平台访问参数。

修复状态

• 当前状态：已有配置修复方案。
• 修复方法：使用APP_OPTS明确指定平台实际的主机地址、端口和上下文路径，并覆盖安装API Proxy。
• 修复版本：不适用。
• 关联补丁/修复包：无需独立补丁包。

关联信息

• API Proxy日志：/opt/api-proxy/logs/api-proxy.log。
• API Proxy对外服务端口：16443，以现场安装配置为准。
• 现场确认的平台后端示例：HTTP、8080端口、zstack上下文路径。
• Veeam API Proxy安装包及部署文档：以对应产品版本发布目录和安装包内文档为准。