• 包管理器
• 操作系统

本指南以 K3s 包维护文档 为核心骨架，系统讲解在 nixpkgs 仓库中维护 k3s 包的完整流程，包括 NixOS 发布周期内的版本策略、patch 升级脚本用法、包移除流程与变更审查清单。读者读完可以掌握update-script.sh的调用方式与内部原理、版本化包（如k3s_1_36）的增删流程，以及维护者审查 k3s PR 时的关键检查点。

为什么 k3s 需要专门的维护流程

与 bash 这类可以随nixos-rebuild switch原子升级的普通软件不同，k3s/Kubernetes 通常跨多台 NixOS 机器运行，且每台机器独立更新。新旧版本在集群中会短暂共存（version skew），因此 nixpkgs 必须维持一条不违背上游 Kubernetes 版本偏差政策的"升级路径"（upgrade path）。这一背景在 VERSIONING.md 中有详细论述，是理解本维护文档一切流程的前提。

k3s 基于 Kubernetes 构建，通常沿用与上游 K8s 相近的发布节奏与支持窗口：大约每 4 个月发布一个新版本，每个版本支持略超过 1 年。nixpkgs 据此在nixos-unstable分支上同时维护两类包：

• 标准k3s包：随上游新版本发布即时更新；
• 版本化包（如k3s_1_34、k3s_1_35）：遵循补丁发布支持生命周期，在上游 EOL 或早于nixos-stable中当前k3s版本时从nixos-unstable移除。

从 pkgs/top-level/all-packages.nix 可以看到当前的实际结构：仓库同时暴露k3s_1_34至k3s_1_37四个版本化包，且k3s = k3s_1_36;——标准别名指向当前最新版本化包。

NixOS 发布周期内的维护节奏

发布前（Pre-Release）

在下一个 NixOS 版本的 breaking change 窗口关闭之前，维护者需要在nixos-unstable上完成三件事：

1. 确保k3s指向最新版本化发布；
2. 确保发布说明（release notes）最新；
3. 提前移除将在下一个 NixOS 稳定版生命周期结束前上游 EOL 的 k3s 版本，并附带恰当的弃用通知（即下文"包移除流程"）。

这样做的目的是让即将冻结的 NixOS 稳定版只包含一个仍受支持的 k3s 版本，避免在稳定版支持周期内出现已弃用软件。

发布后（Post-Release）

对于 k3s 的major/minor 新版本：

• nixos-unstable：创建新的版本化包目录（如1_37/）；
• nixos-unstable：更新k3s别名指向新版本化包；
• nixos-unstable：新增 NixOS 发布说明，注明被移除的已弃用 k3s 包、以及来自 Kubernetes/k3s 项目的迁移信息；
• nixos-stable：回移（backport）该版本化包。

对于已有版本的patch 发布：

• nixos-unstable：按"Patch 升级流程"更新包版本；
• nixos-stable：回移在nixos-unstable上完成的更新。

稳定版之间的版本跨越策略

按 VERSIONING.md 的规划，每个 NixOS 稳定版发布时只应含一个 k3s 版本（如 24.05 为 1.30.x）。为了不强迫用户在升级 NixOS 稳定版时做违反版本偏差政策的大版本跳跃，维护者会把后续版本化包回移到当前稳定版。文档给出的三版本示例为：

• NixOS 23.11：k3s/k3s_1_27（发布版本，patch 回移）+k3s_1_28、k3s_1_29、k3s_1_30（回移）；
• NixOS 24.05：k3s/k3s_1_30（发布版本）+k3s_1_31、k3s_1_32（回移）；
• NixOS 24.11：k3s/k3s_1_32（发布版本）。

用户升级到新稳定版前，可先在旧稳定版上通过services.k3s.package依次指向k3s_1_31、k3s_1_32完成集群内小版本滚动，从而平滑跨过稳定版边界。

Patch 升级流程：update-script.sh 实操

基本用法

patch 升级可直接使用包根目录下的 update-script.sh。在 nixpkgs git 仓库根目录运行，例如升级 k3s 1.30.x：

./pkgs/applications/networking/cluster/k3s/update-script.sh "30"

只需把"30"替换为对应的 minor 版本号即可（当前仓库中可用"34"、"35"、"36"、"37"）。脚本会在执行结束时输出符合passthru.updateScript约定的 commit 描述 JSON（attrPath、oldVersion、newVersion、files），供 nixpkgs 的自动更新机制实现提交。

脚本内部流程

结合脚本源码，一次 patch 升级会依次完成以下工作（update-script.sh）：

1. 参数校验：MINOR_VERSION="${1:?Must provide a minor version number...}"强制要求传入 minor 版本号；
2. 获取当前版本：通过nix-instantiate --eval读取k3s_1_X.version，作为 OLD_VERSION 基线；
3. 查询上游最新 tag：调用 GitHub Releases API，过滤prerelease、排除rc/engine后缀，按版本号倒序筛选出v1.X.*的最新稳定 tag；
4. 定位 commit 与源码 hash：解析 tag 对应的 commit SHA，并用nix-prefetch-url --unpack计算 k3s 源码 tarball 的 store 路径与 sha256；
5. 推导依赖版本：在 store 内source scripts/version.sh（预置TAG、GITHUB_SHA等环境变量），得到 k3s-root、CNI plugins、containerd 等所有捆绑组件的版本与 hash。

随后脚本更新三个版本描述文件（update-script.sh）：

• chart-versions.nix：从k3s.io/k3s-charts/assets下载 traefik/traefik-crd chart，计算 sha256 后写入；脚本会校验 chart 数量恰好为 2，否则提示"New manifest charts added, the packaging scripts will need to be updated"并退出；
• images-versions.json：从该版本 Release 资产中筛选k3s-airgap-images-*.tar.*，结合官方sha256sum-{amd64,arm64,arm}.txt生成各架构 airgap 镜像归档的 url 与 sha256；
• versions.nix：写入k3sVersion、k3sCommit、k3sRepoSha256及所有组件版本，其中k3sVendorHash先用占位符FAKE_HASH，最后用nurl计算真实的 Go modules vendor hash 后sed替换。

失败处理与自动化

文档明确规定：脚本失败时第一目标是修复脚本本身；若无法修复，则用确切的命令和观察到的失败现象开 issue 报告。同时，RyanTM bot 可以自动执行 patch 升级，更新日志位于按版本组织的页面（例如 1.30.x 的日志页面）。这些日志可供维护者核对 bot 每次升级前后的版本变化。

包移除流程

版本化包的移除时间线遵循 VERSIONING.md 中的补丁发布支持生命周期。移除某个版本化包（如k3s_1_30）时，需要提交一个 PR 完成四件事：

1. 删除版本化目录：移除包含 chart 与包版本文件的目录（如./1_30/），即 1_34/、1_35/、1_36/、1_37/ 这类目录下的versions.nix、chart-versions.nix、images-versions.json；
2. 删除 default.nix 中的包块（如k3s_1_30 = ...）；
3. 删除 pkgs/top-level/all-packages.nix 中的包引用；
4. 在 pkgs/top-level/aliases.nix 中添加弃用通知，例如文档给出的模板：

   k3s_1_26 = throw "'k3s_1_26' has been removed from nixpkgs as it has reached end of life"; # Added 2024-05-20

当前仓库中已有实践范例：pkgs/top-level/aliases.nix 中保留了k3s_1_30至k3s_1_33的 throw 别名，均注明 "has been removed from nixpkgs as it has reached end of life" 及添加日期。这样既能让引用旧包的用户得到明确报错，又能通过别名保留迁移线索。

变更请求（PR）审查清单

文档为 k3s 包的审查者提供了快速检查清单：

1. Go 编译器版本是否按该 release 的 go.mod 文件锁定？注意：update script 不会锁定也不会更改 Go 版本，因此 PR 中任何 Go 版本调整都需要人工核对 go.mod；
2. K3s 的passthru.tests是否在所有受支持架构上通过？（x86_64-linux、aarch64-linux）
   • GitHub CI 上可用 OfBorg 测试所有平台；
   • 本地测试可在 nixpkgs 根目录、升级分支上运行：

     nix build .#k3s_1_29.passthru.tests.{etcd,single-node,multi-node}

     （将"29"替换为被测版本）

3. nix 构建日志或测试日志中是否有异常？

测试与构建器机制补充

从 builder.nix 的源码可以看到，passthru.tests的生成逻辑是：按k3s_+ 主次版本号（1.36→k3s_1_36）映射到nixosTests.k3s下的同名测试（etcd、single-node、multi-node等，排除all），也就是说nix build .#k3s_1_36.passthru.tests.etcd实际会构建对应的 NixOS 集成测试。

k3s 的构建本身分为两个阶段（builder.nix 注释有完整说明）：第一阶段用buildGoModule构建将被打包进"厚 k3s 二进制"的所有组件（CNI plugins、containerd-shim、k3s bundle），让它们都经过 nixpkgs 的自动 strip/patchelf 处理；第二阶段再把这些组件连同 k3s-root 的etc配置、traefik chart 一起通过go generate嵌入最终的单二进制k3s，并生成kubectl、crictl、ctr等多调用符号链接（builder.nix）。同时，builder 还通过k3sRuntimeDeps（kmod、socat、iptables、nftables、iproute2、ipset、bridge-utils、ethtool、util-linuxMinimal、conntrack-tools、runc、bash、shadow 等，builder.nix）在wrapProgram中注入 PATH，保证 kubelet 运行所需的宿主机工具可用。审查者若在日志中发现异常，可据此定位是捆绑组件问题还是运行时依赖缺失。

版本化包目录结构速览

当前每个版本目录（如 1_36/）固定包含三个文件，供维护者日常核对：

• versions.nix：核心版本清单，含k3sVersion、k3sCommit、k3sRepoSha256、k3sVendorHash，以及 k3s-root、CNI、containerd、cri-tools、flannel、kube-router、cri-dockerd、helm-controller 等全部捆绑组件的版本与 sha256；
• chart-versions.nix：traefik 与 traefik-crd 两个内置 chart 的 URL 与 sha256；
• images-versions.json：各架构 airgap 镜像归档（amd64/arm64/arm）的 URL 与 sha256，对应k3s.airgap-images-amd64-tar-zst等 passthru 属性。

版本化包的装配入口是 default.nix，它通过import ./builder.nix lib得到构造器，再对每个versions.nix调用callPackage，并把调用方（all-packages.nix）传入的额外参数向下透传，从而支持对 builder 的三处可覆写点：overrideBundleAttrs、overrideCniPluginsAttrs、overrideContainerdAttrs。

适用前提与限制

• 上述流程面向 nixpkgs 的 k3s 维护者与审查者，普通用户通常只需通过services.k3s.package选用合适的k3s或k3s_X_Y版本；
• update-script.sh依赖curl、git、go、jq、nurl、yq-go等工具（见脚本开头的 nix-shell shebang），并假设在 nixpkgs git 仓库根目录执行；
• 文档给出的版本示例（如 1.26、1.29、1.30）为历史策略示例，当前仓库实际维护的版本以 default.nix 中列出的k3s_1_34~k3s_1_37为准，nixos-unstable与各nixos-stable分支的具体情况可能随时间推移变化，请以各分支当前内容为准。

• 包管理器
• 操作系统