企业官网建设流程全解析

Velero 故障排查实战指南：从 debug 诊断包、云凭据校验到 LoadBalancer 恢复与 Prometheus 指标问题的系统解法

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero

本文基于 Velero v1.10 官方文档 troubleshooting.md 展开，系统讲解 Velero 在真实生产环境中的典型故障排查路径：如何用velero debug生成完整诊断包、如何提升服务端日志级别、如何验证cloud-credentials与BackupStorageLocation/VolumeSnapshotLocation凭据链路，以及 LoadBalancer Service 恢复、备份卡在 InProgress、Prometheus 指标缺失等常见问题的成因与处置方法。读完本文，读者将掌握一套可直接落地的 Velero 排障工作流，并理解各排障手段背后的源码实现依据。

排障总体思路与两份专项文档

当 Velero 出现安装失败、备份/恢复异常或行为不符合预期时，官方建议先对照已知问题清单排查；若无法定位，再提交 issue 或在 Kubernetes 社区的 Velero Slack 频道交流。在动手之前，建议先分清故障发生阶段，并优先查阅仓库中两份与之强相关的排障文档：

• 安装/部署阶段问题：参见 Debugging Installation Issues。该文档覆盖了 Velero 客户端找不到 kubeconfig（依次检查--kubeconfig标志、$KUBECONFIG环境变量、~/.kube/config）、备份/恢复卡在New阶段（通常意味着 Velero 服务端没有运行，需检查 Pod 描述与日志）、以及 AWSNoCredentialProviders、AzureFailed to refresh the Token、GCEopen credentials/cloud: no such file or directory等云厂商凭据挂载错误的核对清单。
• 恢复阶段问题：参见 Debugging Restores，重点排查恢复卡住、资源被跳过（spec.restorePVs、排除列表、集群不支持的资源类型）等场景。

这两份文档与本文形成互补：它们回答“某类错误为什么会出现”，本文则聚焦“如何拿到证据并定位根因”。

用velero bug快速上报问题

velero bug命令会拉起一个浏览器窗口并预填好 GitHub issue 内容，预填信息包括操作系统、CPU 架构、kubectl客户端与服务端版本（如可获取）以及 Velero 客户端版本。这些信息在你点击提交按钮之前不会发送到 GitHub，因此可以随意增删改。

从源码看，该命令位于 pkg/cmd/cli/bug/bug.go，其实际收集的信息比文档描述更细：

• 版本信息来自buildinfo.Version与buildinfo.FormattedGitSHA()，即 Velero 版本号与 Git 提交号；
• 额外收集了启用的 Feature Gate，对应features.Serialize()，模板中提示读者可用velero client config get features查看；
• kubectl version的输出通过 5 秒超时的子进程获取（常量kubectlTimeout，见 bug.go），未连接集群或命令不存在时只打印警告而不会阻断提交流程；
• 打开浏览器按平台分发：macOS 用open、Linux 用xdg-open、Windows 用rundll32（见 bug.go），这意味着在无图形环境的 Linux 上该命令会报错，此时可直接复制模板内容手动建 issue。

issue 模板本身就是一份排查指引：对于 v1.7.0+ 版本，模板明确建议改用velero debug --backup <backupname> --restore <restorename>生成支持包并作为附件提交，而不是手工粘贴一堆日志。

用velero debug生成诊断包

velero debug命令生成一个 tarball 形式的诊断包，包含：

• 版本信息；
• Velero 服务端与插件的日志；
• 由 Velero 服务端管理的资源，如backup、restore、podvolumebackup、podvolumerestore等；
• 若通过参数指定，还会附带对应备份与恢复的任务日志。

更多信息可用velero debug --help查看。结合源码 pkg/cmd/cli/debug/debug.go 的实现，可以补充以下实操细节：

• 可选参数（见 bindFlags）：
  • --output：诊断包输出路径，不指定时默认为./bundle-<YYYY>-<MM>-<DD>-<HH>-<MM>-<SS>.tar.gz；
  • --backup <name>：收集指定备份的日志（如velero backup logs的产物），未指定则不收集；
  • --restore <name>：收集指定恢复的日志，未指定则不收集；
  • --verbose：执行过程中打印 crashd 的调试信息，默认关闭。
• 前置校验：命令执行前会验证目标命名空间下存在带component=velero标签的 Deployment，若指定了--backup/--restore还会校验对应资源存在（见 validate）。因此报错 “velero deployment does not exist in namespace: xxx” 通常说明命名空间（-n参数）写错了。
• 诊断包内容的实现载体：命令内嵌了一份 crash-diagnostics 脚本（cshd-scripts/velero.cshd，通过go:embed打包进二进制），执行阶段将其交给crashd收集 Velero Deployment、插件日志、node-agent DaemonSet 日志及 Velero 创建的各类资源清单（见 NewCommand 的命令描述）。

典型用法示例：

# 只打包服务端与资源清单 velero debug # 指定备份与恢复，附带任务日志，并指定输出文件名 velero debug --backup mybackup-20230101 --restore myrestore-20230102 \ --output /tmp/velero-bundle.tar.gz --verbose

提升 Velero 服务端日志级别

当服务端日志不足以定位问题时，可以编辑 Velero Deployment，把--log-level调成debug。操作如下：

kubectl edit deployment/velero -n velero ... containers: - name: velero image: velero/velero:latest command: - /velero args: - server - --log-level # Add this line - debug # Add this line ...

注意事项：

• 修改 args 会触发 Deployment 滚动更新，短暂影响控制面，建议在可维护窗口操作，并在排障结束后恢复原 args；
• 日志级别参数直接作用于velero server进程，服务端启动日志中会打印指标服务与控制器信息，debug 级别下信息量显著增大，注意日志存储压力。

已知问题：恢复 LoadBalancer 类型 Service 后云负载均衡器名称变化

由于 Kubernetes 对type=LoadBalancer的 Service 的处理机制，恢复这类对象时可能遇到 Service UID 变化的问题。Kubernetes 会基于 Service UID 自动派生云资源名称，而恢复后的 UID 与原集群不同，导致云上负载均衡器实例名称发生变化。如果你的应用 DNS CNAME 指向原云负载均衡器的域名，执行 Velero 恢复后需要更新该 CNAME 指针。

替代方案：如果你的云厂商支持，可以设置 Service 的spec.loadBalancerIP字段来固定负载均衡器 IP，从而在恢复后保持连接可用（细节参见 Kubernetes 官方文档中关于 LoadBalancer 类型 Service 的章节）。

常见问题（Miscellaneous Issues）

Velero 启动时报custom resource not found

Velero 服务端在启动时若发现所需的自定义资源定义（CRD）缺失，会拒绝启动。处置方式是重新执行一次velero install，补齐缺失的 CRD。CRD 定义位于仓库的 config/crd/v1 与 config/crd/v2alpha1 目录，velero install会将其随安装流程一并下发到集群。

velero backup logs返回SignatureDoesNotMatch错误

从对象存储下载产物（如备份日志）时会使用临时签名 URL。对于 S3 兼容型存储（如 Ceph），其实现与官方 S3 API 存在差异时可能引发此类签名错误。遇到SignatureDoesNotMatch时应逐项确认：

• 确认 S3 兼容层使用的是AWS 签名版本 4（如 Ceph RADOS 需为 v12.2.7 或更高版本）；
• 对于 Ceph，尝试使用 Ceph 原生账号作为凭据，而不是 OpenStack Keystone 等外部身份提供方。

Velero（或被备份的 Pod）在备份过程中重启，备份卡死在 InProgress

Velero 无法恢复一个被中断的备份。卡在InProgress阶段的备份没有任何文件上传到对象存储，可以直接删除后重新发起：

kubectl delete backup <name> -n <velero-namespace>

这一设计可以从源码结构得到印证：备份的上传流程以对象存储中的 tar 文件为原子提交单位，中途重启后残留的InProgress备份对象不具备可续传状态，因此官方口径是删除重建而非续跑。

Velero 未发布 Prometheus 指标

按以下顺序逐步排查：

1. 确认指标发布已启用。最新的 Velero Helm chart 默认开启指标发布，检查所用 chart 的values.yaml中相关配置是否为开启状态；

2. 确认 Velero Pod 暴露了指标端口。默认监听地址为:8085，这一点在源码中可以直接确认：服务端默认值定义于 pkg/cmd/server/config/config.go（defaultMetricsAddress = ":8085"），节点侧 node-agent 的默认值同样为:8085（见 pkg/cmd/cli/nodeagent/server.go）。Pod 中需要有如下端口声明：

   ports: - containerPort: 8085 name: metrics protocol: TCP

   该端口在官方安装资源中即为默认内容，参见 pkg/install/resources.go。

3. 确认指标服务在该端口上实际响应。可以用端口转发验证：

   $ kubectl -n <YOUR_VELERO_NAMESPACE> port-forward <YOUR_VELERO_POD> 8085:8085 Forwarding from 127.0.0.1:8085 -> 8085 Forwarding from [::1]:8085 -> 8085

   然后在浏览器访问http://localhost:8085/metrics，应能看到 Velero 暴露的指标项。

4. 确认 Pod 带有 Prometheus 抓取所需的注解。官方安装资源里默认包含prometheus.io/port: "8085"注解（见 pkg/install/resources.go），如果你的 Deployment 是手工改造过的，需要核对这些注解是否被误删；

5. 在 Prometheus UI 中确认Velero Pod 位于被抓取的 targets 列表中，且状态为 up。

如何确认 Velero 使用了正确的云凭据

云凭据交给 Velero 用于两类操作：向对象存储存取备份，以及执行卷快照操作。凭据有两种提供方式：

• 安装时提供，通过velero install的--secret-file标志，或helm install的--set-file credentials.secretContents.cloud标志；
• 创建BackupStorageLocation时通过--credential标志指定（相关字段说明见 locations.md）。

排查安装时提供的凭据

安装时提供的凭据会以 Kubernetes Secret 形式保存在 Velero 所在命名空间，名称为cloud-credentials。依次确认：

1. Secret 存在且内容正确：

   $ kubectl -n velero get secrets cloud-credentials NAME TYPE DATA AGE cloud-credentials Opaque 1 11h $ kubectl -n velero get secrets cloud-credentials -ojsonpath={.data.cloud} | base64 --decode <Output should be your credentials>

2. Velero Deployment 挂载了该 Secret（挂载点为/credentials）：

   $ kubectl -n velero get deploy velero -ojson | jq .spec.template.spec.containers[0].volumeMounts [ { "mountPath": "/plugins", "name": "plugins" }, { "mountPath": "/scratch", "name": "scratch" }, { "mountPath": "/credentials", "name": "cloud-credentials" } ]

   如果启用了文件系统备份，还需确认 node-agent DaemonSet 也挂载了cloud-credentials：

   $ kubectl -n velero get ds node-agent -ojson | jq .spec.template.spec.containers[0].volumeMounts [ { "mountPath": "/host_pods", "mountPropagation": "HostToContainer", "name": "host-pods" }, { "mountPath": "/scratch", "name": "scratch" }, { "mountPath": "/credentials", "name": "cloud-credentials" } ]

3. 确认凭据文件确实进入了 Pod 内：

   $ kubectl -n velero exec -ti deploy/velero -- bash nobody@velero-69f9c874c-l8mqp:/$ cat /credentials/cloud <Output should be your credentials>

   任何一步失败，都要回查 Secret 定义本身：键名必须是cloud，值应为完整凭据文件内容（AWS 场景下即[default]段包含aws_access_key_id与aws_secret_access_key的配置文件）。

排查BackupStorageLocation/VolumeSnapshotLocation的凭据

为某个 BSL/VSL 单独指定凭据时，按以下步骤确认：

1. 确认所用对象存储插件支持多凭据。若 Velero Deployment 日志中出现"config has invalid keys credentialsFile"，说明当前插件版本尚不支持多凭据。Velero 官方团队维护的对象存储插件均已支持该特性，出现上述报错时请升级插件到最新版本；如使用第三方插件，需联系其供应商。

2. 确认 BSL/VSL 引用的 Secret 与键存在且内容正确：

   # 确定 BackupStorageLocation 引用的 secret 与 key BSL_SECRET=$(kubectl get backupstoragelocations.velero.io -n velero <bsl-name> -o yaml -o jsonpath={.spec.credential.name}) BSL_SECRET_KEY=$(kubectl get backupstoragelocations.velero.io -n velero <bsl-name> -o yaml -o jsonpath={.spec.credential.key}) # 确认 secret 存在 kubectl -n velero get secret $BSL_SECRET # 打印 secret 内容并核对 kubectl -n velero get secret $BSL_SECRET -ojsonpath={.data.$BSL_SECRET_KEY} | base64 --decode # 确定 VolumeSnapshotLocation 引用的 secret 与 key VSL_SECRET=$(kubectl get volumesnapshotlocations.velero.io -n velero <vsl-name> -o yaml -o jsonpath={.spec.credential.name}) VSL_SECRET_KEY=$(kubectl get volumesnapshotlocations.velero.io -n velero <vsl-name> -o yaml -o jsonpath={.spec.credential.key}) # 确认 secret 存在 kubectl -n velero get secret $VSL_SECRET # 打印 secret 内容并核对 kubectl -n velero get secret $VSL_SECRET -ojsonpath={.data.$VSL_SECRET_KEY} | base64 --decode

   结果判读：

   • 若 secret 不存在：它不在 Velero 命名空间内，必须创建；
   • 若打印内容无输出：secret 内可能不存在该 key 或 key 无内容，可用kubectl -n velero describe secret $BSL_SECRET（或$VSL_SECRET）核对 data 中的键名，必要时按 Kubernetes Secret 的编辑方法补入 base64 编码后的凭据数据。

排障手段速查小结

以上流程均以 Velero v1.10 文档与当前仓库源码为准；若你使用的版本不同（例如 1.7 之前没有velero debug，需按velero bug模板中的“earlier versions”一节手工收集日志），请以对应版本文档与--help输出为准。

【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero