问题说明

适用于排查 UI 任务长时间执行中、管理节点卡队列、LongJob 挂起、备份/还原任务卡住、OVF 导入卡住、后台进程仍在运行但管控面显示异常等问题。此类问题需要区分“真正卡队列”“长任务仍在执行”“后端进程已结束但管控面未回调”和“资源异常导致队列堆积”。

现象

• UI 上执行任务超时，后续同类任务无法正常执行。
• PENDING TASK NUMBER 远大于 ASYNC LEVEL，任务队列堆积。
• 备份任务一直显示备份中，但备份服务器流量已停止或物理机侧任务已结束。
• 使用备份数据恢复云主机卡住，需要确认下载和 convert 进度。
• 从 OVF 导入云主机卡在 28%，LongJob 变为 Suspended。
• 创建云主机、重连物理机或刷新存储时，因底层异常导致任务无法返回。

适用环境

• 产品：ZCF
• 组件：Cloud
• 涉及对象：ZStack Cloud；management-server、TaskQueue、LongJob、备份、ImageStore、OVF、KVM agent、ZStore
• 版本：4.x-4.8.38

可能原因

• agent 重启、异常或底层命令卡住，管理节点任务长时间等待返回。
• 任务超时时间较长，取消任务时后端服务重启，管控面继续等待回调。
• 资源异常导致频繁重连或手动重连，队列任务过多。
• 备份服务器或镜像服务器性能不足，任务进度实际很慢或中断。
• OVF 上传镜像过程中 30 秒无进展，导致 LongJob 自动挂起。
• 存储故障、imagecache 下载、multipath 卡住等底层异常导致任务无法完成。

排查步骤

1. 判断是否卡队列

zstack-cli
LogInByAccount accountName=admin password=<password>
DebugSignal signals=DumpTaskQueue
exit
zstack-ctl dump_mn_queue | less

• 在管理日志中搜索 BEGIN TASK QUEUE DUMP 和 END TASK QUEUE DUMP。
• 关注 QUEUE SYNC SIGNATURE、RUNNING TASK NUMBER、PENDING TASK NUMBER、ASYNC LEVEL、RUNNING TASK。
• 当 PENDING TASK NUMBER 远大于 ASYNC LEVEL 时，通常可判断为队列堆积。

2. 通过 API ID 追踪任务

grep -a -n "<api-id>" /usr/local/zstack/apache-tomcat/logs/management-server.log*

• 从任务中心、审计或错误信息中获取 API ID。
• 找到任务最后一次执行位置，判断是在管理节点、KVM agent、备份服务器、镜像服务器还是存储侧等待。

3. 区分 LongJob 挂起和普通任务卡住

zstack-cli
GetTaskProgress apiId=<api-id>
QueryLongJob apiId=<api-id>
CancelLongJob uuid=<longjob-uuid>

• OVF 导入、镜像上传、长时间复制类任务可能走 LongJob。
• LongJob Suspended 时，按子任务顺序取消，通常先取消被挂起的上传/下载子任务，再取消上层创建任务。

4. 检查后端进程和真实进度

ps -ajxf | egrep "zstcli|qemu-img|convert|backup|zstore"
rbd info <pool>/<image>

• 备份还原通常包含 ImageStore 下载和 qemu-img convert 两阶段。
• 如果后端进程仍在运行，UI 卡住不一定代表任务失败。
• 如果重启 MN 后不清理后端进程，重新执行恢复任务可能与旧进程冲突。

5. 清理队列或重启前确认风险

• 如果现场环境存在正在运行的备份、迁移、恢复、镜像上传等任务，优先按队列签名精确清理。
• 使用 cleanQueue 前必须确认 signatureName 准确，避免误清理正常业务任务。
• 若无正在运行的重要任务，可评估关闭全局高可用后重启管理节点服务。

zstack-cli
cleanQueue signatureName=<signature-name> isCleanUp=true

补充排查方法

基础排查命令

# 管理节点服务和集群基础状态
zstack-ctl status
systemctl status zstack-ha.service 2>/dev/null || true
systemctl status mariadb.service mysqld.service 2>/dev/null || true
zsha2 status 2>/dev/null || true

# 管理节点主日志和近期错误
ls -lh /usr/local/zstack/apache-tomcat/logs/management-server.log*
grep -iE 'ERROR|WARN|Exception|failed|timeout' /usr/local/zstack/apache-tomcat/logs/management-server.log | tail -n 200

# 基础资源与系统状态
df -hT
free -m
top -b -n 1 | head -n 30
journalctl -p warning --since '2 hours ago' --no-pager | tail -n 200

临时解决方案

• 先区分管理面显示异常、资源状态异常和底层业务异常；只在确认底层状态正常时，才考虑重连、刷新缓存、重试任务或重启管理服务。
• 如需重启管理节点服务，先确认 HA 状态、当前任务和业务窗口，优先单节点逐台处理，并保留 /usr/local/zstack/apache-tomcat/logs/management-server.log*。
• 涉及数据库修复、资源强制删除、主存储/镜像服务器重连等操作时，先完成数据库备份并记录回退方案。

任务、数据库与管理角色专项检查

zstack-cli QueryLongJob
zstack-cli QueryTaskProgress 2>/dev/null || true
zstack-ctl status
zstack-ctl dump_mysql --file-name zstack-db-before-troubleshooting
mysql -uroot -p -e 'show processlist;' 2>/dev/null
mysql -uroot -p -e 'show slave status\G' 2>/dev/null
grep -iE 'workflow|rollback|task|longjob|database|deadlock|timeout|ERROR|Exception' /usr/local/zstack/apache-tomcat/logs/management-server.log | tail -n 300

任务/数据库类临时处理建议

• 长任务、删除残留或管理角色异常时，先判断任务是否仍有后台动作，避免重复点击、强制删除或直接清理数据库。
• 数据库类处理前必须先 zstack-ctl dump_mysql，并记录需要回退的资源 UUID、任务 UUID 和操作时间窗口。
• 管理角色或 HA 异常时先确认主备、VIP 和服务状态；临时恢复优先选择重连、重试工作流或单节点服务恢复。

补充信息

• 排查结论需结合当前版本、服务状态、日志、集群健康、近期变更和现场影响面确认。
• 涉及数据库修改、强制删除、OSD/MON 重建、Pool 删除、服务重启或网络变更等高风险操作时，应先完成备份、审批和技术支持确认。