Velero 从源码构建指南：本地编译、跨平台打包与镜像制作全流程
【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero
本文是一份面向开发者的 Velero 源码构建实操指南，围绕site/content/docs/v1.1.0/build-from-source.md展开，结合当前仓库的 Makefile、hack/build.sh、Dockerfile 与 pkg/buildinfo/buildinfo.go 等实现细节，完整讲解从拉取源码、本地编译二进制、交叉编译多平台产物，到构建并推送容器镜像、更新集群中运行镜像的每一步。读完本文，你将掌握 Velero 构建体系的核心机制，能够按需产出带版本信息的 CLI 二进制与自研镜像。
前置条件
在开始构建之前，需要准备以下环境：
- Kubernetes 集群：版本 1.7 或更高（用于后续安装与验证）。
- 集群内的 DNS 服务：Velero 的 in-cluster 工作负载依赖集群 DNS 解析服务名。
kubectl：已安装并配置好访问目标集群的 kubeconfig。- Go 语言环境：最低版本要求 1.8（对应 v1.1.0 时代的要求）；当前仓库的
go.mod已演进为 Go Modules 工程，构建时请以实际go.mod声明的 Go 版本为准。
注：v1.1.0 时代的文档基于旧版
GOPATH工作区模式；而当前仓库已是标准的 Go Modules 工程（见根目录 go.mod），无需再将项目强制放置在$GOPATH/src下。下文同时给出两种源码获取方式，以适配不同历史版本或离线场景。
获取源码
方式一：通过go get拉取最新代码（推荐）
在 Go Modules 尚未普及的早期版本中，官方推荐通过go get将源码导入到 Go 工作区：
mkdir $HOME/go export GOPATH=$HOME/go go get github.com/velero-io/velero其中go指 Go 的 import path（即$HOME/go这个 GOPATH 目录）。为了后续使用方便，建议把该目录加入PATH，这样构建出的二进制可直接在任意位置执行：
export PATH=$PATH:$HOME/go/bin在 Go Modules 时代，等价做法是直接克隆仓库并切换到你需要的版本：
git clone https://gitcode.com/GitHub_Trending/ve/velero && cd velero当前仓库内包含的完整构建脚本与 Makefile 均可直接复用。
方式二：下载 Release 源码归档
从项目 Release 页面下载名为Source code的源码压缩包，解压到 Go import path 下，使其路径呈现为src/github.com/velero-io/velero（早期 GOPATH 布局要求）。
需要特别注意的是：Makefile 的多数目标都假设在一个 git 仓库内构建。如果是从源码归档构建，将无法使用依赖 git 元数据的目标（例如注入GIT_SHA、检测工作区状态的逻辑），此时只能退回到下文所述的go build命令。这一点在当前仓库 Makefile 中体现得很明显——GIT_SHA通过git rev-parse HEAD获取，GIT_TREE_STATE通过git status --porcelain判断：
GIT_SHA = $(shell git rev-parse HEAD) ifneq ($(shell git status --porcelain 2> /dev/null),) GIT_TREE_STATE ?= dirty else GIT_TREE_STATE ?= clean endif构建二进制
Velero 提供了多种构建方式，按需选择即可。无论采用哪种方式，make系列命令都会把产物输出到_output/bin/$GOOS/$GOARCH目录下。例如：
- macOS（darwin/amd64）：
_output/bin/darwin/amd64/velero - Linux（linux/amd64）：
_output/bin/linux/amd64/velero
make还会把版本号、git commit、工作区状态等元信息通过 Go linker 的-X标志注入二进制，使velero version能输出正确的版本信息（见下文"版本信息注入"一节）。
构建本地二进制
在本机编译适配当前操作系统与架构的velero二进制，两条命令等价：
go build ./cmd/veleromake local入口代码位于 cmd/velero/velero.go，它调用pkg/cmd/velero包构建整个 cobra 命令树并执行。make local在 Makefile 中的实现会基于go env GOOS-GOARCH自动探测本机平台，并把VERSION、REGISTRY、GIT_SHA、GIT_TREE_STATE等变量传给 hack/build.sh 完成实际编译：
local: build-dirs ## Build locally GOOS=$(GOOS) \ GOARCH=$(GOARCH) \ ... ./hack/build.sh交叉编译（在构建容器中）
要在一个 Linux 构建容器里产出 linux/amd64 目标二进制，运行：
make build该目标（_output/bin/$(GOOS)/$(GOARCH)/$(BIN)）会通过make shell启动构建容器，容器内以GOOS/GOARCH环境变量驱动交叉编译。指定任意平台可用通用形式make build-<GOOS>-<GOARCH>，例如为 macOS 构建：
make build-darwin-amd64在 Makefile 中，build-%目标会把ARCH=$*（形如darwin-amd64）透传给build，再由platform_temp = $(subst -, ,$(ARCH))拆解出GOOS与GOARCH：
build-%: ## Build specific binary @$(MAKE) --no-print-directory ARCH=$* build一次性构建全部受支持平台可使用便捷目标all-build，其支持的平台列表在CLI_PLATFORMS变量中定义（当前仓库比 v1.1.0 文档列出的五类平台更广）：
CLI_PLATFORMS ?= linux-amd64 linux-arm linux-arm64 darwin-amd64 darwin-arm64 windows-amd64 linux-ppc64le linux-s390x all-build: $(addprefix build-, $(CLI_PLATFORMS)) ## Build for all CLI platforms对应 v1.1.0 文档列出的核心平台为：
- linux-amd64
- linux-arm
- linux-arm64
- darwin-amd64
- windows-amd64
版本信息注入的底层原理
make构建之所以能让velero version输出正确信息，关键在于 hack/build.sh 中通过-ldflags注入的变量：
LDFLAGS="-X ${PKG}/pkg/buildinfo.Version=${VERSION}" LDFLAGS="${LDFLAGS} -X ${PKG}/pkg/buildinfo.ImageRegistry=${REGISTRY}" LDFLAGS="${LDFLAGS} -X ${PKG}/pkg/buildinfo.GitSHA=${GIT_SHA}" LDFLAGS="${LDFLAGS} -X ${PKG}/pkg/buildinfo.GitTreeState=${GIT_TREE_STATE}"这些变量对应 pkg/buildinfo/buildinfo.go 中声明的包级变量。FormattedGitSHA()还会在工作区不干净时给 commit 追加-dirty后缀：
func FormattedGitSHA() string { if GitTreeState != "clean" { return fmt.Sprintf("%s-%s", GitSHA, GitTreeState) } return GitSHA }版本命令实现在 pkg/cmd/cli/version/version.go，它会同时打印 Client 与 Server 两侧版本，并在主版本不一致时给出升级提示。可见，GIT_TREE_STATE的注入正是为了让本地未提交修改的构建产物在velero version中能被清晰识别。
调试构建
如需可调试的二进制（禁用内联与优化），在构建时设置DEBUG=1，hack/build.sh 会追加 gcflags：
DEBUG=1 make local # 对应实现：GCFLAGS="all=-N -l"构建容器镜像并更新集群中的 Velero
velero install在部署时，会依据注入的版本信息决定拉取哪个 tag 的官方镜像。若你修改了源码，需要让集群中的 Velero 运行你自己的镜像，可按以下步骤操作。
设置镜像仓库与版本
先设置$REGISTRY环境变量指定镜像仓库前缀。例如构建gcr.io/my-registry/velero:main，则：
export REGISTRY=gcr.io/my-registry若未设置，早期默认值为gcr.io/heptio-images；在当前仓库 Makefile 中默认值已变为velero，镜像名由IMAGE ?= $(REGISTRY)/$(BIN)拼出。可选地设置$VERSION改变镜像 tag（默认VERSION ?= main）。
构建镜像
make container在 Makefile 中，container目标要求 Docker buildx 可用，并会按ALL_OS_ARCH逐平台构建（默认当前GOOS-GOARCH）。构建时通过 build-arg 把PKG、BIN、VERSION、REGISTRY、GIT_SHA、GIT_TREE_STATE等传入 Dockerfile，其中：
- 使用
golang:1.26-trixie作为多阶段构建的 builder 镜像； - 在 builder 阶段同时编译出
velero、velero-restore-helper、velero-helper三个二进制； - 最终镜像基于
paketobuildpacks/ubuntu-noble-run-tiny精简运行环境，并复制产物到/output。
因此一条make container产出的镜像内实际包含 Velero 主程序与两个 helper 辅助程序，这也是velero install部署所需的完整运行时。
推送镜像
make push对于多架构场景，Makefile 提供了push-manifest目标，通过docker manifest create/annotate/push组合出跨平台 manifest 列表。若推送到非安全（insecure）镜像仓库，可设置INSECURE_REGISTRY=true并自行准备 buildx builder（详见 Makefile 顶部注释）。
更新集群中已部署的 Velero 镜像
安装完成后，若只想切换 Deployment 使用的镜像为包含你代码修改的新镜像，用kubectl set image：
kubectl -n velero set image deploy/velero velero=myimagerepo/velero:$VERSION同时需要注意：
镜像名称不变时需触发 Pod 重建：若新镜像 tag 与旧的一致，Kubernetes 不会感知镜像内容变化，需要删除 Deployment 的 Pod 强制重建：
kubectl -n velero delete pods -l deploy=veleroinstall 命令的
--image覆盖：在 pkg/cmd/cli/install/install.go 中，velero install暴露了--image标志（"Image to use for the Velero and node agent pods"）。如果你想在安装阶段就直接使用自建镜像，可以不依赖版本信息推断，显式传入--image myimagerepo/velero:$VERSION。
常见问题与构建路径速查
- 产物在哪里：统一输出到
_output/bin/$GOOS/$GOARCH/velero；Windows 平台会追加.exe后缀（见 hack/build.sh 中if [[ "${GOOS}" = "windows" ]]分支）。 - 为什么要 git 仓库：
make系列目标依赖git rev-parse HEAD与git status注入 commit 与工作区状态；从源码归档构建时请直接使用go build ./cmd/velero。 - 如何验证构建成功：运行
velero version --client-only查看注入的版本、Git commit 与工作区状态（dirty 标记）。 - 构建/验证/测试相关目标：
make verify（运行 hack/verify-all.sh）、make test（在构建容器内运行单元测试）、make ci（依次执行 modules 校验、verify、全部测试）。
【免费下载链接】veleroBackup and migrate Kubernetes applications and their persistent volumes项目地址: https://gitcode.com/GitHub_Trending/ve/velero
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
