Skip to content

fix(docker): Go 构建镜像跟上 go.mod 的 1.26.6(否则任一 Dockerfile 构建都直接失败) - #5690

Merged
Wei-Shaw merged 1 commit into
Wei-Shaw:mainfrom
luckydududu:fix/dockerfile-golang-image-follows-gomod
Aug 17, 2026
Merged

fix(docker): Go 构建镜像跟上 go.mod 的 1.26.6(否则任一 Dockerfile 构建都直接失败)#5690
Wei-Shaw merged 1 commit into
Wei-Shaw:mainfrom
luckydududu:fix/dockerfile-golang-image-follows-gomod

Conversation

@luckydududu

Copy link
Copy Markdown
Contributor

问题

v0.1.177 起,用仓库里任意一个 Dockerfile 构建镜像都会直接失败

#32 [backend-builder 5/8] RUN --mount=... go mod download
#32 0.105 go: go.mod requires go >= 1.26.6 (running go 1.26.5; GOTOOLCHAIN=local)
ERROR: failed to solve: process "/bin/sh -c go mod download" did not complete successfully: exit code: 1

backend/go.mod 已经要求 go 1.26.6,而三个 Dockerfile 里的 Go 构建镜像还钉在 1.26.5。官方 golang 镜像设置了 GOTOOLCHAIN=local,不会自动下载更新的工具链,于是在 go mod download 这步硬失败。

复现步骤

git checkout v0.1.177
docker build -t sub2api:test .
  • 期望:构建成功
  • 实际backend-builder 阶段报上面那个错,退出码 1

deploy/Dockerfilebackend/Dockerfile 同理。

临时绕过办法(对根 Dockerfiledeploy/Dockerfile 有效,因为它们把版本写成了 ARG):

docker build --build-arg GOLANG_IMAGE=golang:1.26.6-alpine -t sub2api:test .

backend/DockerfileFROM golang:1.26.5-alpine 硬编码,没有这个口子。

原因

89d826be2修复:解决分组用量 PR 的 CI 失败,2026-08-14)把 backend/go.mod 提到了 1.26.6,并同步更新了三个 workflow 的版本断言,但没有动任何一个 Dockerfile

 .github/workflows/backend-ci.yml       | 4 ++--
 .github/workflows/release.yml          | 2 +-
 .github/workflows/security-scan.yml    | 2 +-
 backend/go.mod                         | 2 +-
 ...

在此之前,两者一直是同步的:

tag backend/go.mod Dockerfile
v0.1.171 1.26.5 1.26.5
v0.1.172 1.26.5 1.26.5
v0.1.173 1.26.5 1.26.5
v0.1.175 1.26.5 1.26.5
v0.1.176 1.26.5 1.26.5
v0.1.177 1.26.6 1.26.5

25a716960「Go 工具链升级 1.26.4 → 1.26.5」那次就是两边一起改的,所以这是一次回归,不是历来如此。)

为什么 CI 发现不了

三个 workflow 都用 actions/setup-go + go-version-file: backend/go.mod 取版本,跑的不是这些 Dockerfile;官方镜像发布走 goreleaser(在 runner 上编好二进制再塞进 alpine 基础镜像),也不经过 backend-builder 这条多阶段链。

于是这条链路没有任何自动化覆盖,只有自行用仓库 Dockerfile 构建的人会撞上。

checklist 里漏了 Dockerfile

DEV_GUIDE.md 里那条升级须知只列了 CI 文件:

升级 Go 时要同时改 backend/go.modbackend-ci.yml(两处)、release.ymlsecurity-scan.yml 里的这句断言

Dockerfile 不在清单里 —— 这才是这次漏改的直接原因,所以本 PR 一并把它补上。

修复

三个 Dockerfile 的 Go 构建镜像跟上 go.mod

文件 改动
Dockerfile ARG GOLANG_IMAGE=golang:1.26.5-alpine1.26.6-alpine
deploy/Dockerfile 同上
backend/Dockerfile FROM golang:1.26.5-alpine1.26.6-alpine

并把 DEV_GUIDE.md 的升级 checklist 补上这三个文件,同时点明两类遗漏的表现不同

前者漏了 CI 会在版本校验步骤直接失败;后者漏了 CI 不会报,而是等到有人用这些 Dockerfile 构建时才失败

关于「更省事的改法」

考虑过让 Dockerfile 从 go.mod 派生版本(构建时 grep '^go ' backend/go.mod)以杜绝再次漂移,没有采用:那需要在 Dockerfile 之外加一层包装或改变构建调用方式,对上游是侵入性改动;而仓库现有的做法(版本写死 + 文档 checklist)本来是有效的,这次只是 checklist 漏了一项。先把 checklist 补全,比改变构建模式更贴合现状。

如果维护者更倾向于加一个 CI 检查(比对 go.mod 与 Dockerfile 的版本,不一致就红),我可以另开一个 PR —— 本 PR 按「不改 CI 配置」的惯例没有涉及。

测试

双向证据(实际构建,非推演):

条件 结果
修复前(默认 GOLANG_IMAGE=golang:1.26.5-alpine go mod download 失败:go.mod requires go >= 1.26.6 (running go 1.26.5; GOTOOLCHAIN=local)
修复后(golang:1.26.6-alpine ✅ 完整多阶段构建通过,镜像产出正常

修复后的镜像已在实际环境运行验证:应用正常启动、/health 通、v0.1.177 的两个新迁移(222_group_usage_daily_rollups / 223_group_usage_rollup_timezone)正常执行并落库。

本 PR 不含任何 Go 代码改动git diff --name-only.go 文件),因此 gofmt / go build / 两档 go test 的结果与 base 完全一致。

影响面

  • 只影响构建阶段,运行时行为零变化
  • 1.26.5 → 1.26.6 是补丁版本升级,go.mod 已经要求它,CI 也已经跑在这个版本上 —— 本 PR 只是让 Dockerfile 追上,不引入新的版本要求
  • 三个 Dockerfile 全部覆盖,避免只修一处留下另外两处

附带说明(本 PR 未处理)

README.md / README_CN.md / README_JA.md 里的徽章和技术栈表格仍写着 Go 1.26.5。那些是展示性内容、不影响构建,为避免在本 PR 里混入无关 diff 没有一并改。需要的话我另开一个文档 PR。

89d826b raised backend/go.mod to `go 1.26.6` and updated the three CI
workflows' version assertions, but left the Go builder image in all three
Dockerfiles pinned at 1.26.5. Since the official golang images set
GOTOOLCHAIN=local, the toolchain is not auto-downloaded and any image build
fails hard at `go mod download`.

CI does not catch this: the workflows build with actions/setup-go, not with
these Dockerfiles.

Also extend the Go-upgrade checklist in DEV_GUIDE.md, which listed only the
CI files -- that omission is why the Dockerfiles were missed.
@Wei-Shaw
Wei-Shaw merged commit 51016bb into Wei-Shaw:main Aug 17, 2026
8 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Aug 17, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants