Development and Release zh

开发与发布

本页覆盖本地开发、验证、性能 profile、CI 和发布流程。

环境

主要技术栈：

• Go 1.26.4
• Fiber v3
• dix 用于依赖注入和生命周期管理
• collectionx、lo、mo 用于集合和 option 风格工具
• gocron 用于内部定时任务
• observabilityx 用于指标集成
• GoReleaser 用于 GitHub Release 资产和 Linux 安装包
• Docker Buildx 用于 GHCR 和 Docker Hub 镜像

常用开发命令

task test
task lint
task check
task build

• task test：运行 go test ./...。
• task lint：运行 golangci-lint run ./...。
• task check：运行 staticcheck。
• task build：构建当前平台 runtime binary。

性能和 profile

task perf:bench
task perf:bench:static
task perf:k6
task perf:k6:frontend
task perf:k6:split
task perf:aot:refine:baseline

Profile 命令：

task perf:profile:resolver
task perf:profile:cache
task perf:profile:pipeline
task perf:profile:http
go tool pprof .\tmp\perf\http.cpu.pprof

k6 系列任务需要 Docker。它们会构建 benchmark 镜像，并运行 SPACK direct、SPACK AOT、Nginx 和 k6 容器。

CI

GitHub Actions CI workflow 在 push 和 pull request 时运行：

• 从 go.mod 设置 Go
• 安装 Task
• task lint
• task check
• task test
• task build

当前 CI 覆盖：

• ubuntu-latest
• windows-latest

Tag 发布

常规发布由 tag 驱动：

task release VERSION=2.0.5

也可以自动递增版本：

task release:bump:patch
task release:bump:minor
task release:bump:major

Tag 使用 vX.Y.Z 格式。

本地发布流程

当 GitHub Actions 无法运行时，使用本地发布流程：

task release:local

该任务通过 Goyek 运行 scripts/release-local.sh，流程包括：

• 基于 docker/release-runner.Dockerfile 构建 Linux release runner 镜像。
• 在 Linux 容器中运行 GoReleaser，并使用 --skip=docker 生成 GitHub Release archives 和 Linux packages。
• 从 dist/ 整理 Docker 构建上下文。
• 推送 runtime Debian 镜像。
• 推送 compiler Debian 镜像。
• 推送 runtime Alpine 镜像。
• 校验镜像 manifest 和 GHCR package 可见性。

常用变量：

变量	默认值	含义
SPACK_RELEASE_TAG	最新 v* tag	要发布的 tag。
SPACK_RUNTIME_PLATFORMS	linux/amd64,linux/arm64	Runtime Debian 平台。
SPACK_COMPILER_PLATFORMS	linux/amd64	Compiler Debian 平台。
SPACK_ALPINE_PLATFORMS	linux/amd64	Runtime Alpine 平台。
SPACK_PUSH_GHCR	true	是否推送 GHCR tag。
SPACK_PUSH_DOCKER_HUB	true	是否推送 Docker Hub tag。

发布后验证

发布后运行：

task release:verify

该任务通过 Goyek 运行 scripts/release-verify.sh，它验证的是已发布镜像，而不是本地构建镜像。为了速度，默认关闭 compiler 侧图片变体生成；如果需要校验图片矩阵，可以设置 SPACK_IMAGE_ENABLE=true、SPACK_IMAGE_WIDTHS 和 SPACK_IMAGE_FORMATS：

• 检查 runtime、compiler 和 Alpine 镜像 manifest。
• 使用已发布 compiler 镜像编译一份 fixture dist。
• 校验生成的 .spack bundle。
• 启动 direct runtime 和 AOT runtime 容器，并启用只读 rootfs、drop all capabilities。
• 检查 /livez、HTML、JavaScript、Range 请求和浏览器风格图片请求。
• 确认无效的外部 .gz sidecar 不会被信任并作为 gzip 响应返回。

发布产物

GoReleaser 发布：

• GitHub Release archives
• checksums.txt
• Linux deb、rpm、apk 安装包
• Linux、macOS、Windows runtime archive
• Linux amd64 compiler archive

镜像：

ghcr.io/lyonbrown4d/spack
lyonbrown4d/spack
ghcr.io/lyonbrown4d/spack-compiler
lyonbrown4d/spack-compiler

Tags：

仓库	Tag	说明
spack	latest	Debian slim runtime 最新版本。
spack	<version>	Debian slim runtime 指定版本。
spack	debian	Debian slim runtime 最新版本。
spack	debian-<version>	Debian slim runtime 指定版本。
spack	alpine	Alpine runtime 最新版本。
spack	alpine-<version>	Alpine runtime 指定版本。
spack-compiler	latest	带 libvips 运行依赖的 Debian slim compiler 最新版本。
spack-compiler	<version>	带 libvips 运行依赖的 Debian slim compiler 指定版本。
spack-compiler	debian	带 libvips 运行依赖的 Debian slim compiler 最新版本。
spack-compiler	debian-<version>	带 libvips 运行依赖的 Debian slim compiler 指定版本。

v2.0.5 发布记录

• Release: https://github.com/lyonbrown4d/spack/releases/tag/v2.0.5
• Runtime Debian digest: sha256:e7a23b4bc3f64ce5cbf06b1ddd754557796eaeb44a035e23d607c60cd6ed77bb
• Runtime Alpine digest: sha256:16298d065a24421dacdba4446822e734c1c0cb2fa34fbaca30b299151d1d2536
• Compiler Debian digest: sha256:5823a000b3a05024abc09c7803a745bdff29be030f94afecada517f9bc937d71

v2.0.5 在 GitHub Actions 不可用时通过本地流程发布。GitHub Release 资产由 Linux 容器中的 GoReleaser 生成；镜像由 Docker Desktop 上的 Docker Buildx 推送。

贡献约定

• 优先通过 dix module/lifecycle 装配依赖。
• 面向 collection 的简化优先考虑 collectionx、lo、mo。
• 错误应使用 oops 包装并保留上下文。
• 不通过 nolint 或调整 lint 配置绕过问题。
• 避免在配置层暴露内部 scheduler 细节。
• 性能改动应补 benchmark，或至少运行相关 profile。