Agent Runtime 常见故障排查

先确定失败发生在哪一步：访问集群、提交声明、调度、拉取镜像、创建运行环境、挂载文件、执行任务，还是清理资源。保留第一次失败的信息，再进行配置修改。
确认操作目标
kubectl config current-context
kubectl -n agc-docs-demo get pods -o wide
kubectl -n agc-docs-demo get pvc
替换为实际命名空间。资源不存在时先核对 context、命名空间、名称和权限；
按现象处理
现象
先看什么
处理方式
连接超时或证书错误
本地网络、API 地址、证书有效期。
检查网络连接或更新凭证，不关闭证书校验。
Forbidden
操作身份与命名空间权限。
申请具体操作权限，区分云 API 与 Kubernetes 权限。
提交被拒绝
返回的字段或准入规则。
修改明确不支持的字段，不删除运行时配置绕过要求。
Pending / FailedScheduling
Pod 事件、节点资源、RuntimeClass 调度配置。
区分容量、节点筛选与存储绑定失败。
ErrImagePull / ImagePullBackOff
镜像地址、拉取认证、网络。
检查镜像是否存在、架构是否匹配和 Secret 所属命名空间。
ContainerCreating
沙箱创建与卷挂载事件。
检查运行时 handler 和挂载问题，先定位阶段。
非零退出或 CrashLoopBackOff
容器退出码和日志。
检查启动命令、程序依赖、配置、Probe 与资源限制。
OOMKilled
内存限制、使用峰值及节点压力。
调整应用或已评估的资源配置，不直接提高所有任务额度。
PVC Pending
StorageClass、事件、拓扑、访问模式、配额。
若为延迟绑定，结合消费者 Pod 的调度事件判断。
挂载冲突
旧消费者是否仍在、后端卸载状态。
等待或按受支持流程处理，不强占仍被写入的卷。
文件可读不可写
UID/GID、挂载只读标记、目录权限。
按驱动支持的权限方式配置，不默认放开全局写权限。
网络不通
DNS、路由、安全组、策略和服务监听。
依次验证解析、连接和应用认证。
恢复后任务重复
原任务结果、重试标识和业务检查点。
先查外部系统实际结果，再决定重试。
资源无法删除
控制器、依赖、保护与事件。
结束相应业务控制器，避免重新创建；联系管理员处理异常依赖。
收集目标 Pod 信息
kubectl -n agc-docs-demo describe pod agc-workspace
kubectl -n agc-docs-demo logs agc-workspace -c runner
kubectl -n agc-docs-demo get events --field-selector involvedObject.name=agc-workspace --sort-by=.metadata.creationTimestamp
多容器任务指定实际容器名。只有存在上一轮容器实例时，logs --previous 才能取到上一轮日志。普通日志为空可能因为容器尚未启动，应结合事件判断。
get pods 展示的 STATUS 可能是派生显示值，不应全部当作 Pod status.phase 的枚举。
反馈给支持人员
请 提交工单 联系我们，提供发生时间与时区、版本、资源标识、最近变更、最短复现步骤及必要的脱敏事件。不要提交完整 kubeconfig、Secret、Authorization 或业务文件。

现象	先看什么	处理方式
连接超时或证书错误	本地网络、API 地址、证书有效期。	检查网络连接或更新凭证，不关闭证书校验。
Forbidden	操作身份与命名空间权限。	申请具体操作权限，区分云 API 与 Kubernetes 权限。
提交被拒绝	返回的字段或准入规则。	修改明确不支持的字段，不删除运行时配置绕过要求。
Pending / FailedScheduling	Pod 事件、节点资源、RuntimeClass 调度配置。	区分容量、节点筛选与存储绑定失败。
ErrImagePull / ImagePullBackOff	镜像地址、拉取认证、网络。	检查镜像是否存在、架构是否匹配和 Secret 所属命名空间。
ContainerCreating	沙箱创建与卷挂载事件。	检查运行时 handler 和挂载问题，先定位阶段。
非零退出或 CrashLoopBackOff	容器退出码和日志。	检查启动命令、程序依赖、配置、Probe 与资源限制。
OOMKilled	内存限制、使用峰值及节点压力。	调整应用或已评估的资源配置，不直接提高所有任务额度。
PVC Pending	StorageClass、事件、拓扑、访问模式、配额。	若为延迟绑定，结合消费者 Pod 的调度事件判断。
挂载冲突	旧消费者是否仍在、后端卸载状态。	等待或按受支持流程处理，不强占仍被写入的卷。
文件可读不可写	UID/GID、挂载只读标记、目录权限。	按驱动支持的权限方式配置，不默认放开全局写权限。
网络不通	DNS、路由、安全组、策略和服务监听。	依次验证解析、连接和应用认证。
恢复后任务重复	原任务结果、重试标识和业务检查点。	先查外部系统实际结果，再决定重试。
资源无法删除	控制器、依赖、保护与事件。	结束相应业务控制器，避免重新创建；联系管理员处理异常依赖。

常见故障排查

本页目录：

确认操作目标

按现象处理

收集目标 Pod 信息

反馈给支持人员