企业官网建设流程全解析

k3s 发布说明（Release Notes）生成与验证指南：从 ecm-distro-tools 到组件版本核验的完整实操

【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s

导读

k3s 是一个轻量级 Kubernetes 发行版，其每次发版（RC 与 GA）都伴随一份面向用户与维护者的发布说明。本指南基于 k3s 官方发布流程中"创建发布说明 PR"的完整步骤，讲解如何借助ecm-distro-tools自动生成发布说明、如何核对 PR 与 commit 的准确性、以及如何验证 Kubernetes、Containerd、Flannel、CoreDNS 等全部随版本组件版本号的正确来源。读完本文，你将掌握一条可复现的、从生成到校验的发布说明产出链路，并能在当前仓库中逐行定位每个组件版本的"事实出处"。

适用说明：文中命令与流程以 k3s 仓库 docs/release/expanded/release_notes.md 为骨架，示例版本号（如 v1.23.13-rc1+k3s1）为官方文档的历史示例；版本核验规则以当前仓库实际内容为准，具体组件版本请以你所在 tag 的仓库状态为准。

一、发布说明在整个发布流程中的位置

k3s 的发布流程在 docs/release/release.md 中有完整串联：先为 k3s-io/kubernetes fork 生成新 tag，再更新 k3s 仓库并提交 PR，随后进入 RC 发布阶段（cut release → 更新 KDM → 检查镜像 → 生成/更新发布说明）。无论是 RC 还是 GA，发布说明（release notes）都是收尾前的固定环节，且 GA 阶段需要把已合并的发布说明内容复制进正式 Release。其前后依赖见：

• cut release：创建 RC 的 GitHub Release，标题即版本号（如v1.25.0-rc1+k3s1）；
• channel server：GA 定稿后更新渠道服务器。

也就是说，"生成发布说明 PR"这件事本身不是孤立的，它发生在代码已打 tag、CI 已通过之后，目的是把两次发布之间的全部变更整理成机器可读、人可审的清单。

二、第一步：用 ecm-distro-tools 生成发布说明

k3s 官方使用 Rancher 的ecm-distro-tools发布工具镜像来生成发布说明，该工具需要有效的 GitHub Token 才能访问仓库与 PR 数据。

典型调用方式（示例版本为v1.23.13-rc1+k3s1）：

# 输出到 stdout export GHT=$GITHUB_TOKEN export PREVIOUS_RELEASE='v1.23.12+k3s1' export LAST_RELEASE='v1.23.13-rc2+k3s1' docker run --rm -e GITHUB_TOKEN=$GHT rancher/ecm-distro-tools:latest \ gen_release_notes -r k3s -m $LAST_RELEASE -p $PREVIOUS_RELEASE

参数含义：

运行前提：本机安装 Docker，且GITHUB_TOKEN已配置为具有该仓库读取权限的 Token。命令输出的是发布说明正文（stdout），可直接作为后续编辑的起点。

三、第二步：修正标题、版本行与"变更区间"表述

工具生成的初稿不能直接使用，需要按以下规则手工修订：

1. 首行写入目标版本 semver：例如<!-- v1.25.3+k3s1 -->。该注释行供脚本与后续自动化识别版本号。
2. 标题必须包含新的 Kubernetes 版本，例如This release updates Kubernetes to v1.25.3, and fixes a number of issues.。
3. "changes since" 行必须写旧版本号，例如## Changes since v1.25.2+k3s1。

这三处的共同目的，是让读者（以及解析该 Markdown 的工具）一眼能看出"从哪个版本升到哪个版本、Kubernetes 升级到了什么小版本"。

四、第三步：验证变更清单的完整性

发布说明的"changes since"部分必须与真实合并的 PR 一一对应，官方给出了细致的核对流程：

1. 确定上一个发布的真实日期：进入 GitHub Releases 页面找到上一个 release，把页面上的 "XX days ago" 换算为具体日期。

2. 按分支与时间筛选 PR：在 GitHub Issue 搜索 UI 中搜索指定分支、指定日期之后合并的 PR，例如：

   is:pr base:release-1.23 merged:>2022-09-28 sort:created-asc

   其中release-1.23是发布分支，2022-09-28是上一个发布的日期。

3. 逐条核对 PR 标题与 commit message：

   • 每个 PR 标题（或其首个评论中的 "release note" 段落）都应成为发布说明中的一个条目；
   • 每条目的末尾应附带指向该 PR 的链接；
   • 该 PR 的 commit message 紧随其后，直到下一个 PR 为止。

4. 怀疑有缺失/多余 commit 时对比 tag：使用 GitHub 的 compare 功能对比旧 tag 与新 tag，例如v1.25.2+k3s1...v1.25.3-rc2+k3s1，可暴露出区间内全部新增 commit；再在 commit 页面找到其关联的 merge issue，确认该 issue 是否已收录进发布说明。若该 commit 不在本次对比区间内，则回退对比更早的两个 tag（如v1.25.0+k3s1...v1.25.2+k3s1）继续排查。

5. backport 条目必须引用 backport issue：如果发布说明中需要加入 backport 变更，链接应指向 backport 对应的 issue，而不是 main 分支上的原 issue。

这一步是整个发布说明质量的核心：保证"每个真实合并的 PR 都有条目，每个条目都对应真实 PR"。

五、第四步：验证随版本组件的版本号

k3s 的发布说明中有一份"released components"清单，用于列出随版本一起发布的所有组件。官方明确：这份组件列表是完全静态的，除非有人在 PR 中提出，否则不需要增删。当前文档列出的组件包括：

Kubernetes、Kine、SQLite、Etcd、Containerd、Runc、Flannel、Metrics-server、Traefik、CoreDNS、Helm-controller、Local-path-provisioner

版本核验的关键原则是：k3s 仓库内的 scripts/version.sh 是版本信息的"单一事实来源"（source of truth），按以下顺序在对应 tag 下逐级查找：

1. 先在version.sh中搜索组件名；
2. 找不到则查构建脚本 scripts/build；
3. 仍找不到则查仓库根目录 go.mod；
4. 少数以 Helm Chart / Manifest 形式分发的组件，查 manifests 目录下的对应清单文件。

5.1 当前仓库中各组件版本的实际出处

以当前仓库为例，可以在下列文件中逐一验证（注意：你验证某个发布版本时，应在该发布对应的 tag上查看这些文件，而不是 main 分支）：

• Kubernetes：version.sh通过get-module-version k8s.io/kubernetes从 go.mod 获取（见 scripts/version.sh）。当前 go.mod 中k8s.io/kubernetes => github.com/k3s-io/kubernetes v1.36.3-k3s1，即 k3s fork 的 Kubernetes。
• Kine / SQLite / Helm-controller / Flannel / Runc / Etcd / Containerd / CRI-tools / kube-router：同样来自 go.mod 的 replace/require 块，例如：
  • github.com/k3s-io/kine v0.16.3（go.mod）；
  • github.com/k3s-io/helm-controller v0.17.7（go.mod）；
  • github.com/k3s-io/containerd/v2 v2.3.2-k3s2（go.mod）；
  • github.com/opencontainers/runc v1.4.2（go.mod）；
  • github.com/flannel-io/flannel v0.28.4（go.mod）；
  • go.etcd.io/etcd/server/v3 => github.com/k3s-io/etcd/server/v3 v3.6.14-k3s1（go.mod）；
  • github.com/k3s-io/cri-tools v1.36.0-k3s1（go.mod）。
• runc 的特殊性：如官方文档所强调，runc "有点怪"——它不信任 go.mod，而是优先采用version.sh中设置的环境变量，该变量被下载脚本（scripts/download）拾取，再由构建脚本对下载产物执行 make。version.sh中还固化了VERSION_CNIPLUGINS="v1.9.1-k3s1"、VERSION_FLANNEL_PLUGIN="v1.9.0-flannel1"等非 go module 管理的版本。
• Metrics-server：镜像版本写在 manifests/metrics-server/metrics-server-deployment.yaml 中（rancher/mirrored-metrics-server:v0.9.0），同时可看到其启动参数（--metric-resolution=15s、--secure-port=10250等）。
• Traefik：Chart 与镜像版本写在 manifests/traefik.yaml（traefik-40.1.4+up40.1.0.tgz、镜像 tag3.7.8）。
• CoreDNS：镜像版本写在 manifests/coredns.yaml（rancher/mirrored-coredns-coredns:1.14.6），Corefile 中还可见 k3s 的%{CLUSTER_DOMAIN}%等模板占位符。
• Local-path-provisioner：版本写在 manifests/local-storage.yaml（rancher/local-path-provisioner:v0.0.37）。

5.2 从源码理解 version.sh 的取值机制

scripts/version.sh 中两个关键函数值得了解：

get-module-version(){ go list -mod=readonly -m -f '{{if .Replace}}{{.Replace.Version}}{{else}}{{.Version}}{{end}}' $1 } get-module-path(){ go list -mod=readonly -m -f '{{if .Replace}}{{.Replace.Path}}{{else}}{{.Path}}{{end}}' $1 }

它们用go list -m读取模块版本，且优先返回 replace 后的版本——这正是 k3s 大量使用 fork（github.com/k3s-io/...）时版本仍能正确归位的原因。同时该脚本会在存在GIT_TAG时校验 tag 是否匹配$VERSION_K8S[+-]*，不匹配即报错退出；没有 tag 时则以$VERSION_K8S+k3s-${COMMIT:0:8}$DIRTY作为开发版本号，其中COMMIT、DIRTY来自 scripts/git_version.sh（-dirty后缀表示工作区有未提交改动）。因此发布说明中的版本号本身也与这套脚本的计算逻辑严格一致。

六、理解发布说明的段落结构

官方文档明确了发布说明中的两个主要段落：

• changes since：汇总自上一个发布以来的全部变更。更具体地说，期间每个合并的 merge issue（PR）都应有一个条目。开发者可以在自己的 PR 中添加一个特殊的"User-Facing Change"段落来提供自定义说明，这些说明会作为该 issue 标题下的子条目出现在发布说明中。这一机制保证了"面向用户的变更"不会被埋没在大量内部提交里。
• released components：列出本次发布中的所有 Kubernetes 组件。官方强调，这些组件一般是非 Kubernetes 核心、通过 Helm Chart 安装的附加组件（如 Traefik、CoreDNS、Metrics-server、Local-path-provisioner 等），它们不在 kubelet/apiserver 二进制内，而是作为系统组件随集群启动部署。这正好解释了为什么它们的版本要单独在 manifests 目录的 HelmChart/Deployment 清单中查找。

七、实操要点与常见误区

1. 版本核验必须对着 tag 而不是 main：官方流程要求"浏览要验证的发布版本对应的 tag"，因为 main 分支上的版本号与历史发布无关。核验时请切换到目标 tag 再查看version.sh、scripts/build、go.mod、manifests。
2. 组件列表是静态的：不要凭感觉增删组件；若确实需要调整，应在对应 PR 中明确提出，由维护者共同确认。
3. runc 别用 go.mod 判断：runc 版本以version.sh为准（历史上 go.mod 可能滞后或被 fork 覆盖），这是官方文档特别标注的反例。
4. backport 用 backport issue：链接错了 issue，读者就无法追踪到真实的修复来源。
5. "changes since" 与 PR 一一对应：宁可多花时间用 compare 工具逐 commit 排查，也不要让发布说明与实际合并历史出现偏差。

八、结语

一份合格的 k3s 发布说明 = 工具自动生成（ecm-distro-tools）+ 人工修订元信息（版本、标题、区间）+ 逐 PR 验证（搜索/compare/backport 溯源）+ 组件版本四级核验（version.sh→scripts/build→go.mod→manifests）。这套流程对维护者而言是发布质量的红线，对使用者和贡献者而言，则是理解"当前版本到底升级了什么、每个组件版本从哪来"的最佳入口——下次你在 Release 页面看到长串组件版本时，现在你已知道该去哪里逐个验证它们了。

【免费下载链接】k3sLightweight Kubernetes项目地址: https://gitcode.com/GitHub_Trending/k3/k3s