问题说明
适用于排查通过 curl、Postman、Java SDK、Python SDK 或第三方系统调用 ZStack Cloud API 时出现的访问失败、鉴权失败、返回码异常、轮询超时、权限不足和参数错误等问题。此类问题多与调用地址、端口、HTTP 方法、密码加密、异步 API 轮询、代理映射和账号权限有关。
现象
- Java SDK 调用报错 405，提示请求方式错误。
- 调用异步 API 后返回轮询地址，但继续调用轮询地址返回
Request timed out。 - 子账户调用配额、IPsec 或企业管理相关 API 报权限或 session 异常。
- API 返回 202、503、404 等状态码，调用方误判为接口失败。
- 通过代理地址访问 API 时，轮询地址仍返回管理节点内网地址。
- Python SDK 调用快照创建云盘 API，任务查询超时。
适用环境
- 产品：ZCF
- 组件：Cloud
- 涉及对象：ZStack Cloud；OpenAPI、Java SDK、Python SDK、session、AK/SK、IAM、计费、配额、ZWatch
- 版本：4.x-4.8.38
可能原因
- 请求 URL、端口、协议或管理节点/VIP 地址不正确。
- API HTTP 方法使用错误，例如创建资源时使用 GET 而不是 POST/PUT。
- 登录密码加密方式错误，或调用工具对 sha512 密码进行了二次加密。
- 异步 API 返回的轮询地址未按代理地址改写，导致外部调用方访问内网地址失败。
- API 是异步任务，调用方未按 202 轮询机制继续查询任务结果。
- 子账户权限不足，调用了仅 admin 或特定角色可用的 API。
- SDK 默认任务轮询超时时间不足，长耗时任务仍在后台执行。
排查步骤
1. 核对 API 基础访问信息
- 确认调用地址是管理节点地址、VIP 地址还是代理映射地址。
- 确认端口、协议、防火墙、WAF、NAT、负载均衡和地址映射是否放通。
- 使用 curl 或 Postman 复现最小调用，排除 SDK 封装层影响。
curl -k -i http://<mn-or-vip>:8080/zstack/v1/2. 核对登录和鉴权
- session 模式需先登录并在后续请求中携带 session uuid。
- 账户登录密码按接口要求使用 sha512；如果调用工具已自动加密，避免重复传入已加密密码。
- AK/SK 模式需检查 date、signature、Authorization 字段和调用方机器时间。
RequestTimeTooSkewed通常表示调用方与平台时间差过大。若时间差超过 15 秒，需先校准调用方和平台时间后再重试。
3. 核对 HTTP 方法和参数
- 按开发手册确认 GET、POST、PUT、DELETE 方法是否匹配。
- 对 action 类接口，确认 body 结构、字段位置、systemTags 和 userTags 格式。
- 对查询接口，确认 fields、conditions、ZQL 条件和枚举值是否正确。
4. 理解异步 API 轮询机制
- 除登录等少量接口外，非 GET API 通常为异步 API。
- 首次调用成功返回 202 时，调用方需要继续 GET 返回体中的轮询地址。
- 轮询地址常见结果：
- 202：任务仍在执行。
- 200：任务执行成功。
- 503：任务执行失败，返回错误信息。
- 404：轮询地址过期或地址错误。
- 如果使用外部代理映射，需将轮询地址中的内网地址替换为代理地址后再访问。
5. 检查权限和账号类型
- 使用 admin 账号复现同一 API，判断是否为子账户权限边界。
- 配额、部分企业管理、IPsec、角色等 API 可能要求特定权限或 UI 功能授权。
- 如果 UI 上该账号也看不到对应功能，API 调用失败通常不是 session 本身问题，而是权限不具备。
6. 检查管理日志
grep -a -n "<api-id-or-session-uuid>" /usr/local/zstack/apache-tomcat/logs/management-server.log*
grep -a -n "API\|apiId\|errorCode" /usr/local/zstack/apache-tomcat/logs/management-server.log*- 用 API ID、session uuid、资源 UUID 或错误码在管理日志中追踪真实异常。
- 对批量创建、批量删除、创建快照等高并发操作，需同时关注底层资源锁、存储 I/O 和任务队列。
注意事项
- 排查结论需结合当前版本、服务状态、日志、集群健康、近期变更和现场影响面确认。
- 涉及数据库修改、强制删除、OSD/MON 重建、Pool 删除、服务重启或网络变更等高风险操作时，应先完成备份、审批和技术支持确认。