企业官网建设流程全解析

• 网络
• 云原生
• 网络安全

本指南以 Calico 仓库根目录的 DEVELOPER_GUIDE.md 为主体，结合仓库内根级 Makefile、共享构建库 lib.Makefile、版本元数据 metadata.mk 以及各组件子目录的 Makefile，系统讲解如何搭建 Calico 开发环境、按需构建组件镜像、执行交叉编译，并运行单元测试（UT）、功能验证测试（FV）与系统测试（ST）。读完本文，你将能够从零开始编译出calico/node、felix、typha、calicoctl等镜像与二进制，并掌握加速增量构建、替换基础镜像、同步 Helm Chart 与 manifests 的完整工作流。

前置条件：Linux 构建环境

Calico 的构建体系完全围绕容器化构建设计，所有 Go 编译都在 Docker 容器内完成，因此宿主机只需要三样东西：

• Docker：构建容器镜像、执行容器内编译、运行 FV/ST 测试的基础设施；
• git：构建过程依赖 git 仓库状态推导版本号（GIT_VERSION、GIT_COMMIT、BUILD_ID等，见 lib.Makefile）；
• make：整个仓库的构建与测试入口统一由 Makefile 驱动。

在开始之前建议先确认 Docker 守护进程可用（如docker info能正常返回）。首次构建时，构建系统会自动拉取构建工具镜像calico/go-build（版本形如$(GO_VERSION)-llvm$(LLVM_VERSION)-k8s$(K8S_VERSION)，当前由 metadata.mk 中的GO_BUILD_VER决定，例如 Go 1.27.1 + LLVM 21.1.8 + Kubernetes v1.37.0）。

注意：文档假设的是 Linux 环境。虽然部分子目录支持 macOS 开发（例如calicoctl提供darwin-amd64、darwin-arm64二进制），但整体构建与测试仍以 Linux + Docker 为基准。

构建 Calico：从全量镜像到按需编译

全量构建make image

在仓库根目录执行：

make image

该命令会并行构建仓库内所有组件的容器镜像。根 Makefile 中image目标的实现为：

image: $(MAKE) -j$(NUM_BUILD_JOBS) $(KIND_IMAGE_MARKERS) @CALICO_IMAGES="$(KIND_CALICO_IMAGES)" \ DEV_IMAGE_PREFIX="$(DEV_IMAGE_PREFIX)" \ DEV_IMAGE_TAG="$(DEV_IMAGE_TAG)" \ ARCH="$(ARCH)" \ STAMP_DIR="$(DEV_STAMP_DIR)" \ $(REPO_ROOT)/hack/dev-build.sh --tag

可见全量构建分两步：先以-j$(NUM_BUILD_JOBS)并行构建各组件镜像（默认并行度为 4，可用NUM_BUILD_JOBS=8等调大，见 lib.Makefile），再调用 hack/dev-build.sh 将所有本地镜像统一打上开发仓库标签。全量构建产物众多、耗时较长，因此文档明确建议：只构建你正在修改的那个组件的镜像。

干净构建make clean image

构建系统利用 Go 包缓存与本地 vendor 缓存来加速重复构建，增量构建会跳过未变更部分。若需要彻底重来，先执行clean目标：

make clean image

根 Makefile 的clean会递归清理api、apiserver、calicoctl、cni-plugin、confd、felix、cmd/calico、kube-controllers、libcalico-go、node、typha、release、whisker等全部子目录，并删除.dev-stamps/、bin/、.stamp.*等中间产物，确保后续构建从干净状态开始。

构建单个组件镜像make -C <dir> image

Calico 采用"每个子目录一个独立 Makefile + 共享 lib.Makefile"的架构（各组件 Makefile 均include ../lib.Makefile），因此可以在任意组件目录单独执行构建。例如构建calico/node：

make -C node image

对应地，也可以构建其他组件：

make -C felix image # 构建 calico/felix 测试环境镜像 make -C typha image # 构建 Typha 相关产物 make -C calicoctl build # 编译 calicoctl CLI 二进制

以 node/Makefile 为例，image目标依赖完整的构建链：先编译 BPF 程序（filesystem/usr/lib/calico/bpf，来自 felix/bpf-gpl 与 felix/bpf-apache 的make build-bpf），再以 CGO 方式构建组合型calicomonobinary（../cmd/calico/bin/calico-cgo-$(ARCH)），最后通过docker buildx build生成node:latest-$(ARCH)镜像。这也解释了为什么node镜像的源码依赖除了自身deps.txt外，还通过local-deps-go-files宏把cmd模块的全部本地依赖（felix、confd 等）纳入增量重建判断。

版本号与产物命名

构建产物命名遵循统一约定（详见 lib.Makefile 的LDFLAGS与各组件 Makefile）：

• 二进制位于bin/或dist/，形如felix-arm64、typha-amd64、calicoctl-linux-amd64、calicoctl-darwin-arm64、calicoctl-windows-amd64.exe（多 OS 时按NAME-OS-ARCH命名，见 calicoctl/Makefile）；
• 镜像命名为NAME:latest-ARCH，如calico/felix:latest-amd64、calico/typha:latest-s390x，多 OS 时为NAME:latest-OS-ARCH；
• 编译进二进制的版本信息（Version、BuildDate、GitRevision）通过-X链接器标志注入pkg/buildinfo包，版本号由git describe --tags --dirty --always --abbrev=12推导，发布构建（RELEASE=true）时仅使用 tag。

交叉编译：为指定架构构建镜像

默认情况下镜像面向构建机器的架构产出。Calico 支持四大架构：amd64、arm64、ppc64le、s390x（由 lib.Makefile 的ARCHES变量定义）。要交叉编译，通过ARCH环境变量指定目标架构：

make image ARCH=arm64

在 lib.Makefile 中可以看到完整的架构处理逻辑：

• BUILDARCH为宿主机架构（uname -m探测，x86_64/aarch64会被规范化成amd64/arm64），ARCH为目标架构，默认等于BUILDARCH；
• 交叉编译时，构建系统会先通过docker run --privileged calico/binfmt注册 QEMU binfmt 支持（register目标），再用docker buildx build --platform=linux/$(ARCH)产出目标架构镜像；
• amd64 主机构建其他架构时，Go 侧使用 clang 作为交叉编译器（clang --target=aarch64-linux-gnu等），配合/usr/$(CROSS_TRIPLE)/sys-root系统根目录，避免 QEMU 慢速模拟 CGO 构建（见CLANG_CROSS_TRIPLE_*与CROSS_SYSROOT定义）；
• Rust 侧（CARGO_BUILD_TARGET）同样通过环境变量注入交叉编译目标，链路使用 lld 链接器。

执行make build-all或make image-all会一次性构建全部受支持架构（可用EXCLUDEARCH排除个别架构）。

替换基础镜像：CALICO_BASE 变量

许多 Calico 组件（如 Typha、apiserver）以calico/base作为基础镜像。该镜像可通过 Makefile 变量覆盖：

make image CALICO_BASE=some/image

默认值由 lib.Makefile 决定：CALICO_BASE ?= calico/base:$(CALICO_BASE_VER)，其中CALICO_BASE_VER当前为基于 Red Hat UBI 9 的镜像（见 metadata.mk 中的CALICO_BASE_VER=ubi9-1789183536）；若设置USE_UBI_AS_CALICO_BASE，则直接使用registry.access.redhat.com/ubi9/ubi-minimal:latest。DOCKER_BUILD宏会通过--build-arg CALICO_BASE=$(CALICO_BASE)把该变量传入各组件 Dockerfile。

使用自定义基础镜像需要满足两个前提（文档原文明确警告）：

1. 所选基础镜像必须与默认镜像足够相似（当前默认基于 Red Hat UBI），否则构建可能失败；
2. 自建镜像缺少 Calico 团队对官方镜像所做的回归测试，官方支持将按尽力而为原则提供。

同步 Helm Chart 与 Manifests

Calico 的 Helm Chart 位于仓库charts/目录（含calico、tigera-operator、crd.projectcalico.org.v1、projectcalico.org.v3等多个 Chart），而 manifests 目录下的 YAML（如calico.yaml、calico-typha.yaml、calico-etcd.yaml）大部分由 Helm Chart 自动生成。

因此，修改了 Chart 模板之后，必须重新生成 manifests：

make gen-manifests

根 Makefile 中该目标的实现为：

gen-manifests: bin/helm bin/yq cd ./manifests && ./generate.sh

即借助bin/helm与bin/yq渲染 Chart 并运行 manifests/generate.sh 批量产出。此外，完整的代码/CRD 生成流程make generate会依次执行gen-semaphore-yaml、gen-deps-files、protobuf、各组件gen-files、gen-manifests、gen-test-set与fix-changed，是新增 API 或修改 CRD 定义后的一站式生成入口。

Makefile 标准目标参考

以下是每个项目目录（含根目录）都会提供的标准 Makefile 目标：

以 calicoctl/Makefile 为实例：make build产出bin/calicoctl-$(BUILDOS)-$(ARCH)，make build-all则产出 Linux 四种架构加 Windows/macOS 的全部二进制；felix/Makefile 的build还额外包含build-bpf（编译 GPL 与 Apache 两套 BPF 程序）与 Windows 可执行文件。

运行自动化测试

单元测试（UT）：make test

每个组件目录都维护着独立的测试套件，测试随源码在仓库内，无需部署完整 Kubernetes 集群即可运行。文档建议：

1. 首选通过提交 PR 触发 CI 构建，让 CI 系统代为运行测试；
2. 本地运行时逐目录执行，因为全仓库测试耗时非常长；在具体目录中使用make test运行该目录的测试。

make test在 lib.Makefile 中定义为test: ut fv st，即依次运行单元测试（ut）、功能验证测试（fv）与系统测试（st）。各目录的测试入口各有特色：

• felix：ut目标通过run-coverage脚本以 CGO 容器运行 Ginkgo 测试（默认跳过fv,k8sfv,bpf/ut包）；ut-bpf需要 root 权限，会挂载 bpffs 并运行真实 BPF 测试；还提供ut-watch（ginkgo watch）与cover-browser/cover-report覆盖率查看；
• typha：ut目标执行./utils/run-coverage，另提供ut-no-cover、ut-watch、cover-report等辅助目标；
• calicoctl：ut目标在容器内运行ginkgo -cover -r并输出 JUnit 报告。

功能验证测试（FV）与系统测试（ST）

在 lib.Makefile 中test由ut fv st组成，但各目录对 FV/ST 的实现差异较大：

• felix FV：make fv会先通过fv-prereqs构建fv/fv.test测试二进制、组合型calico镜像、test-workload、test-connection、calico-bpf、pktgen及全部 BPF 程序，然后由run-batches脚本按批次执行。支持并行分片：FV_NUM_BATCHES=N设定总批次数，FV_BATCHES_TO_RUN="k"指定运行第 k 批；还有fv-bpf（FELIX_FV_ENABLE_BPF=true启用 eBPF 数据面）、fv-nft（nftables 数据面）等变体；
• typha：fv等价于k8sfv-test，即用calico/calico:latest-$(ARCH)镜像以component typha命令启动 Typha，再运行 felix 侧的 k8s FV 测试（USE_TYPHA=true/false控制是否经过 Typha）；
• calicoctl：fv目标会启动 etcd、并在 6443/6444 两个端口各起一个 Kubernetes apiserver 与 controller-manager（用于验证多 kubeconfig 支持），应用 mock Node 与 CRD 后运行./tests/fv；
• ST（系统测试）：calicoctl 的st通过pytest在特权测试容器内运行 tests/st 下的测试（可用ST_TO_RUN指定单个用例，如tests/st/calicoctl/test_crud.py:TestCalicoctlCommands.test_get_delete_multiple_names），felix、typha 则声明"No STs available"。

各目录更细粒度的测试选择（如 Ginkgo focus、批次数、慢测试阈值）请参考对应目录的文档与 Makefile。

构建加速：缓存与并行机制

Calico 的构建体系从多个维度加速增量开发：

• Go 包缓存与 vendor 缓存：所有容器内构建统一挂载LOCAL_GO_PKG_CACHE（默认$(REPO_ROOT)/.go-pkg-cache，也可由GOCACHE或环境变量指定）到容器/go-cache，并挂载宿主机GOMOD_CACHE（$GOPATH/pkg/mod或$HOME/go/pkg/mod）实现模块复用，见 lib.Makefile 的DOCKER_RUN_PRIV_NET定义；
• 源码依赖跟踪（deps.txt）：每个组件的 deps.txt 记录外部模块依赖与仓库内本地依赖（local:前缀），SRC_FILES据此自动展开，任何相关源码变更都会触发该组件的增量重建；
• 镜像指纹与 stamp 文件：镜像构建通过.*.created-$(ARCH)等 stamp 文件标记完成状态，make clean删除这些 stamp 以强制重建；根目录image目标默认-j4并行构建各组件，可用NUM_BUILD_JOBS调整并行度；
• 开发镜像标签与推送：hack/dev-build.sh 负责把本地构建的calico/<name>:latest-$(ARCH)镜像重新打上$(DEV_IMAGE_PREFIX)/<name>:$(DEV_IMAGE_TAG)开发标签（make image内部调用--tag），make push则按 docker image ID 变化增量推送（--push），重复运行会自动跳过未变更的镜像；
• 容器资源限制：可在工作站上通过DOCKER_CPUS、DOCKER_CPUSET_CPUS、DOCKER_MEMORY、GOMAXPROCS、GO_BUILD_PARALLELISM等变量限制并行构建的内存/CPU 占用，防止开发机被压垮。

深入阅读

• 更详细的开发者文档（如 如何向 Calico 新增一个 API，涵盖 v3 API 结构、make generate生成代码与 CRD、kubebuilder 校验注解、libcalico-go 客户端与 calicoctl CRUD 命令的编写流程）位于 hack/docs 目录；
• 根级 Makefile 还包含protobuf（重新生成 protobuf 绑定）、static-checks/golangci-lint（静态检查）、chart（打包 Helm Chart）、kind-up/e2e-test（本地 kind 集群端到端测试）、release系列（发布构建）等更多目标，可按需查阅；
• 各组件 Makefile（node/Makefile、felix/Makefile、typha/Makefile、calicoctl/Makefile 等）是了解具体构建链与测试入口的第一手资料。

常见问题与建议

• 全量构建太慢？优先make -C <组件目录> image只构建所修改的组件；测试同理，逐目录执行make test而非仓库级全量测试。
• 需要干净构建？使用make clean image，或在make push前删除.dev-stamps目录强制全量重建（见根 Makefile 顶部注释）。
• 要发布/推送镜像？请勿在本地直接执行make cd；正确做法是使用make push DEV_IMAGE_PATH=<你的账号> DEV_IMAGE_TAG=<标签>推送到你自己的仓库，或交由 CI 系统以CONFIRM=true执行官方发布流程。
• 架构与宿主不一致？明确使用ARCH=arm64等参数，构建系统会自动注册 binfmt 并启用 clang 交叉编译，无需手动干预。
• 交叉编译的 CGO 差异：amd64 默认CGO_ENABLED=1（BPF/libbpf 需要），其余架构默认纯 Go 构建；在 amd64 主机上交叉编译时通过 clang + 系统根目录完成 CGO 编译，相关细节均可在 lib.Makefile 中溯源。

• 网络
• 云原生
• 网络安全