问题说明

本文用于排查ZCenter添加、测试或重连ZSphere云账号时，ZSphere返回HTTP 403和requestTimeTooSkewed的问题。该错误表示ZSphere判定REST请求Date头与管理节点当前时间的偏差超过允许范围，既可能是系统时间未同步，也可能是ZCenter与ZSphere时区不同且时区校验开关的比较方式不适合当前环境。

现象

• 在ZCenter中添加ZSphere云环境、测试云账号连接或重连账号失败。
• 页面可能提示“校验ZSphere账号失败”，原因中包含requestTimeTooSkewed。
• ZSphere返回HTTP 403，接口未进入正常的账号、许可证或资源查询流程。
• 云账号状态可能保持或变为off，后续资源同步无法正常执行。
• ZCenter与ZSphere显示的本地时间可能相差数小时，例如一个使用UTC，另一个使用UTC+8。

适用环境

• 产品：ZCenter
• 版本：5.1.0
• 对接平台：ZSphere 5.1.x及具备相同时区检查机制的版本
• 组件：ZCenter的ZSphere连接组件、ZSphere REST API、ZSphere管理节点
• 认证方式：使用AK/SK签名调用ZSphere REST API

可能原因

ZCenter调用ZSphere REST API时，会在请求中加入带时区的Date头，并将该值参与AK/SK签名。ZSphere在完成后续认证前检查请求时间，允许的时间偏差约为正负15分钟；超出范围时返回HTTP 403和requestTimeTooSkewed。

ZSphere的rest.checkTimeZone决定时间比较方式：

• true：识别请求中的时区，按绝对时间比较。双方时区可以不同，但系统实际时间必须同步。
• false：忽略请求中的时区偏移，按本地显示时间比较。双方即使处于同一绝对时间，只要时区不同，也可能被判定相差数小时。

因此，该问题不能只根据“显示时间不同”判断，必须同时比较epoch和时区配置。

排查步骤

1. 确认错误关键字和发生接口

• 记录错误发生时间、ZSphere云环境和云账号UUID，并确认响应中包含大小写完全一致的requestTimeTooSkewed。
• 搜索ZCenter连接组件和Portal日志中的requestTimeTooSkewed、meta-data/opensource、/licenses、/zones或ZSphere账号校验失败信息。
• 对接校验可能依次访问ZSphere元数据、许可证和区域接口，具体失败接口以现场日志为准。

2. 比较ZCenter和ZSphere的实际时间

• 在ZCenter主机、实际发送ZSphere请求的进程或容器、所有活动ZSphere管理节点分别执行：

  date '+local=%Y-%m-%dT%H:%M:%S %z %Z epoch=%s'
  date -u '+utc=%Y-%m-%dT%H:%M:%S %z %Z epoch=%s'
  timedatectl status

• 如果使用Chrony，可补充检查：

  chronyc tracking
  chronyc sources -v

• 预期结果：各节点epoch值基本一致，系统时间同步服务正常。
• 判断规则：
• epoch差值超过900秒，属于真实系统时间偏差，必须先修正时间同步。
• epoch基本一致，但本地显示时间相差固定时区偏移，例如约8小时，属于时区处理方式不一致的高概率场景。

3. 检查实际发送请求的进程时区

• 请求的Date头由ZCenter的ZSphere连接组件生成，应检查该进程或容器，而不是只检查Portal页面所在主机。
• Docker环境示例：

  docker exec <zsphere-connector-container> date '+local=%Y-%m-%dT%H:%M:%S %z %Z epoch=%s'
  docker exec <zsphere-connector-container> date -u '+utc=%Y-%m-%dT%H:%M:%S %z %Z epoch=%s'
  docker exec <zsphere-connector-container> java -XshowSettings:properties -version 2>&1 | grep -E 'user.timezone|user.country'

• 预期结果：连接组件的系统时间和JVM时区与部署设计一致。
• 异常处理：容器时区与宿主机不同或JVM使用非预期时区时，按部署规范统一时区并重新部署连接组件。

4. 检查ZSphere时区校验开关

• UI路径：系统管理 > 系统参数 > 平台策略 > 管理节点策略。
• 配置项：调用REST API检查时区。
• 后端配置：rest.checkTimeZone。
• 判断方式：
• 开启时，ZSphere识别请求时区并按绝对时间比较。
• 关闭时，ZSphere忽略时区偏移，仅比较双方本地时间。
• 因此，当双方处于不同时区但实际epoch一致时，关闭该开关可能把正常请求误判为相差数小时。

5. 排除代理修改请求头

• 如果ZCenter通过代理或负载均衡访问ZSphere，检查中间设备是否修改、删除或重新生成Date头。
• 记录脱敏后的请求时间、响应时间和代理日志。不要在日志或工单中暴露AK、签名或完整Authorization头。

处理方式

1. 临时规避方案

在ZSphere中将调用REST API检查时区切换为当前状态的相反值：

• 对接失败时开关为开启状态，将其关闭后重新测试。
• 对接失败时开关为关闭状态，将其开启后重新测试。

保存配置后，在ZCenter重新执行ZSphere云账号测试连接或重连。该操作用于快速确认并临时规避时区比较方式不匹配，不替代系统时间同步。

2. 正式处理方案

1. 统一ZCenter主机、ZSphere连接组件和全部ZSphere管理节点的NTP/Chrony时间源。
2. 确认各节点epoch差值小于ZSphere允许范围，并尽量保持在正常时间同步误差内。
3. 按部署规范统一或明确配置操作系统、容器和JVM时区，避免容器继承非预期时区。
4. 根据统一后的环境和安全策略设置rest.checkTimeZone，不要依赖反复切换开关长期维持连接。
5. 如果经过代理访问ZSphere，修正代理对Date头的处理，确保请求头不被改变。

验证方法

• 时间验证：ZCenter连接组件和所有ZSphere管理节点的epoch值基本一致，无超过900秒的偏差。
• 配置验证：记录调用REST API检查时区的最终状态，并确认与当前时区部署方式匹配。
• 连接验证：在ZCenter执行POST /api/portal/v4/cloud-account/CheckAccount，不再返回requestTimeTooSkewed。
• 账号验证：已有账号执行重连后状态变为on。
• 业务验证：等待或触发一次受控资源同步，能够正常查询ZSphere区域和资源。
• 日志验证：后续定时连接检查不再出现requestTimeTooSkewed或HTTP 403时间偏差错误。

风险与回滚

• 调用REST API检查时区是ZSphere全局REST API策略，切换后可能影响其他使用AK/SK调用ZSphere的客户端，操作前应评估影响并记录原值。
• 修改操作系统时间、时区或NTP配置可能影响日志时间、定时任务、证书校验和集群组件，应在维护窗口按平台规范执行。
• 如果切换开关后问题未恢复，应将开关恢复为原值，继续检查真实时钟偏差、连接组件JVM时区和代理请求头。
• 不要通过扩大允许时间偏差、修改签名算法或长期关闭时间同步服务规避该问题。

补充信息

• ZSphere配置项英文含义为“Check Time Zone in REST API Calls”，默认值和最终建议值应以目标ZSphere版本及现场安全策略为准。
• 添加云环境和云账号连接失败的通用排查参见：添加云环境或测试云账号连接失败，如何排查？。