etcd 多 Go 模块仓库的依赖管理实践：升级顺序、自动化脚本与版本一致性保障

2026-09-05 23:32:03作者：冯梦姬Eddie

本篇技术指南基于 etcd 官方贡献者文档 dependency_management.md 展开，系统讲解 etcd 这个典型的多模块（multi-module）Go 仓库中，依赖升级的完整工作流：为什么 dependabot 对 etcd 不够用、多个模块共享同一依赖时应当遵循怎样的升级顺序、如何手工或用 update_dep.sh 脚本安全地升级依赖、Go 语言版本应如何随分支演进，以及 bbolt、raft 这两个核心依赖与 etcd 各版本的对应关系。读完后，你将能够独立完成一次跨模块的依赖升级 PR，并理解 make fix、BOM 清单和 verify-dep 校验在背后保证了什么。

一、为什么 etcd 需要专门的依赖管理策略

etcd 的 main 分支启用了 dependabot 来管理依赖，其调度配置见 .github/dependabot.yml，覆盖 github-actions、gomod 和 docker 三类生态，调度周期为每周（weekly）。但文档明确指出：dependabot 对 etcd 这类多模块仓库支持得并不好（原因对应上游 dependabot-core 的已知 issue），因此当 dependabot 自动提交升级 PR 时，通常需要人工介入处理。

etcd 的仓库结构本身就决定了这一点：仓库被拆分为多个独立 Go module（如 api、pkg、client/pkg、client/v3、server、etcdctl、etcdutl、tests 等），每个目录都有独立的 go.mod，并通过 go.work 工作区串接起来。同一个上游依赖（例如 github.com/spf13/cobra）会同时出现在多个模块的 go.mod 中——在当前仓库中可以看到 etcdctl/go.mod、server/go.mod、etcdutl/go.mod、go.mod 等均直接依赖 cobra，而 tests/go.mod 则是以 // indirect 标记间接依赖。这意味着依赖升级必须"跨模块同步"，而不能像单模块项目那样一蹴而就。

可直接合并的依赖 PR

文档区分了两类自动 PR：

工作流依赖（CI 中用到的 Actions 等）：此类自动升级 PR（例如升级 github/codeql-action、actions/checkout、ossf/scorecard-action）只要所有检查通过，就可以直接批准并合并，无需人工逐模块处理。
Go 模块依赖：则需要按下面的顺序化流程操作。

二、多模块升级顺序：先依赖方被依赖者

当多个 etcd 模块依赖同一个包时，必须按正确顺序升级。规则很简单：

如果模块 A 依赖模块 B，则先升级模块 B 的该依赖，再升级模块 A。 若两个模块互不依赖，则顺序无关紧要。

以 github.com/spf13/cobra 为例，文档给出的升级顺序是：

go.etcd.io/etcd/pkg/v3
go.etcd.io/etcd/server/v3
go.etcd.io/etcd/etcdctl/v3
go.etcd.io/etcd/etcdutl/v3
go.etcd.io/etcd/tests/v3
go.etcd.io/etcd/v3
go.etcd.io/etcd/tools/v3

其中 go.etcd.io/etcd/tools/v3 不依赖其他 etcd 模块、也不被其他模块依赖，所以它在任何时机升级都可以。

从源码结构看，这一顺序的本质是模块间的 require/replace 关系：例如 server/go.mod 中通过 replace 指令将 go.etcd.io/etcd/api/v3、go.etcd.io/etcd/pkg/v3 等指向仓库内兄弟目录（../api、../pkg），如果下游模块先声明了更高的依赖版本，Go 的 MVS（最小版本选择）会要求所有上游模块同步跟进，否则 CI 的模块一致性检查会失败。

三、手工升级一个依赖的完整步骤

以将 github.com/spf13/cobra 从 1.6.1 升到 1.7.0、目标模块 go.etcd.io/etcd/etcdctl/v3 为例，标准流程是：

cd ${ETCD_ROOT_DIR}/etcdctl
go get github.com/spf13/cobra@v1.7.0
go mod tidy
cd ..
make fix # 这会更新 bill of materials、Go modules 和 workspace 等

对所有模块执行同样的操作后提交：

git add .
git commit --signoff -m "dependency: bump github.com/spf13/cobra from 1.6.1 to 1.7.0"

注意事项（来自原文档，务必遵守）：

提交后应关闭 dependabot 自动打开的相关 PR，避免重复工作。
一个 PR 升级多个依赖时，建议每个依赖单独一个 commit（并非强制，例如可以把 go.etcd.io/etcd/tools/v3 的所有依赖升级放在一个 commit 中）。

`make fix` 背后实际做了什么

这一步是整个流程的关键，它把"改版本号"变成"全仓库一致性同步"。查看 Makefile 可以确认 fix 目标的组成：

fix: fix-mod-tidy fix-bom fix-lint fix-yamllint sync-toolchain-directive \
    update-go-workspace fix-shell-ws

逐项对应到脚本：

fix-mod-tidy → scripts/fix/mod-tidy.sh：对 workspace 中的每个模块执行 rm -f go.sum && go mod tidy，保证 go.mod/go.sum 与源码实际导入一致。
fix-bom → scripts/fix/bom.sh：使用 license-bill-of-materials 工具重新生成仓库根目录的 bill-of-materials.json（许可证物料清单），并固定以 GOOS=linux 生成以避免跨平台依赖差异。
update-go-workspace → scripts/update_go_workspace.sh：删除并按 git 中所有 go.mod 重新生成 go.work，同步 toolchain 指令为 .go-version 中的版本。
sync-toolchain-directive → scripts/fix/sync_go_toolchain_directive.sh：保持各模块 toolchain 指令一致。

这些脚本共同的遍历逻辑来自 scripts/test_lib.sh 中的 run_for_workspace_modules：它从 go.work 解析出所有工作区模块，依次进入每个模块目录执行命令，任一模块失败即中止。这就是"跨模块一致性"在工程上的落点。

四、自动化方案：`scripts/update_dep.sh`

前提：需要 bash 5.x 或更高版本。

作为手工步骤的替代，etcd 提供了 scripts/update_dep.sh 来自动完成跨模块升级：

# 升级到指定版本
./scripts/update_dep.sh github.com/spf13/cobra v1.7.0

# 升级到最新版本
./scripts/update_dep.sh github.com/spf13/cobra

脚本会依次完成 5 件事（与 update_dep.sh 的实现一一对应）：

打印该依赖在所有 go.mod 中的当前版本（print_current_dep_version）；
如果该依赖在所有模块中都是纯间接依赖（is_fully_indirect 通过 go list -m all 判定），给出警告并要求人工确认后才继续；
对每个依赖它的模块执行 go get 升级（update_module）；
运行 make fix-mod-tidy fix-bom update-go-workspace verify-dep 保证各模块间的一致性；
再次打印升级后的版本供人工核对。

阅读源码还能发现两个值得注意的工程细节：

纯间接依赖的特殊处理：go get 对间接依赖往往不生效，脚本因此先用 go mod edit -require 将其临时提升为直接依赖，升级后再由 go mod tidy 自动放回 // indirect 位置（见 update_dep.sh 中的注释）。
verify-dep 是真正的守门员：它对应 Makefile 中的 PASSES="dep" ./scripts/test.sh，最终执行 scripts/test.sh 里的 dep_pass 函数——汇总所有模块的 go list -m 输出，若同一依赖在不同模块中解析到不同版本，直接报错 FAIL: inconsistent versions。这正是"所有模块必须使用同一依赖版本"这条规则在 CI 中的自动执行。

五、故障排查：proto 生成失败

升级 protoc、protoc 插件或 grpc-gateway 版本时，可能因 *.proto 文件内容变化导致 CI 报错：

FAIL: 'genproto' FAILED at Wed Jul 31 07:09:08 UTC 2024
make: *** [Makefile:134: verify-genproto] Error 255

解决方法是从 etcd 仓库根目录重新生成 protobuf 绑定：

./scripts/genproto.sh

genproto.sh 会重新生成 api/ 目录下的全部 protobuf Go 绑定，并将变更提交进同一个 PR 即可。

六、间接依赖（Indirect dependencies）的处理原则

文档给出的决策树是：

所有模块都只是间接依赖 某个包（例如 github.com/go-logr/logr）→ 通常不主动升级。
间接依赖存在 CVE 或 bug 影响 etcd → 优先让引入它的外部模块（记为 M1）升级该依赖（记为 D1），etcd 只需升级 M1；若 M1 迟迟不升级，etcd 可以按前述流程直接升级 D1，但从长期看应尽量移除对这种缺乏维护的模块的依赖。
混合情况（部分模块直接依赖、部分模块间接依赖）→ 首选"对所有模块统一升级，无论直接还是间接"；若遇到障碍再临时退而求其次只升直接依赖，但最终目标是修复问题，让所有模块收敛到同一版本。

update_dep.sh 对纯间接依赖的确认提示、以及 dep_pass 的版本一致性检查，都是围绕这条原则设计的配套机制。

七、已知不兼容的依赖更新

文档记录了 arduino/setup-protoc 从 1.3.0 升级到 2.0.0 时遇到过的不兼容问题（对应上游一次升级 PR），提示维护者在处理该 Action 的版本跳跃时留意其行为变化，必要时参考当时的修复 PR 处理方式。

八、轮换值班表（Rotation worksheet）

由于 dependabot 的调度间隔是每周，它会每周自动开出一批依赖升级 PR，而每次都可能需要人工介入。etcd 社区为此维护了一张 Google 表格形式的轮换值班表，任何人注册后即可参与排班处理这些 PR。这是一条面向社区贡献者的低门槛参与路径：你不需要深入内核，只需按本文第二~四节的流程处理若干 PR。

九、稳定分支（Stable branches）的依赖策略

对稳定发布分支，etcd 不主动升级依赖，除非存在影响 etcd 的 CVE 或 bug。确实需要升级时，遵循与 main 分支相同的流程，但有一个版本差异要注意：release-3.4 分支没有 make fix（即没有 scripts/fix/mod-tidy.sh 这类修复脚本），因此升级到 3.4 分支时无需执行该步骤，需手工确认各 go.mod 的 tidy 状态。

十、Go 语言版本（Golang versions）的管理规则

文档按子项目性质给出两套 Go 版本策略：

子项目类型	示例	版本策略
独立库（无二进制产物）	bbolt、raft、gofail	所有分支（含 main）始终锁定最旧的受支持的 Go 小版本，把选择权交给库的使用方
产出二进制/镜像的子项目	etcd、etcd-operator、auger	main 分支用最新 Go 小版本开发；稳定发布分支用上一个受支持小版本的最新补丁，保证稳定性

etcd 开发分支升级 Go 小版本时，建议步骤为：

仔细阅读新 Go 版本的 release notes 及相关博客，关注弃用项、性能影响等；
先创建一个 GitHub issue 声明升级意图并邀请讨论；
在本地修改 .go-version 后运行 make fix 完成升级（当前 main 分支的 .go-version 为 1.26.6，与 go.work 中 toolchain go1.26.6 一致）；
本地跑性能基准测试，对比升级前后差异；
提交 PR。

稳定发布分支则维持"受支持 Go 版本的最新补丁"，小版本升级要在当前小版本停止受支持之前完成（依据 Go 官方发布政策）。

从源码结构看，.go-version 是整个构建体系的事实来源：scripts/test_lib.sh 中的 determine_go_version 会读取它并导出 GOTOOLCHAIN=go<version>，从而让构建、测试脚本统一使用该工具链；scripts/update_go_workspace.sh 生成 go.work 时也会把 toolchain 同步为该值。这解释了为什么文档强调"改完 .go-version 必须跑 make fix"——只有 fix 才能把 toolchain 指令传播到 workspace 和各模块。

十一、核心依赖的版本映射：bbolt 与 raft

文档最后给出了 etcd 与两个核心依赖的版本对应关系，并解释了 raft 的仓库迁移历史：

bbolt：etcd 3.4.x 与 3.5.x 依赖 bbolt 1.3.x；etcd 3.6.x 起依赖 bbolt 1.4.x。
raft：3.4 与 3.5 分支将 raft 直接包含在 etcd 仓库内（无外部 raft 模块依赖）；从 3.6 起 raft 迁移到独立的 go.etcd.io/raft 模块仓库，首个版本即 v3.6.0，etcd 3.6.0 对应 raft v3.6.0。