问题说明

本文用于排查ZCenter添加云环境、测试云账号或重连已有云账号失败的问题。连接校验由对应云平台插件执行，失败原因可能是参数、网络、凭据、许可证、云平台接口或账号所属环境不正确。

现象

• 添加云环境时点击测试连接失败，环境未保存或保存后账号状态为off。
• 已有云账号执行重连失败，页面显示具体云平台错误原因。
• 错误可能表现为接口超时、Connection refused、凭据无效、许可证过期、环境不存在或不支持该云类型。
• 连续失败后，定时连接检查可能暂时停止重试，并出现“reconnection failed too many times”相关日志。

适用环境

• 产品：ZCenter
• 版本：5.1.0
• 组件：Portal云环境、云账号和对应云平台连接插件
• 云平台：ZStack、Cube、Cube HCI、ZSphere、VMware、Kubernetes及其他已部署插件

可能原因

• 云类型、云环境ID、API地址、版本或认证模式填写错误。
• Portal所在主机或容器无法访问云平台API地址，存在DNS、防火墙、路由或代理问题。
• principal、credential、用户名、密码、AK/SK、Kubernetes认证模式或Base64编码不正确。
• 私有云账号未关联有效的云环境，或云环境已被删除。
• 云平台许可证过期、额度不足、接口不可用或当前版本不支持该类型。
• 连续5次连接失败后触发临时抑制，默认抑制时间约为7200秒；此时修正配置后不能立即判断为仍然失败。

排查步骤

1. 记录请求和返回原因

• 记录云类型、云环境ID、账号UUID、API地址、失败时间、接口路径和完整错误信息。
• 不要在工单、日志或截图中暴露密码、Token、AK/SK或完整Kubeconfig。
• 区分添加新环境、添加已有环境账号、测试连接和重连已有账号四种场景。

2. 校验请求参数和权限

• 测试连接接口：POST /api/portal/v4/cloud-account/CheckAccount。
• 添加云环境接口：POST /api/portal/v4/cloud-env/AddEnv。
• 重连已有账号：POST /api/portal/v4/cloud-account/Reconnect?uuid=<ACCOUNT_UUID>。
• 检查项：确认操作账号有对应权限，type和credential不为空；私有云类型确认cloudEnvId存在。
• 预期结果：请求参数通过校验，私有云账号能找到关联云环境。
• 异常处理：先修正参数或权限，不要直接删除并重建环境。

3. 从Portal运行位置检查网络

• 检查项：从Portal服务所在主机或容器访问实际云平台API地址，而不是从浏览器所在电脑测试。
• 命令示例：

  getent hosts <cloud-api-host>
  nc -vz <cloud-api-host> <cloud-api-port>
  curl -v --connect-timeout 10 --max-time 30 <cloud-api-url>

• 预期结果：DNS解析正确、TCP端口可达并获得云平台HTTP响应。
• 异常处理：检查Portal容器网络、路由、防火墙、代理、云平台白名单、API监听地址和证书信任链。不要使用跳过TLS校验作为长期处理方式。

4. 按云类型校验凭据和专用参数

• ZStack、Cube、Cube HCI、ZSphere：确认管理节点API地址、账号凭据、版本和许可证状态。
• VMware：确认vCenter地址、账号密码和计算资源接口可访问。
• Kubernetes：确认API Server地址、authMode以及对应的Kubeconfig、证书或Bearer Token内容；凭据按接口要求进行Base64编码。
• 预期结果：参数格式和云平台实际认证方式一致。
• 异常处理：重新生成或重新编码凭据，避免手工复制时引入换行、空格或错误的Base64内容。

5. 查看Portal日志和连接抑制状态

• 日志位置：通常为Portal运行目录下的logs/zscmp.log，容器环境同时查看容器日志。
• 建议搜索：check ZStack account failed、check VMware account failed、kubernetes check account fail、CloudConnectStateHandler、reconnection failed too many times。
• 预期结果：日志能定位到网络、认证、许可证或插件校验阶段。
• 异常处理：如果日志显示连续失败抑制，先确认配置已修正并等待抑制TTL到期，再执行重连；不要循环点击重连制造更多失败记录。

6. 收集支持信息

• 脱敏后的云类型、API域名/IP和端口、版本、认证模式及错误信息。
• Portal服务日志、云平台API日志和故障时间窗口。
• 云环境和云账号UUID、账号状态、最近连接失败次数。
• 从Portal主机或容器执行的DNS、TCP和HTTP测试结果。

处理方式

1. 修正云环境API地址、版本、云类型或账号凭据后，重新执行CheckAccount。
2. 网络不通时修正Portal到云平台的路由、防火墙、代理或白名单配置。
3. 许可证、配额或云平台服务异常时，先恢复云平台侧状态，再执行连接测试。
4. 已有账号使用Reconnect恢复连接，不要以删除重建作为默认处理方式。
5. 连续失败抑制期间，停止重复重试，等待抑制时间结束或按运维流程处理精确的连接失败缓存。

验证方法

• 连接验证：CheckAccount返回成功或无错误原因。
• 账号验证：Reconnect成功，账号详情中的状态变为on。
• 环境验证：云环境详情可正常查询，关联账号和API配置正确。
• 同步验证：等待或触发一次受控资源同步，资源列表可正常拉取。
• 日志验证：后续定时连接检查不再持续输出对应插件失败日志。

风险与回滚

• 凭据变更前保留旧配置的安全记录，不要把明文凭据写入工单或日志。
• 不要直接删除云环境；删除操作可能连带删除关联云账号。
• 不要绕过证书、白名单或许可证校验作为长期方案。
• 连接参数修改失败时恢复变更前配置，并重新执行只读连通性和连接测试。

补充信息

• 连接校验由云类型对应的ICloudAccount.check()插件实现，具体错误应以现场插件日志为准。