★ FEATURED ARTICLE 1. 为什么需要一份真正能落地的 Velero 排查手册集群备份这件事平时风平浪静的时候没人惦记一旦真出事——误删了命名空间、存储桶被清空、跨集群迁移卡在 PartiallyFailed——你才会发现备份工具本身的故障排查能力有多重要。Velero 作为 Kubernetes 生态里最主流的备份与迁移工具用起来门槛不高但出问题的时候很多人第一反应就是看velero backup describe看到状态是 PartiallyFailed 就懵了不知道下一步该往哪查。我接触过的场景里Velero 的故障大致集中在几个方向备份或恢复任务状态异常、对象存储凭证失效、Pod 卡在 Init 或 CrashLoopBackOff、VolumeSnapshot 相关资源对不上、以及升级之后行为变化导致的兼容性问题。这些问题有的靠一条命令就能定位有的必须翻源码才能搞清楚它到底在等什么。标题里提到的velero debug调试包、凭证、指标和已知问题恰好覆盖了从快速收集现场到深入根因的完整链路。这篇内容适合两类人看一类是刚接手集群备份、能跑通基本命令但遇到报错就卡住的同学另一类是已经在生产环境维护 Velero、需要一套系统化排查思路的老手。我会把velero debug调试包怎么用、凭证问题怎么分层排查、指标怎么读、以及几个高频已知问题的源码级原因讲清楚中间穿插我自己踩过的坑和实际验证过的操作步骤。所有命令和配置都可以直接抄参数选择我会说明为什么这么定。需要提前说明的是Velero 的版本迭代比较快不同大版本之间 CRD 结构、插件接口、默认行为都有差异。下面涉及具体行为的地方我会标注适用的大致版本范围你对照自己环境的版本做取舍。另外文中涉及的存储、集群、项目均为泛指或虚构代称不对应任何真实环境。2. 先搞清楚 Velero 的故障分层别一上来就翻日志2.1 从架构看故障可能落在哪一层排查 Velero 问题最忌讳的就是哪里报错查哪里的线性思维。Velero 的架构决定了它的故障是分层出现的你得先判断问题落在哪一层再决定用什么工具。它的核心组件包括velero命令行客户端、运行在集群里的veleroDeployment包含 backup、restore、schedule 等 controller、各个插件对象存储插件、VolumeSnapshot 插件、以及外部的对象存储和快照存储。一次备份的完整链路是这样的客户端把 Backup CR 提交到集群backup controller 监听到之后开始处理先调用对象存储插件把资源清单上传到存储桶再对挂载了持久卷的 Pod 触发快照走 VolumeSnapshot 或 Restic/Kopia 文件级备份最后更新 Backup CR 的状态和结果。这条链路上任何一环出问题最终表现都可能是 PartiallyFailed 或者一直卡在 InProgress。所以我的习惯是先做一次分层判断如果 Backup CR 根本没被创建问题在客户端或 RBAC如果 CR 创建了但状态一直 InProgress问题在 controller 或插件如果状态是 PartiallyFailed问题多半在某个具体资源或某个卷的备份上如果恢复失败还要额外考虑目标集群的存储类、镜像、RBAC 是否匹配。这个判断做完你才知道该看 controller 日志、插件日志还是该看存储桶里的实际内容。2.2 三种状态异常对应的排查入口我把最常见的三种异常状态和对应的第一排查入口整理成了一张表实际用下来能省掉大量盲目翻日志的时间异常表现最可能的层级第一排查入口辅助手段Backup/Restore CR 未创建客户端 / RBACkubectl auth can-i验证权限客户端--log-level debug状态长期 InProgresscontroller / 插件controller 日志 插件日志velero debug调试包状态 PartiallyFailed具体资源 / 卷velero backup describe --details存储桶内 backup 内容核对Pod CrashLoopBackOff插件配置 / 凭证Pod 事件 容器日志凭证 Secret 解码核对恢复后资源缺失目标集群差异恢复日志中的 skip 记录源集群资源清单对比这张表的价值在于它把看什么和为什么看绑定了。比如状态长期 InProgress很多人会去翻客户端日志但客户端早就返回了真正卡住的是集群里的 controller 或插件你翻客户端日志什么也看不到。再比如 PartiallyFaileddescribe的摘要信息往往只告诉你有 N 个资源失败具体是哪个资源、失败原因是什么得加--details才能看到逐项记录。2.3 版本差异是排查前必须先确认的前提这一点我必须单独强调因为踩过太多次坑。Velero 从 1.9 到 1.14 之间Restic 逐步被 Kopia 取代、VolumeSnapshot 的 API 版本从 v1beta1 走到 v1、插件接口从旧版 SDK 迁移到新版、velero debug收集的内容范围也有调整。你在网上搜到的某条排查命令很可能在你当前版本上根本不适用。排查任何问题之前先跑这两条命令确认版本velero version kubectl get deployment -n velero velero -o jsonpath{.spec.template.spec.containers[0].image}第一条给出客户端和服务端的版本第二条确认实际运行的镜像 tag。两者不一致是常见问题——客户端升级了但服务端没升或者 Helm chart 的 values 里 image tag 写死了旧版本。版本确认之后再去对照官方文档对应版本的 troubleshooting 章节能避免大量无效搜索。3. velero debug 调试包把现场一次性打包带走3.1 调试包到底收集了什么velero debug是我最推荐的第一动作原因很简单它把排查需要的大部分现场信息一次性收集齐了你不用在集群里一条条敲命令、一条条复制日志。它收集的内容大致包括Velero 相关 CRD 和 CR 的完整 YAMLBackup、Restore、Schedule、BackupStorageLocation、VolumeSnapshotLocation 等、velero Deployment 和 DaemonSet 的 Pod 日志、节点和 PV/PVC 信息、以及集群版本等基础信息。这里有个细节很多人不知道velero debug默认只收集与 Velero 命名空间相关的资源如果你把 Velero 装在了非默认命名空间或者备份涉及的其他命名空间里有异常资源需要显式指定。另外它收集日志时有时间窗口限制默认只抓最近一段时间的日志如果问题发生在几小时前得调整参数把窗口拉长。我一般这样跑velero debug --namespace velero \ --log-level debug \ --duration 2h \ --output /tmp/velero-debug-$(date %Y%m%d-%H%M).tar.gz--duration 2h是为了覆盖问题发生的时间段--log-level debug让收集到的日志包含更详细的上下文。输出路径带上时间戳方便多次收集时区分。这个包拿到手之后解压出来先看目录结构再按下面的顺序读。3.2 调试包的阅读顺序与关键文件解压之后不要一头扎进日志里按这个顺序读效率最高。先看metadata/下的集群信息和版本信息确认收集时的环境和你以为的一致再看resources/下的 Backup 和 Restore CR 的 YAML重点看status字段里的errors、warnings、phase和progress然后看logs/下 controller 的日志按时间倒序找 ERROR 和 WARN最后才看插件日志和 Pod 事件。Backup CR 的status.errors字段是最直接的线索来源它记录了备份过程中每个失败项的计数和原因。但要注意这个字段只记录失败次数不记录具体哪个资源失败具体资源要看velero backup describe name --details。调试包里的 CR YAML 和 describe 的输出是互补的前者给你全局状态后者给你逐项明细。日志部分有个技巧controller 日志里搜backup加备份名能快速过滤出某次备份相关的所有日志行搜plugin能定位插件调用相关的记录搜timeout和context deadline exceeded能快速发现超时类问题。插件日志通常在单独的容器里如果 Velero 用了 initContainer 加载插件initContainer 的日志也要看插件加载失败往往就卡在这一步。3.3 调试包的局限与补充手段velero debug不是万能的它有几个明确的盲区。第一它不收集对象存储桶里的实际内容如果你的问题是备份显示成功但桶里没数据调试包帮不了你得直接去桶里核对。第二它不收集 VolumeSnapshot 的实际状态和底层快照存储的信息卷快照类问题需要额外查VolumeSnapshotContent。第三它收集的日志有时间窗口超出窗口的历史日志不在包里。所以我的做法是调试包作为基线再根据具体问题补充针对性收集。卷快照问题补kubectl get volumesnapshot,volumesnapshotcontent -A -o yaml存储桶问题补对象存储侧的列举命令节点级问题补kubectl describe node和 kubelet 日志。把这些和调试包放在一起才是一份完整的现场。注意调试包里包含 CR 的完整 YAML可能含有存储桶名称、路径、部分配置信息。对外分享或提交工单之前先做一遍脱敏把敏感的桶名、路径、账号标识替换掉。4. 凭证问题从 Secret 到插件的分层排查法4.1 凭证失效的典型表现与第一判断凭证问题是 Velero 最高频的故障来源之一典型表现包括BackupStorageLocation 状态变成 Unavailable、备份报NoSuchBucket或AccessDenied、恢复时读不到备份对象、Pod 启动时 initContainer 报凭证相关错误。这些表现背后可能是同一个原因也可能是不同层级的问题得分开看。第一判断很简单先看 BackupStorageLocation 的状态。velero backup-location get kubectl get backupstoragelocation -n velero -o yaml如果状态是Unavailablestatus.message里通常会有具体原因比如AccessDenied、InvalidAccessKeyId、no such bucket。这一步能快速区分是凭证本身错了还是凭证对但权限不够还是桶根本不存在。三种情况的处理路径完全不同别混在一起查。4.2 Secret 解码与凭证内容核对Velero 的凭证存在一个 Secret 里默认名字是cloud-credentialskey 通常是cloud。核对凭证内容的第一步是解码kubectl get secret cloud-credentials -n velero -o jsonpath{.data.cloud} | base64 -d解码出来通常是一个 credentials 文件格式的内容包含访问密钥和秘密密钥。核对时注意几个高频错误密钥前后多了空格或换行、复制时把引号也带进去了、密钥被轮换过但 Secret 没更新、Secret 的 key 名字和插件期望的不一致。最后这条特别隐蔽——不同对象存储插件对 Secret key 的命名要求不同有的要cloud有的要特定文件名装错插件或改过配置就容易对不上。还有一个容易忽略的点Secret 所在的命名空间必须和 Velero 部署的命名空间一致。如果你用 Helm 装在了自定义命名空间但 Secret 建在了 defaultPod 挂载时找不到表现就是启动失败或凭证为空。核对时把命名空间一起确认。4.3 权限策略的最小化核对凭证内容对不代表权限够。对象存储的访问策略需要覆盖 Velero 用到的操作列举桶、读写对象、有时还需要桶的元数据读取。权限不足的典型报错是AccessDenied但报错信息里不一定告诉你缺哪个权限。我的核对方法是拿凭证在集群外做一次最小化验证用同样的凭证和端点尝试列举桶、上传一个小对象、读回、删除。这四步能覆盖 Velero 备份恢复的核心操作。如果列举就失败是桶级权限问题如果列举成功但上传失败是对象写权限问题如果上传成功但读回失败是对象读权限问题。分步验证比在集群里反复试错快得多。提示做凭证验证时尽量在隔离环境用临时凭证验证完立即作废。生产凭证不要拿去在不受控的环境里测试。4.4 插件侧凭证加载的源码级理解为什么凭证明明对插件还是报错这得从插件加载凭证的机制说起。Velero 的 Pod 启动时会把 Secret 挂载成文件插件在初始化时读取这个文件并构造存储客户端。如果挂载路径、文件名、环境变量指向的路径三者有任何一处不一致插件就读不到凭证。源码层面插件通常通过环境变量如凭证文件路径定位凭证然后按特定格式解析。解析失败时有的插件会明确报凭证格式错误有的则直接报连接失败后者容易误导你去查网络。所以遇到凭证看起来对但连不上的情况先确认 Pod 里凭证文件的实际路径和内容kubectl exec -n velero deploy/velero -c velero -- ls -l /credentials kubectl exec -n velero deploy/velero -c velero -- cat /credentials/cloud如果文件不存在或内容为空问题在挂载配置如果内容对但插件仍报错再去看插件的初始化日志通常会有解析相关的线索。这一步能把凭证问题和网络问题彻底分开避免在错误的方向上浪费时间。5. 指标与监控把事后排查变成事前发现5.1 Velero 暴露了哪些关键指标Velero 服务端默认暴露 Prometheus 格式的指标端口通常是 8085。这些指标是提前发现问题的关键而不是等备份失败了才去看。核心指标包括备份和恢复的总数、成功数、失败数、各阶段耗时、队列长度、以及插件调用的成功失败计数。我重点关注三类指标。第一类是备份失败计数按备份名或按原因维度看能快速发现某个备份反复失败第二类是备份耗时耗时突然拉长往往意味着存储侧变慢或数据量增长第三类是队列长度队列持续堆积说明 controller 处理不过来可能是插件卡住或资源不足。抓取指标最直接的方式是端口转发后 curlkubectl port-forward -n velero deploy/velero 8085:8085 curl -s localhost:8085/metrics | grep velero生产环境一般接 Prometheus配一个 ServiceMonitor 或 PodMonitor 抓这个端口即可。指标接进去之后配几条告警规则比什么都强备份失败数在时间窗口内超过阈值告警、备份耗时超过基线告警、BackupStorageLocation 不可用告警。这三条能覆盖大部分备份悄悄坏了的场景。5.2 用指标定位卡顿与超时备份卡在 InProgress 是常见问题指标能帮你快速判断卡在哪。看备份各阶段的耗时指标如果卡在上传资源清单阶段问题在对象存储侧如果卡在快照阶段问题在卷快照或文件级备份如果队列长度一直涨但处理数不涨controller 本身可能卡住了。超时类问题也能从指标里看出来。Velero 对插件调用、快照操作都有超时设置超时发生时指标里会有对应的失败计数。结合日志里的context deadline exceeded能定位到具体是哪个操作超时。定位之后要么调大超时参数要么解决底层变慢的原因——我倾向于先查底层原因盲目调大超时只是把问题往后推。5.3 指标盲区与日志的配合指标不是万能的它告诉你发生了什么但不告诉你为什么。比如失败计数涨了指标不会告诉你失败的具体资源是哪个、报错原文是什么。所以指标和日志必须配合用指标负责发现和定位方向日志负责给出根因。我的习惯是给关键指标配告警告警触发后自动触发一次velero debug收集现场把调试包和告警时间点关联起来。这样等你去排查的时候现场已经被完整保存了不用赌问题还会不会复现。这个自动化做起来不复杂一个告警 webhook 加一个收集脚本就能实现但收益很大。6. 高频已知问题的源码级拆解6.1 备份 PartiallyFailed 但 describe 看不出原因这是最让人抓狂的情况之一状态是 PartiallyFaileddescribe的摘要只显示有失败项但逐项明细里信息很少。源码层面PartiallyFailed 的判定逻辑是有资源备份失败但整体流程走完了失败项的详细信息记录在 Backup CR 的status.errors和存储桶里的备份内容中。排查这类问题的关键是拿到逐项明细。velero backup describe name --details会列出每个资源的备份结果失败的资源会标注原因。如果 describe 的信息还不够直接去存储桶里看这次备份的目录结构Velero 会在桶里按备份名建目录里面有资源清单和元数据文件失败项往往能在元数据里找到更详细的记录。还有一个源码级的细节某些资源备份失败是因为它依赖的其他资源不存在或不可读比如 CRD 对应的 CR 在备份时 CRD 已被删除。这类级联失败在 describe 里表现为多个资源同时失败但根因只有一个。看到一批资源同时失败时先找它们之间的依赖关系别逐个去查。6.2 恢复时资源被跳过恢复完成但资源缺失日志里通常有 skip 记录。常见原因包括目标集群没有对应的 CRD、命名空间映射配置不对、资源已存在且策略是跳过、存储类不匹配导致 PVC 无法恢复。源码层面恢复流程会先做资源存在性检查和映射转换任何一步不满足就跳过并记录原因。排查时先看恢复日志里的 skip 关键字每条 skip 都带原因。如果是 CRD 缺失先装 CRD 再恢复如果是命名空间映射问题检查 restore 的 namespace mapping 参数如果是资源已存在确认 restore 的 existing resource policy 设置是否符合预期。PVC 恢复失败还要额外看目标集群的 StorageClass 是否和源集群一致不一致时要么改映射要么提前在目标集群建好对应的 StorageClass。6.3 升级后行为变化导致的新故障升级 Velero 之后出现以前好好的现在坏了多半是默认行为或接口变化。几个高频变化点Restic 到 Kopia 的迁移导致文件级备份配置不兼容、VolumeSnapshot API 版本变化导致旧 CR 无法识别、插件 SDK 升级导致旧插件加载失败、默认超时和并发参数调整导致行为差异。这类问题的排查思路是先对齐版本再对齐配置。确认客户端和服务端版本一致确认插件版本和 Velero 版本匹配确认 CRD 已经随升级更新velero install --dry-run或对照官方升级文档检查 CRD 变更。升级前在测试环境跑一遍完整备份恢复比在生产上直接升要稳妥得多。7. 一套可复用的排查流程与实操心得7.1 从告警到根因的标准动作序列把前面这些串起来我实际用的排查流程是这样的告警或人工发现异常后第一步确认版本和环境一致性第二步跑velero debug收集现场第三步看 BackupStorageLocation 状态和 Backup/Restore CR 的 status第四步按状态查对应的日志和明细第五步用指标确认影响范围和是否在扩大第六步定位根因后修复并补一条监控或告警防止复发。这个序列的价值在于它是有序的每一步都为下一步缩小范围。最怕的是跳过前面的步骤直接钻源码结果在错误的方向上耗掉半天。我见过有人一上来就翻插件源码最后发现只是 Secret 里多了个换行符。7.2 几个让我少走弯路的实操习惯第一个习惯任何改动之前先备份当前配置。Velero 的 CRD、Deployment、Secret、BackupStorageLocation 全部导出成 YAML 存一份改坏了能快速回滚。第二个习惯凭证轮换和版本升级都先在测试环境验证完整备份恢复链路别在生产上直接试。第三个习惯给每次排查建一个记录记下现象、命令、结论下次遇到类似问题直接查记录比重新查快得多。第四个习惯调试包收集自动化。前面提过告警触发自动收集这个投入很小但回报很大。第五个习惯定期做恢复演练。备份能不能用只有恢复过才知道定期从备份里恢复一个非关键命名空间能提前发现凭证、存储类、CRD 之类的隐患。提示恢复演练选非关键命名空间恢复后核对资源数量、PVC 绑定状态、Pod 能否正常启动。只验证恢复命令返回成功是不够的要验证恢复出来的东西真的能用。7.3 常见问题速查表最后把高频问题和对应处理整理成一张速查表方便对照现象可能原因处理方向BackupStorageLocation Unavailable凭证错误 / 桶不存在 / 权限不足解码 Secret 核对分步验证权限备份长期 InProgress插件卡住 / 存储变慢 / 队列堆积看指标队列长度和阶段耗时PartiallyFailed 无明细级联失败 / 明细在桶里describe --details 桶内元数据恢复资源缺失CRD 缺失 / 映射错误 / 已存在跳过看 skip 日志逐条核对Pod CrashLoopBackOff凭证挂载失败 / 插件加载失败看 initContainer 日志和挂载路径升级后新故障接口变化 / CRD 未更新 / 插件不匹配对齐版本对照升级文档这套流程和习惯是我在实际维护中一点点攒下来的没有什么高深技巧核心就是有序排查、保留现场、验证闭环。Velero 的故障大多不复杂复杂的是在信息不全的时候容易慌一慌就乱查。把现场收集好、把分层判断做对、把版本对齐大部分问题都能在半小时内定位到方向。真正需要翻源码的深水区问题其实不多而且一旦你理解了它的分层逻辑源码读起来也没那么吓人。
阅读完成 · 觉得有帮助？
