API网关云原生微服务【免费下载链接】kgatewayThe Cloud-Native API Gateway and AI Gateway项目地址https://gitcode.com/gh_mirrors/kg/kgateway点击查看免费下载本篇指南以仓库根目录的 RELEASE.md 与 devel/contributing/releasing.md 为主线系统讲解 kgatewayCloud-Native API Gateway / AI Gateway的双轨发布体系一方面通过自动化流水线为main分支的每一次合并构建可消费的滚动制品另一方面通过 GitHub Actions GoReleaser 编排 minor / patch 正式版本的安全发布。读完你将掌握 rollingmain版本的命名与 Helm 安装方式、正式发布的全部前置步骤、OSV 漏洞扫描与 CVE 处置、Release Notes 自动生成原理以及发布后文档与下游项目的同步流程。一、kgateway 的发布体系总览kgateway 的发布由两条相互独立又彼此衔接的链路组成Rollingmainbuilds滚动主分支构建针对合并到main分支的每个提交自动构建并发布制品让开发者和用户能提前验证尚未进入正式补丁或小版本的功能与修复。正式 Releaseminor / patch由维护者通过 release 工作流 手动触发workflow_dispatch产出语义化版本号Semantic Versioning 2.0.0的正式发布包括二进制、Docker 镜像、Helm Chart 与 GitHub Release。支撑这两条链路的仓库内关键文件包括.github/workflows/release.yaml发布主流水线含 setup / helm / stage / validate / load_tests / release-notes / publish / smoke 等作业.github/workflows/osv-scanner.yamlOSV 依赖漏洞扫描源码 镜像.github/workflows/nightly-tests.yaml对main与各 LTS 分支的每日回归、一致性conformance、负载与 e2e 测试hack/osvtoolOSV 告警查询与 CVE 处置入口脚本hack/generate-release-notes.shRelease Notes 生成脚本MakefileROLLING_MAIN_VERSION、release-notes、release-charts等关键变量的定义与目标的实现.goreleaser.yamlGoReleaser 配置负责构建多架构二进制与镜像。二、Rollingmain构建让每个合并提交都可测试2.1 机制与版本命名自动化已就位所有合并进main分支的提交都会触发构建与发布。其价值在于开发者与用户可以拿到包含最新特性与修复的具体制品进行测试而不必等到 patch 或 minor 正式版。rolling 构建的版本号是滚动的基于下一个 minor 版本号例如v2.4.0-main。该浮动版本并非手工维护而是读取 Makefile 中的变量ROLLING_MAIN_VERSION ? v2.5.0-main从当前仓库看main分支正在跟踪v2.5.0-main。在 release 工作流 的 setup 作业中针对refs/heads/main的 pushVERSION会被计算为$(make --no-print-directory print-ROLLING_MAIN_VERSION)-${GIT_SHA}即每个提交得到独立的v2.5.0-main-sha镜像标签避免并发 main 提交之间互相覆盖浮动标签v2.5.0-main只由仍然是main的 HEAD 的那一次运行来 promote下文详述。2.2 制品与消费方式构建出的制品会推送到 GHCRGitHub Container Registry并可通过 Helm Chart 直接消费。例如helm install kgateway-crds oci://cr.kgateway.dev/kgateway-dev/charts/kgateway-crds --version v2.4.0-main --namespace kgateway-system --create-namespace helm install kgateway oci://cr.kgateway.dev/kgateway-dev/charts/kgateway --version v2.4.0-main --namespace kgateway-system --create-namespace其中cr.kgateway.dev是官方仓库的 vanity registry 别名工作流中通过VANITY_REGISTRY变量区分官方kgateway-dev/kgateway仓库发布到cr.kgateway.dev/kgateway-dev个人 fork 则发布到ghcr.io/owner以保证 fork 上 release notes 中的安装命令指向真实存在的镜像。2.3 浮动标签的 promote 细节在rolling-charts作业中浮动 Chart 与镜像标签被一起promote且以该提交仍是 origin/main HEAD为条件git fetch origin main --depth1 HEAD_SHA$(git rev-parse origin/main) if [ ${HEAD_SHA} ! ${GITHUB_SHA} ]; then echo origin/main has moved past this commit; skipping floating tag promotion exit 0 fi对于kgateway、sds、envoy-wrapper三个镜像分别用docker buildx imagetools create将:VERSION复制为:FLOAT如v2.5.0-main及-amd64/-arm64子标签再执行make release-charts VERSION${FLOAT}。镜像先于 Chart 提升确保 Chart 解析到的镜像标签始终存在若中途失败也不会留下指向旧镜像的 Chart。三、正式发布流程概览正式发布通过GitHub Actions GoReleaser 流水线完成。kgateway 采用 Semantic Versioning 2.0.0MAJOR.MINOR.PATCH制品二进制、镜像等由 GoReleaser 构建并由 release 工作流 统一发布可通过workflow_dispatch按需运行。每次发布都从一个追踪 issue开始参考仓库内 .github/ISSUE_TEMPLATE/RELEASE-REQUEST.md 模板使每一步任务可见、可审计。工作流 dispatch 时提供两个输入version必填发布版本号必须以v开头且符合语义化版本预发布如v2.0.0-alpha.1允许但不允许 build metadata后缀因为版本号同时充当镜像/Chart 的 OCI tag而不是合法的 OCI 标签字符allow_missing_previous_version布尔默认 false是否允许跨越缺失的前置版本发布。前置条件确认拥有向 kgateway 仓库推送的权限后设置贯穿整个发布流程的环境变量export MINOR0 export REMOTEorigin如需重新克隆仓库git clone -o ${REMOTE} https://github.com/kgateway-dev/kgateway.git cd kgateway四、Minor Release创建发布分支与同步 CI 清单4.1 创建 release branch如果发布分支尚不存在则从main创建。分支命名规则为v2.${MINOR}.x例如v2.0.xgit checkout -b v2.${MINOR}.x git push ${REMOTE} v2.${MINOR}.x4.2 更新main上的滚动版本在main上通过 PR 将 Makefile 中的ROLLING_MAIN_VERSION提升到下一个 minor 的滚动标签。例如切出v2.3.x后将其设置为v2.4.0-main——因为main从此跟踪下一个 minor。4.3 将新分支加入 CI 工作流清单两个 CI 工作流硬编码了分支列表且都不会自动发现新分支因此新切出的分支若未列入清单将得不到任何 CI 覆盖.github/workflows/osv-scanner.yaml将其加入定时扫描矩阵branches[...]数组以及workflow_dispatch的分支选项。该 allowlist 是哪些分支会被扫描的唯一事实来源——hack/osvtool 与cve-bump技能都会解析该文件而非硬编码分支列表因此保持其最新即可。 注意其容错语义被 allowlist 但在被扫描仓库中不存在的分支、以及尚未发布到对应 registry 的 release 镜像会被标注并跳过而不是让运行失败——这保证了 fork 上的扫描保持绿色fork 通常只携带部分 release 分支且不发布 release 镜像而在kgateway-dev/kgateway上同样的缺口会以 error 级别标注使新切分支缺失扫描目标时在运行摘要中仍然可见。.github/workflows/nightly-tests.yaml将其加入determine_refs作业中定时运行使用的refs数组该数组驱动每日的 conformance、load 与 e2e 矩阵。4.4 退役 LTS 分支当某个 release 分支到达生命周期终点将其从上述两个工作流中移除OSV 的branches数组与workflow_dispatch选项、nightly 的refs数组。两份修改都只落在main上定时运行总是使用默认分支上的工作流定义尽管它分别 checkout 各 ref所以从main的矩阵中移除一个 ref 即全局退役它无需在 release 分支上做任何对应修改。同时删除仅用于让退役分支保持绿色的分支专属 workaround。分支退役后即停止被扫描不再出现在hack/osvtool输出中也无需在发布前进行 CVE 处置。五、OSV 扫描与 CVE 处置发布前的安全门发布前维护者需要基于将要发布的那个分支的 OSV 扫描结果清理那些会随制品发布的开源依赖漏洞。release 工作流本身不会自动执行这一处置因此它属于发布检查清单的一部分。如果使用 Codex、Claude Code 等 AI 编码工具cve-bump技能以cve-bump、Clear CVEs等方式唤起会包装该流程并以 hack/osvtool 为规范入口。手动操作时先以表格视图查看当前分支状态./hack/osvtool --table --target source --state todo ./hack/osvtool --table --target image --state todo--state todo只关注 critical 与 high 级别的发现--state open则展示全严重度视图--target source源码依赖发现--target image容器镜像发现。hack/osvtool会从 .github/workflows/osv-scanner.yaml 读取分支 allowlist因此其检查的分支始终与定时扫描工作流保持一致。针对特定发布分支拉取原始告警并逐一决策处置方式./hack/osvtool --raw --branch v2.3.x --target source --state todo ./hack/osvtool --raw --branch v2.3.x --target image --state todo常见的三种处置结果咨询有修复版本时将依赖升级到首个修复版本确认为误报时仅更新 osv-scanner.toml只允许放入无歧义的误报且每条必须写明误报原因以便复核暂无安全修复时保持 open 并推迟发布。依赖升级或 ignore 列表更新落地后注意镜像侧的更新只在 release 时才会生效手动重跑 osv-scanner GitHub Action 或等待其 nightly 运行再为发布分支重跑技能或hack/osvtool确认分支干净到足以发布。新增或退役 release 分支时务必先更新 OSV 工作流中的 allowlist再依赖其结果。六、Patch Release 与执行发布6.1 Patch 的来源Patch 版本从已有的 release 分支生成例如v2.3.x。在所有必要的 backport PR 合并之后即可进入发布阶段。6.2 触发发布打开 release 工作流 页面使用右上角的 Run workflow 下拉框发起发布选择要发布的分支minor 发布选择main分支patch 发布选择被修补的 release 分支如v2.3.x输入版本号例如v2.0.3。必须是v前缀的 semver 且无 build metadata带后缀会被拒绝因为版本号同时充当镜像/Chart 标签可选启用 Run load tests对暂存制品执行负载套件其结果不阻塞发布Allow missing previous version 保持不勾选除非确实在刻意跳过一个版本。6.3 版本号校验规则setup 作业会对输入版本执行严格校验正则匹配^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-prerelease)?$规则包括必须v前缀且为合法 semver预发布含大写的如v1.2.3-RC.1可接受拒绝后缀非合法 OCI tag 字符拒绝以-main、-amd64、-arm64结尾的版本这些后缀被保留给派生标签会造成镜像标签被覆盖或错配版本字符串长度不得超过 103 字符否则派生标签stage-sha-version、-amd64/-arm64会超出 OCI 标签 128 字符上限。随后调用 hack/ci/assert-release-version-valid.sh 做两道防重复校验版本未被发布过无 GitHub release、无 draft、无远端 git tag以及版本紧随其应有前置版本patch 要求前一 patch 已打 tag新 minor 要求上一 minor 有 GA 发布。该脚本只在发布安全时才以 0 退出任何其他情况都会自行说明原因并失败。七、流水线内部从 stage 到 publish 的多阶段安全门发布工作流按依赖关系组织为若干作业核心设计是先暂存、后校验、再提升setup计算版本、暂存标签、前置 tag 等发布路径的镜像暂存标签为stage-gitsha12-version非 semver避免消费自动化如 Kargo 在未验证前采用制品helm并行打包 Chart并验证 Chart 默认镜像 tag 能正确解析到发布版本stage运行make releaseGoReleaser 构建kgateway、sds、envoy-wrapper三个镜像的 amd64/arm64 双架构并打多架构清单随后对暂存副本执行容器结构测试container-structure-test配置见 test/container-structure/validate在 kind 集群中安装暂存 Chart运行 Gateway API Conformance 测试make all-conformance——这是发布路径上强制性的门load_tests可选、建议性运行负载测试与 xDS benchmark结果不阻塞 publishrelease-notes生成 Release Notes见下一节publish只有 stage镜像结构测试与 validateconformance都通过才将镜像从暂存 tag按 gated digest 逐字节复制docker buildx imagetools create --prefer-indexfalse提升到正式 tag并推送 Helm Chart推送的是校验过的那份.tgz字节而非重新打包最后组装 release body 并创建 GitHub Releasesmoke告警级别非门、不回滚用默认镜像 tag安装已发布的 Chart确认发布出去的 Chart 指向发布出去的镜像。7.1 防重复发布与可重入设计对已存在版本git tag 或 GitHub release的 dispatch 会快速失败并拒绝重新发布已完成发布的版本不会被重跑覆盖publish 作业在提升前再次用--skip-predecessor做最后检查防止运行期间版本被他人发布镜像提升循环是可安全重跑的重新复制已发布的 digest 是 no-op而已发布 tag 持有与 gated digest 不一致的字节则会中止而非覆盖若提升中途失败镜像/Chart tag 已发布但无 GitHub Release工作流会输出恢复指引在制品保留窗口内重跑是安全的若残留 draft release 先用gh release delete version --cleanup-tag删除。7.2 GitHub Release 的 Latest 判定publish 作业不会盲目将新版本标记为 Latest仅当新版本是非预发布 GA、且版本排序高于当前 Latest通过gh api查询并严格区分 404 与其它错误避免 API 波动时误判时才会--latesttrue。这避免了老分支的 backport patch如 v2.4.1 在 v2.5.0 之后抢走/releases/latest与徽标。八、Release Notes 自动生成与本地预览Release 工作流会自动运行make release-notes对应 Makefile 中的目标.PHONY: release-notes release-notes: ## Generate release notes (PREVIOUS_TAG required, CURRENT_TAG optional) ./hack/generate-release-notes.sh -p $${PREVIOUS_TAG:-} -c $${CURRENT_TAG:-HEAD}publish 作业会先把欢迎头部hack/release-notes/header.md.tmpl与安装/快速开始页脚hack/release-notes/footer.md.tmpl包在生成的变更日志外面再创建 GitHub Release因此无需手动步骤。底层的 hack/generate-release-notes.sh 工作流程用git log prev_tag..cur_ref从提交信息中提取所有 PR 编号通过 GitHub API 抓取 PR 详情失败时回退到 issue 端点提取 PR 描述中release-note代码块内的内容内容为 NONE/空则跳过按 PR 的kind/标签归类到固定章节breaking_change、feature、fix、deprecation、documentation、cleanup、install、bump对应 Breaking Changes / New Features / Bug Fixes / Deprecations / Documentation / Cleanup / Installation Changes / Dependency Updates章节顺序即优先级——一个 PR 带多个kind/*标签时归入优先级最高的章节带有 release note 但无任何可承载 note 的 kind 标签的 PR 会输出告警而非静默丢弃生成包含贡献者头像网格的 Contributors 章节输出到_output/RELEASE_NOTES.md。如需在本地预览即将发布的 Release NotesGITHUB_TOKENyour_token ./hack/generate-release-notes.sh -p v2.0.3 -c v2.1.0脚本参数-p/--previous-tag必填、-c/--current-tag默认 HEAD、-r/--repo默认kgateway-dev/kgateway、-o/--output默认_output/RELEASE_NOTES.md./hack/generate-release-notes.sh --help可查看全部选项。注意版本 tag 可能含 shell 元字符PREVIOUS_TAG必须以环境变量方式端到端传递不能展开到命令行。九、发布后验证与文档同步9.1 验证发布结果在 GitHub Releases 页面确认发布已公开且包含预期资产二进制归档与 checksums。随后按 quickstart 指南 走一遍安装流程确保新版本可用。注意在文档更新前需要手动把文档中的当前版本替换为新版本。9.2 更新 kgateway.dev 文档kgateway 文档库kgateway.dev 仓库必须更新以引用新版本最新稳定版本bump 文档使用的 kgateway 版本例如从 v2.0.3 升到 v2.0.4sed -i 1s/^2\.0\.3$/2.0.4/ assets/docs/versions/n-patch.md可选若 kgateway 升级了 Gateway API 依赖同步更新assets/docs/versions/k8s-gw-version.mdGW_API_VERSION$(cd ../kgateway go list -m sigs.k8s.io/gateway-api | awk {print $2} | sed s/^v// cd ../kgateway.dev) sed -i 1s/.*/${GW_API_VERSION}/ assets/docs/versions/k8s-gw-version.md历史版本文档kgateway.dev 不使用分支支持旧版本文档而是采用版本化目录 conref的方式。当 patching 非最新 minor如当前最新是 v2.1.0 时更新 v2.0.4 → v2.0.5时需要同步更新对应版本的目录与 conref。最后签名提交并推送FORKname_of_my_fork git commit -s -m Bumps Kgateway release version git push $FORK再从 fork 向上游 kgateway.dev 提交 PR。9.3 更新下游项目以下项目消费 kgateway发布后应更新或创建 issue 引用新版本patch 发布可选在llm-d-infra中创建 issue 并提交 PR 来 bump kgateway 版本且其 quickstart 指南应先用新 kgateway 版本测试通过再提交 PR。9.4 版本信息注入kgateway 二进制的版本号由 Makefile 通过 LDFLAGS 注入到 pkg/version/version.go 的version.Version变量-X github.com/kgateway-dev/kgateway/v2/pkg/version.Version$(VERSION)未设置时回退为undefined。发布工作流中VERSION负责打二进制标签ARTIFACT_TAG则作为镜像/清单标签release 路径上即stage-sha-version两者分工明确。十、常见问题与注意事项为什么版本号禁止build metadata因为版本号同时充当镜像与 Chart 的 OCI tag不是合法 OCI 标签字符。为什么 Chart 同时发布vX.Y.Z与X.Y.Z两个 tag它们由 Makefile 的release-charts目标对$(VERSION)与$(VERSION_NO_V)分别打包推送helm 从 Chart 内嵌版本号派生 OCI tag因此两个 tag 是真正不同的制品且两个版本都经过默认 tag 解析断言校验。fork 如何发布镜像 registry 使用ghcr.io/${{ github.repository_owner }}vanity registry 仅官方仓库启用fork 上的 release notes 页脚模板会指向 fork 自己的 ghcr保证安装命令可用。重新运行 publish 安全吗安全。提升循环按 gated digest 复制重放是 no-op任何持有非 gated digest 的已发布 tag 都会触发中止。务必在制品保留窗口7 天内重跑以复用同一批暂存镜像。CI 清单为什么必须手工维护两个 CI 工作流都不会自动发现新分支OSV allowlist 同时被扫描调度与hack/osvtool读取是分支扫描范围的单一事实来源任何增删都应先改它。版本发布流程的核心安全设计镜像在非 semver 暂存 tag 下构建 → 结构测试与 Gateway API conformance 对暂存副本校验 → 校验通过才按 digest 逐字节提升 → 完成后才创建 GitHub Release。每一步失败都会中止 publish且整套流程设计为可安全重入。赞分享API网关云原生微服务【免费下载链接】kgatewayThe Cloud-Native API Gateway and AI Gateway项目地址https://gitcode.com/gh_mirrors/kg/kgateway点击查看免费下载相关推荐Dendron 仓库发布实战指南Patch/Minor 版本发布与 Changelog 维护全流程Dendron 仓库发布实战指南Patch/Minor 版本发布与 Changelog 维护全流程 导读 Dendron 是一个以 monorepo 形式组织知识管理知识库Apache APISIX 版本发布全流程实战指南基于 MAINTAIN.md 的 Patch/Minor 发布与 Apache 社区投票机制详解Apache APISIX 版本发布全流程实战指南基于 MAINTAIN.md 的 Patch/Minor 发布与 Apache 社区投票机制详解 ApachAPI网关后端云原生微服务tldraw SDK 发布机制详解非语义化版本策略、minor/patch 发布流程与 GitHub Actions 实现tldraw SDK 发布机制详解非语义化版本策略、minor/patch 发布流程与 GitHub Actions 实现 tldraw SDK 采用一套区别前端UI组件上一篇Authelia 贡献者测试指南从覆盖策略到 SAST/DAST 与 Lint 全链路解析下一篇Czkawka 磁盘清理重复文件、相似图片、空文件夹一次扫描全找到创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考