builder

制作 Kubernetes 离线安装包（apt/dnf/yum 软件包 + 运行时 + 镜像）的 Go CLI 工具。

生成的离线包包含：

k8s 软件包：kubeadm / kubelet / kubectl（容器内通过 apt/dnf/yum 递归下载，依赖闭包交给包管理器）
容器运行时软件包：containerd / cri-tools（containerd 按 OS 配置获取：默认阿里云镜像 mirrors.aliyun.com/docker-ce 的 docker-ce 源包名 containerd.io，openEuler 等从系统源安装 containerd；runc 由 containerd 包内嵌提供，不单独安装；containerd 源 + 系统源）
系统依赖软件包：conntrack、ipvsadm、nfs-common(-utils)、socat、ebtables、chrony
镜像：核心镜像（容器内安装 kubeadm 后生成清单）+ 附加组件镜像（builder.yaml addon_images 节）
附加安装包：附加组件所需的宿主系统软件包（builder.yaml 顶层 addon_packages 节，name + 可选 version，mode ∈ packages/all 且未跳过附加时并入软件包清单；version 空不锁版本，非空按目标包管理器语法转译）
安装脚本：install.sh（包安装 + preflight）/ load-images.sh
完整性清单：manifest.yaml（可校验）

软件源说明：k8s 组件（apt 与 dnf/yum 系）均使用阿里云 mirrors.aliyun.com/kubernetes-new（仓库由 k8s 版本自动推导，v1.27.3 → v1.27）； containerd 默认来自阿里云镜像 mirrors.aliyun.com/docker-ce（containerd_repo=aliyun，包名 containerd.io），可配置 ustc=中科大 mirrors.ustc.edu.cn/docker-ce / docker=官方 download.docker.com / none=系统源。原 packages.containerd.io 域名在当前网络与公共 DNS（223.5.5.5 / 8.8.8.8）均 NXDOMAIN 无法解析，已改用国内镜像提供 containerd.io 包。该源的 containerd.io 包内嵌 runc 二进制，故不再单独安装 runc 包，避免与独立 runc 包的 Conflicts: runc 冲突导致 apt 无法同时解析。 openEuler 例外：docker 官方无 rhel/7 仓库（download.docker.com/linux/rhel/7/ 为 404），openEuler 改用系统源安装 containerd（containerd_pkg: containerd + containerd_repo: none，从 everything 仓库安装 containerd 包），不配置 docker-ce 源。

快速开始

# 构建 CLI
go build -o builder ./cmd/builder
# 构建软件包（dry-run 演练）
./builder build packages --os ubuntu --os-version 22.04 --kubernetes-version v1.31.6 --arch amd64 --dry-run
# 构建软件包（需联网 + 本机 containerd/ctr；可用 --runtime docker 改用 docker）
./builder build packages --os ubuntu --os-version 22.04 --kubernetes-version v1.31.6 --arch amd64 --out ./dist
# 构建镜像（无需 --os；产物 pixiu-images-{arch}-{k8s}.tar.gz）
./builder build images --kubernetes-version v1.31.6 --arch amd64 --out ./dist
# 多版本并发构建镜像并上传到 images Release
./builder build images \
--kubernetes-version v1.31.7 \
--kubernetes-version v1.31.8 \
--kubernetes-version v1.31.9 \
--arch amd64 --upload
# 校验离线包（目录或 tar.gz）
./builder verify --bundle ./dist/pixiu-images-amd64-v1.31.6.tar.gz

build 执行时按 5 步管线实时输出 [builder] 前缀日志（步骤开始 / 完成 / 跳过 / 失败，dry-run 额外标注），便于跟踪长耗时构建；结束后打印构建步骤汇总表。

命令一览

命令	说明
`build packages`	构建软件包离线包。需 `--os` / `--os-version` / `--kubernetes-version`（`--only-addons` 时可省略 k8s 版本）。产物：`pixiu-packages-{os}-{osver}-{arch}-{k8s}.tar.gz`。`--upload` 上传到以 k8s 版本为名的 Release
`build images`	构建镜像离线包（无需操作系统）。需 `--kubernetes-version`（可重复；多版本时并发构建与上传，上限 10）。产物：`pixiu-images-{arch}-{k8s}.tar.gz`。`--upload` 默认到 `images` Release；kubeadm 下载未指定 `--github-tag` 时优先 k8s 版本 Release（与 `sync kubeadm` 一致），再回退 `images`
`build servers`	构建平台服务镜像离线包。只读 `server_images`（格式同 `addon_images`）；无需`--os` / `--kubernetes-version`；忽略 `--skip-addons` / `--only-addons`；空配置报错。产物：`pixiu-server-images-{arch}.tar.gz`。`--upload` 默认 tag=`download`
`upload`	将已有产物 tar.gz 上传到 GitHub Release。`--file` 可重复；`--github-*` 覆盖配置节
`sync kubeadm`	创建以 k8s 版本为名的 GitHub Release，并上传 kubeadm 二进制。默认单版本；`--all` 同步全部 >= v1.31.0 的正式版本
`sync builder`	交叉编译 `builder-{arch}` 并上传到 GitHub Release（默认 tag=`builder`；默认 arch=amd64+arm64）
`sync client`	拉取 rainbow，交叉编译多平台 `pixiuctl-{version}-{os}-{arch}` 并上传（默认 tag=`pixiuctl-{version}`）
`serve`	加载离线产物，提供本地 OCI registry（`docker pull` 短名）与 yum/dnf/apt HTTP 软件源（纯 Go，无外部工具依赖）
`images`	列出 serve registry 镜像（类似 `docker images`；`--limit` 默认 50）
`packages`	列出 serve 软件源安装包（deb/rpm；`--limit` 默认 50）
`ls`	列出指定仓库的 tag（`builder ls <repository>`）
`verify`	校验 bundle（目录或 tar.gz）完整性
`version`	打印版本

构建子命令

子命令	构建内容	产物名	上传 Release
`build packages`	软件包（k8s/运行时/系统依赖）+ 脚本 + manifest	`pixiu-packages-{os}-{osver}-{arch}-{k8s}.tar.gz`	k8s 版本（或 `--github-tag`）
`build images`	镜像（核心 + 附加组件）+ 脚本 + manifest	`pixiu-images-{arch}-{k8s}.tar.gz`	`--github-tag`（默认 `images`）
`build servers`	平台服务镜像（仅 `server_images`）+ 脚本 + manifest	`pixiu-server-images-{arch}.tar.gz`	`--github-tag`（默认 `download`）

被跳过的步骤在构建汇总中标记为 skipped（非失败）。build images / build servers 不需要操作系统参数。

# 软件包
./builder build packages --os ubuntu --os-version 22.04 --kubernetes-version v1.31.6 --arch amd64
# 镜像（无需 --os；可 --upload 到 images Release）
./builder build images --kubernetes-version v1.31.6 --arch amd64 --upload
# 多版本并发构建并上传
./builder build images \
--kubernetes-version v1.31.7 \
--kubernetes-version v1.31.8 \
--kubernetes-version v1.31.9 \
--arch amd64 --upload
# 平台服务镜像（读 server_images；可 --upload 到 servers Release）
./builder build servers --arch amd64 --upload

镜像打包默认使用 containerd 模式：用 Go 客户端直拉 registry 并写成 docker-save tar（不依赖 ctr export）。packages 阶段仍用宿主机 ctr run。--runtime docker 时用 --pack-image 工具容器（默认 swr.cn-north-4.myhuaweicloud.com/pixiu-public/pixiukit/docker:24-cli，仅 amd64）。ARM 宿主走 docker 模式时须指定 arm64 兼容 pack 镜像：

# ARM64 宿主 + docker 模式
./builder build images --kubernetes-version v1.31.6 --arch arm64 --runtime docker --pack-image <your-registry>/pixiukit/docker:24-cli-arm64

多版本并发时，各版本构建过程中不立刻清理中间镜像；全部结束后去重再统一清理（--keep-files 时仍保留）。

自定义附加组件（addon_packages / addon_images）

核心软件包（kubeadm/kubelet/kubectl + containerd + cri-tools + 系统依赖）与核心镜像（kubeadm 生成）始终使用默认清单，不再支持按包/镜像覆盖或追加参数。containerd 包名与来源由 oses 节 containerd_pkg / containerd_repo 配置（默认 containerd.io + 阿里云镜像；openEuler 为 containerd + 系统源）；这两个字段未配置时按发行版代码内推断（openEuler → containerd + none，其他 → containerd.io + aliyun），因此旧版 builder.yaml 无需更新也能正确获取 openEuler 的 containerd。自定义能力完全由顶层 addon_packages / addon_images 与子命令 / --only-addons / --skip-addons 提供：

参数	说明	示例
`--skip-addons`	跳过附加组件：`addon_images` 不进镜像清单、`addon_packages` 不并入软件包清单（仅核心）	`--skip-addons`
`--only-addons`	只打包附加组件：核心软件包与核心镜像全去，软件包=`addon_packages`、镜像=`addon_images`；与 `--skip-addons` 互斥。此时 `--kubernetes-version` 可省略（不构建 k8s 核心，无需推导 k8s 版本）；且只配置系统源（addon_packages 全部来自系统源，不再配置 k8s/containerd 源）	`--only-addons`

# 软件包：核心 + addon_packages
./builder build packages --os ubuntu --os-version 22.04 --kubernetes-version v1.27.3 --dry-run
# 镜像：核心 + addon_images
./builder build images --kubernetes-version v1.27.3 --dry-run
# 跳过附加组件（仅核心）
./builder build packages --os ubuntu --os-version 22.04 --kubernetes-version v1.27.3 --skip-addons --dry-run

附加组件与子命令联动：addon_packages 在 build packages 且未 --skip-addons 时并入软件包清单；addon_images 在 build images 且未 --skip-addons 时并入镜像清单。详见下文。

附加组件配置与构建子命令联动

附加组件由两处顶层配置提供，均与 build packages / build images / --only-addons / --skip-addons 联动：

addon_images：附加组件镜像清单（name → image:tag）。build images 且未 --skip-addons 时并入镜像清单（与核心镜像去重）；--only-addons 时为其镜像主体（核心镜像全去）。镜像条目支持单版本 tag 与同镜像多版本 tags 两种写法：tags 会在构建时展开为多个拉取/保存任务，tar 文件名按 {name}-{tag}.tar 命名（如 kubez-ansible-v2.0.2.tar），manifest 中每个镜像条目的 source_image 均为含对应 tag 的完整引用，builder serve 可据此发布同一 repo 的多个 tag。
addon_packages：附加安装包列表（对象格式：name + 可选 version）。build packages 且未 --skip-addons 时并入软件包下载清单（与核心清单按包名去重）；--only-addons 时为其软件包主体（核心软件包全去）。version 为空（或省略）不锁版本，透传纯包名；非空按目标包管理器语法转译（apt 系 name=version、dnf/yum 系 name-version），见下方示例。

# 附加组件镜像（仅镜像；不含软件包）# 单版本用 tag（tar 文件名即 {name}.tar）；同一镜像多版本用 tags（构建时展开为多个 tar，文件名 {name}-{tag}.tar）addon_images:
- name: flannelimage: "swr.cn-north-4.myhuaweicloud.com/pixiu-public/flannel/flannel"tag: "v0.24.2"
- name: metrics-serverimage: "registry.k8s.io/metrics-server/metrics-server"tag: "v0.6.4"
- name: kubez-ansibleimage: "ccr.ccs.tencentyun.com/pixiucloud/kubez-ansible"tags: ["v2.0.2", "v3.0.3"]# 附加安装包（与 addon_images 平级；部署附加组件需要的宿主系统软件包）# 对象格式：name = 包名（apt/dnf 通用名，须与目标系统源匹配）；version 可选。# version 为空（或省略）= 不锁版本，透传纯包名给容器内包管理器；# version 非空 = 锁定版本，按目标包管理器语法转译：apt 系 name=version、dnf/yum 系 name-version# （版本需与目标系统源匹配，不匹配时由容器内包管理器报错，请自行调整）。addon_packages:
- name: conntrackversion: ""# 不锁版本：并入清单时透传 conntrack
- name: vimversion: "9.0"# apt 系 → vim=9.0；dnf/yum 系 → vim-9.0

--only-addons 与 --skip-addons 互斥（同时传报错）：

# 软件包：核心 + addon_packages
./builder build packages --os ubuntu --os-version 22.04 --kubernetes-version v1.27.3 --dry-run
# 镜像：核心 + addon_images
./builder build images --kubernetes-version v1.27.3 --dry-run
# 只打包附加软件包（无核心；--kubernetes-version 可省略）
./builder build packages --os ubuntu --os-version 22.04 --only-addons --dry-run
# 只打包附加镜像（无核心）
./builder build images --only-addons --dry-run
# 跳过附加：无 addon_packages / addon_images，仅核心
./builder build packages --os ubuntu --os-version 22.04 --kubernetes-version v1.27.3 --skip-addons --dry-run
./builder build images --kubernetes-version v1.27.3 --skip-addons --dry-run

产物目录结构

pixiu-packages-{os}-{osver}-{arch}-{k8sver}/ # build packages
pixiu-images-{arch}-{k8sver}/ # build images（不绑定 OS）
├── packages/ # 仅 packages 产物含此目录
│ ├── *.deb / *.rpm
│ └── runtime/
├── images/ # 仅 images 产物含此目录
│ ├── core/
│ └── addons/
├── install/
│ ├── install.sh
│ └── load-images.sh
└── manifest.yaml

构建完成后会在 --out 目录生成同名 .tar.gz：

pixiu-packages-{os}-{osver}-{arch}-{k8sver}.tar.gz
pixiu-images-{arch}-{k8sver}.tar.gz

配置文件

单份 yaml 默认位于 /etc/pixiu/builder.yaml（生产部署，与 pixiu 配置惯例一致），可通过 --configFile 或环境变量 BUILDER_CONFIG_FILE 指定配置文件。本地开发使用仓库根目录下的 builder.yaml：--configFile ./builder.yaml 或 export BUILDER_CONFIG_FILE=./builder.yaml。文件按顶层分为：

节	内容
`build`	build 子命令默认参数（可选；优先级：命令行 > 配置 > 内置默认值）
`oses`	OS 注册表：可用版本、包管理器（apt/dnf）、容器内下载软件包用的构建镜像、架构、apt 版本代号（codename/codenames）、dnf 发行版标识（rpm_distro）、containerd 包名与来源（containerd_pkg / containerd_repo）
`addon_images`	附加组件镜像清单（name → image:tag；仅镜像，不含软件包；供 `build images`）。镜像条目可用 `tag`（单版本）或 `tags`（同一镜像多版本，构建时展开为多个 tar，文件名 `{name}-{tag}.tar`，serve 可发布多个 tag）
`server_images`	平台服务镜像清单（格式同 `addon_images`；仅 `build servers` 读取；空配置时报错）
`addon_packages`	可选附加安装包（对象格式：name + 可选 version）。必装包（kubeadm/kubelet/kubectl + containerd + cri-tools + 系统依赖）由代码内定、执行即打包，无需配置。version 空不锁版本、非空按目标包管理器语法转译；mode ∈ packages/all 且未跳过附加时并入软件包清单
`github`	可选：产物上传到 GitHub Release（owner/repo/tag/token 等；token 建议用环境变量）

oses.build_images 为初始值，加载器不验证镜像可用性，生产使用请按需核对。 k8s 版本通过 --kubernetes-version / build.kubernetes_version 指定（任意合法 vX.Y.Z）；cri-tools 缺失时 crictl 回退版本与 k8s 对齐（v1.29.5 → 1.29.5）。

build 参数配置化

build 子命令的所有 -- 参数都可在配置文件 build 节预设，按 命令行 > 配置文件 > 内置默认值 的优先级取最终值：

命令行显式传参 → 优先；
未传时回落配置文件 build 节（字符串为空则跳过）;
配置也为空 → 使用 flag 内置默认值。

因此像 --os、--kubernetes-version 这类"必填"参数，命令行或配置 build 节任一提供即可。例外：--only-addons 时 --kubernetes-version 可省略（不构建 k8s 核心，无需 k8s 版本）。配置示例：

build:
os: "ubuntu"os_version: "22.04"kubernetes_version: "v1.31.1"arch: "amd64"# 命令行 --arch 未传时生效mirror: "aliyun"workdir: "./work"out: "./dist"mode: "all"skip_addons: falseonly_addons: false # 只打包附加组件（addon_images / addon_packages），核心软件包与镜像全去；与 skip_addons 互斥dry_run: falsekeep_files: false # 默认 false=构建完成后清理中间文件与中间镜像；true=保留verbose: false # 默认 false=精简输出；true=打印详细过程日志pack_image: ""# 仅 runtime=docker：镜像打包工具镜像；空=内置默认；ARM 宿主须配置 arm64 兼容镜像runtime: containerd # 构建容器运行时：containerd（默认，宿主机 ctr）| dockerkubeadm_dir: "./kube"# kubeadm 二进制缓存目录；文件名 kubeadm-{version}-linux-{arch}

例如配置 arch: "arm64" 后执行 builder build ...（不传 --arch）会构建 arm64 产物；命令行传 --arch amd64 则仍以命令行优先。

上传产物（GitHub Release）

构建完成后可用 --upload 自动上传产物，或用 upload 上传已有 tar.gz。需在 builder.yaml 配置 github 节，或通过 --github-* flag 覆盖。Token 优先顺序：--github-token > 配置 github.token > 环境变量 GITHUB_TOKEN / GH_TOKEN。

github:
owner: acmerepo: buildertag: ""# 可空：build --upload 时默认用 --kubernetes-versiontoken: ""# 建议用环境变量，勿明文提交

export GITHUB_TOKEN=ghp_xxx
# 软件包构建并上传（Release tag 默认 = k8s 版本）
./builder build packages --os ubuntu --os-version 22.04 --kubernetes-version v1.31.6 --upload \
--github-owner acme --github-repo builder
# 镜像构建并上传到名为 images 的 Release（不存在则创建）
./builder build images --kubernetes-version v1.31.6 --arch amd64 --upload \
--github-owner acme --github-repo builder
# 上传已有产物到 Release
./builder upload --file ./dist/a.tar.gz \
--github-owner acme --github-repo builder --github-tag v1.27.3
# 同步 kubeadm 到各 k8s 版本 Release
./builder sync kubeadm --kubernetes-version v1.31.6 --arch amd64 \
--github-owner acme --github-repo builder
./builder sync kubeadm --all --arch amd64 --github-owner acme --github-repo builder
# 交叉编译 builder 二进制并上传到名为 builder 的 Release（默认 amd64+arm64）
./builder sync builder --github-owner acme --github-repo builder
./builder sync builder --arch amd64 --github-owner acme --github-repo builder
# 拉取 rainbow 并交叉编译 pixiuctl 多平台二进制（默认 tag=pixiuctl-{version}）
./builder sync client --github-owner acme --github-repo builder

行为说明：sync kubeadm 创建的 Release 名称即为 k8s 版本号；--github-tag 为空时复用 --kubernetes-version。--all 会查询本仓库 Release 列表与 kubernetes/kubernetes 正式 tag（排除 -rc/-alpha/-beta），确保 >= v1.31.0 的版本均有 Release，并在 kubeadm 资产缺失时下载上传；已存在则跳过。sync builder 默认 Release tag 为 builder（可用 --github-tag 覆盖），产物名为 builder-{arch}，同名 asset 会覆盖上传。sync client 从 rainbow 仓库拉取源码，运行 pixiuctl version 得到版本号，默认 Release tag 为 pixiuctl-{version}（可用 --github-tag 覆盖），产物为 pixiuctl-{version}-{linux,windows,darwin}-{amd64,arm64}。build --upload / upload 在目标 Release 不存在时也会自动创建。Token 需具备 contents: write（经典 PAT 用 repo）权限。

离线源服务（`serve`）

将 builder 产物加载为常驻服务：镜像走本地 registry（短名），软件包走 HTTP yum/dnf/apt 源。不依赖 createrepo / apt-ftparchive。

--bundle / --dir 同时支持 builder 离线包（含 manifest.yaml）与 单镜像 docker save 的 .tar.gz（含 manifest.json，如 docker save img:tag | gzip > img.tar.gz），可混放；--dir 热加载对新放入的单镜像包同样生效。repo/tag 优先取 docker-save 内 RepoTags。

# packages + images + 单镜像 save 混放
./builder serve \
--bundle ./dist/pixiu-packages-centos-8-amd64-v1.27.3.tar.gz \
--bundle ./dist/pixiu-images-centos-8-amd64-v1.27.3.tar.gz \
--bundle ./extra/pause.tar.gz \
--advertise-host 192.168.1.10
# 已解压目录
./builder serve --bundle ./work/pixiu-ubuntu-22.04-amd64-v1.27.3
# 指定离线包目录：目录不存在则自动创建；加载其中所有 *.tar.gz，并每 3s 轮询热加载新放入的包
./builder serve --dir ./offline-packages --advertise-host 192.168.1.10

加载完成后会打印镜像配置 demo与自定义安装包配置 demo（含节点侧 registry/软件源用法，以及 builder.yaml 的 addon_images / addon_packages 示例）。

--advertise-host 默认取本机非 loopback IP（打印给客户端），无需显式指定；仅在需要对外暴露固定地址时手动覆盖。

--namespace（-n，默认 pixiu）控制 serve 自动导入 bundle 镜像的 registry 发布命名空间：镜像发布到 <host>:5000/<namespace>/<repo>:<tag>（如 172.16.2.247:5000/pixiu/pause:3.10）。用户直接 push 到 serve registry 的镜像保持原仓库不变；软件源 /deb/rpm 不受影响。

# 指定发布命名空间 kubez
./builder serve --bundle ./dist/pixiu-images-*.tar.gz --namespace kubez

默认端口：

registry：0.0.0.0:5000 → docker pull <host>:5000/pixiu/kube-apiserver:v1.27.3
软件源：0.0.0.0:8080 → http://<host>:8080/rpm（dnf）或 /deb（apt）

端口可用 --registry-port / --repo-port 单独覆盖（地址段保持 0.0.0.0 不变）：

./builder serve --bundle ./x.tar.gz --registry-port 8088 --repo-port 8089

客户端示例：

# 镜像（需将 host:5000 加入 Docker insecure-registries）
docker pull 192.168.1.10:5000/pixiu/kube-apiserver:v1.27.3
kubeadm init --image-repository 192.168.1.10:5000/pixiu ...
# 查询 serve registry 镜像列表（类似 docker images；默认最多 50 条）
./builder images --registry-addr 192.168.1.10:5000
./builder images --limit 100
# 查询 serve 软件源安装包列表
./builder packages --repo-addr 192.168.1.10:8080
./builder packages --type deb --limit 100
# 列出某仓库的 tag
./builder ls pixiu/pause --registry-addr 192.168.1.10:5000
# dnf / yum
dnf install --repofrompath=pixiu,http://192.168.1.10:8080/rpm kubeadm
# aptecho'deb [trusted=yes] http://192.168.1.10:8080/deb ./'> /etc/apt/sources.list.d/pixiu.list
apt-get update && apt-get install kubeadm

软件源与包下载

源配置（容器内执行）

组件	apt	dnf（yum 复用同一列）
k8s	阿里云 `mirrors.aliyun.com/kubernetes-new/core/stable/{minor}/deb/`；GPG 密钥固定取自阿里云 `v1.31` 的 `Release.key`（规避旧版密钥过期与官方源访问不稳定）	阿里云 `mirrors.aliyun.com/kubernetes-new/core/stable/{minor}/rpm/`；`gpgkey` 固定取自阿里云 `v1.31` 的 `repomd.xml.key`
containerd	`deb [signed-by=/etc/apt/keyrings/containerd-apt-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/{ubuntu\|debian} {codename} stable`（默认 aliyun；ustc→`mirrors.ustc.edu.cn/docker-ce`，docker→`download.docker.com`）	`[docker-ce-stable]`，baseurl `https://mirrors.aliyun.com/docker-ce/linux/centos/{9\|7}/$basearch/stable`，gpgkey `https://mirrors.aliyun.com/docker-ce/linux/centos/gpg`（官方 docker 段为 `rhel`；openEuler（`containerd_repo: none`）不配置该源，containerd 由系统源提供）

k8s 大版本（如 v1.27）由 k8s 版本自动推导；签名密钥统一使用较新仓库（v1.31）的已续期密钥，避免 EXPKEYSIG 234654DA9A296436。codename / rpm_distro 在 builder.yaml 的 oses 节配置或按约定推导。
k8s 三件套按 patch 精确锁定：非 --only-addons 构建且指定 --kubernetes-version 时，kubeadm/kubelet/kubectl 严格锁定到对应 patch（apt：name=X.Y.Z-1.1；dnf/yum：name-X.Y.Z，与 kubez-ansible 一致）。kubernetes-new rpm 为多架构扁平仓库，仅 --forcearch 不够（不过滤候选包）；dnf 下载脚本先用 repoquery --arch=x86_64|aarch64 解析成唯一 NEVRA（name-ver-rel.arch）再下载；不要写成 name-X.Y.Z.x86_64（非法 NEVRA）。源内无该 patch 时 apt/dnf 依赖解析失败即构建失败，不会静默回退同 minor 最新 patch。
containerd 源默认阿里云镜像（containerd_repo=aliyun，mirrors.aliyun.com/docker-ce），可选 ustc 中科大 / docker 官方；apt 的 gpg key 路径为 {os}/gpg，dnf 的 gpg key 路径固定为 centos/gpg（官方为 rhel/gpg，不带版本号）。国内镜像（aliyun/ustc）已实测可达：apt（ubuntu noble/jammy、debian bookworm）与 centos/9 repomd.xml、centos gpg key 均 HTTP 200。
CentOS 7 使用 yum：--os centos --os-version 7 时自动选择 yum 下载（dnf 是 CentOS 8+/Fedora 才有）；yum 的源配置与 dnf 相同（/etc/yum.repos.d/ + rpm --import），下载依赖 downloadonly 插件，失败自动回退 yumdownloader。CentOS 8/9 等仍走 dnf。
CentOS 7 默认源已自动切换 vault：CentOS 7 已于 2024-06 停止维护（EOL），官方 mirrorlist.centos.org 域名 DNS 已不可解析，容器内 yum makecache 必然失败。yum 分支脚本开头会检测 /etc/centos-release 的 release 7.，命中时移走默认 CentOS-Base.repo（其 base/extras/updates 块只配 mirrorlist 无 baseurl，保留会造成 repo 重复且无有效源）并写入 centos-vault.repo，将 base/extras/updates 指向 vault.centos.org 归档源（7.9.2009），保证 yum makecache / install 能拉取系统依赖包（vim/conntrack 等）。非 CentOS 7 不受影响。
--only-addons 不配置 k8s/containerd 源：只打包附加软件包（addon_packages，全部来自系统源）时，容器内仅配置系统源，不再写入 Kubernetes apt/dnf 源 / docker-ce 源，避免失效源（如 CentOS 7 的官方 download.docker.com rhel/7 已 404）导致 yum makecache 失败。CentOS 7 的 vault 系统源修复始终生效（非 only-addons 同样保留）。
containerd 按系统配置：默认阿里云镜像（containerd.io 包，containerd_repo 默认 aliyun，可配置 ustc=中科大 / docker=官方）；openEuler 等 containerd_repo: none 的发行版不配置 docker-ce 源，containerd 改由系统源（everything 仓库，含 containerd-1.2.0-315.oe2203sp3）安装，软件包名为 containerd（containerd_pkg）。因 docker 官方已停止发布 RHEL7 仓库，官方 download.docker.com/linux/rhel/7/ 为 404（CentOS 7 走 yum 时同样受该 rhel/7 源限制；--only-addons 与 openEuler 系统源场景不配置该源，不受影响）。

包下载（容器内一次完成）

在目标系统容器内（docker run --rm --name builder-packages-<id> -v {packages目录}:/out {build_image} sh -c script）：

配置源 + 导入 GPG key；
apt-get update / dnf makecache / yum makecache；
递归下载：apt apt-get install -y --download-only --no-install-recommends <pkgs> -o Dir::Cache::archives=/out；dnf dnf install -y --downloadonly --downloaddir=/out <pkgs>（插件缺失回退 dnf download --resolve --destdir=/out）；yum yum install -y --downloadonly --downloaddir=/out <pkgs>（downloadonly 插件安装失败回退 yumdownloader --resolve --destdir=/out）；
依赖闭包验证：apt-get install --dry-run <pkgs> / dnf install --assumeno <pkgs>；yum 无 --assumeno，--downloadonly 下载成功即表示依赖可解析。

cri-tools 例外：Kubernetes 源 / docker-ce 源内通常不存在 cri-tools 包，此时容器脚本会写 cri-tools-missing 标记，builder 回退从 GitHub release 下载 crictl 静态 tar 并放入 packages/runtime/（install.sh 检测到该 tar 时以 install -m 0755 安装）。

镜像源（mirror）

包模式下 k8s 组件与运行时均走包源（不经 --mirror 调整），因此 --mirror（或配置文件 build.mirror）仅作用于镜像阶段的镜像仓库（kubeadm config images list --image-repository）。核心镜像清单、拉取/保存的镜像引用及 manifest 中的 source_image 均带该镜像仓库地址：

aliyun（默认）：镜像仓库 registry.aliyuncs.com/google_containers。
official：镜像仓库 registry.k8s.io。
tencent：镜像仓库 mirror.cc.tencentyun.com/kubernetes。

仓库地址需保证可访问且存在对应版本的 k8s 镜像；软件包源不受 --mirror 影响（k8s 组件源与 containerd 源由各自配置决定，见上文"软件源与包下载"）。

kubeadm 二进制获取（生成核心镜像清单用）：build images 会先检查 --kubeadm-dir（默认 ./kube）下是否存在 kubeadm-{k8s版本}-linux-{架构}。若存在则直接复用；若不存在，再从 GitHub Release 下载同名 asset。查找顺序：显式 --github-tag → 仅该 Release；未指定时优先 k8s 版本 Release（与 sync kubeadm 上传位置一致，如 v1.37.0），再回退默认 images。例如 --kubernetes-version v1.37.0 --arch arm64 会先找 owner/repo@v1.37.0/kubeadm-v1.37.0-linux-arm64。

安装（目标机使用）

将离线包传到目标机后：

cd pixiu-ubuntu-22.04-amd64-v1.27.3
sudo bash install/install.sh

install.sh 会：

解析 /etc/os-release 检测包管理器；
preflight：swapoff -a 并注释 /etc/fstab swap 行；加载内核模块（overlay/br_netfilter/ip_vs 系列/nf_conntrack）；写入 sysctl 并 sysctl --system；
安装 packages/ 下所有包（apt：dpkg -i *.deb 失败自动 apt-get -f install -y；rpm：rpm -ivh --nodeps *.rpm）；
配置 containerd SystemdCgroup=true，systemctl enable --now containerd kubelet；若存在 crictl 静态回退 tar 则安装 crictl；
调用 load-images.sh 导入镜像（优先 docker load，失败回退 ctr -n k8s.io images import）；
kubeadm version 自检并输出 kubeadm init 示例命令。

开发

go build ./... # 编译
go vet ./... # 静态检查
go test ./... # 单元测试

已知限制

镜像阶段按本机架构拉取（容器内 docker pull，经挂载的 docker.sock 操作宿主机 daemon）；若 --arch 与本机不同会打印 warning，无法交叉拉取。
依赖本机 docker；docker 不可用时 build 直接失败中断，不产出离线包；可用 build packages 显式跳过镜像阶段。
附加组件镜像 flannel 已切换到华为云 SWR pixiu-public 仓库（swr.cn-north-4.myhuaweicloud.com/pixiu-public/flannel/flannel:v0.24.2）；metrics-server 等镜像使用当前 builder.yaml 中配置的 pixiucloud 仓库。网络不支持外部仓库时可用 --skip-addons 跳过附加组件（addon_images 与 addon_packages 均不进产物，核心镜像 + 核心软件包仍完整），未显式跳过时附加组件拉取失败仍中断。
核心镜像清单通过官方 kubeadm 静态二进制生成（kubeadm config images list，Linux 宿主机直跑；其它平台挂载进构建容器）。
镜像打包在 --pack-image 指定的工具容器内执行（默认 swr.cn-north-4.myhuaweicloud.com/pixiu-public/pixiukit/docker:24-cli，含 docker CLI，docker pull + save；容器名 --name builder-images-<id>，挂载 /var/run/docker.sock 与输出目录）。默认 pack 镜像仅 amd64，ARM/aarch64 宿主须用 --pack-image 指定 arm64 兼容镜像，否则 exec format error；软件包下载容器名为 builder-packages-<id>，便于 docker ps 区分阶段。
容器内真实执行依赖 docker，本机无 docker 时仅 dry-run 演练 + 单测；apt 系 k8s 源使用阿里云 mirrors.aliyun.com/kubernetes-new，containerd 源默认阿里云镜像（mirrors.aliyun.com/docker-ce）已用 curl 实测可达，openEuler 系统源（everything 仓库）的 containerd 包已确认 repomd 200 可达。
CentOS 7（yum）依赖 downloadonly 插件与 yumdownloader；CentOS 7 已 EOL，默认源已由脚本自动切换 vault.centos.org（见上文软件源说明），且官方 docker 源对应 rhel/7 在 download.docker.com 为 404（默认阿里云镜像路径段为 centos/7），非 only-addons 场景的 containerd 包下载存在兼容性风险（系统依赖包经 vault 可正常下载，containerd.io 需 docker-ce 源提供）；--only-addons 不配置 k8s/containerd 源，不受该 rhel/7 源限制。
openEuler 已通过 containerd_pkg: containerd + containerd_repo: none 从系统源安装 containerd，规避官方 download.docker.com 无 rhel/7 仓库导致的 dnf makecache 失败；即使配置未显式声明这两个字段，也会按发行版自动推断为系统源（containerd + none），旧配置兼容；其他 dnf 系（rocky 等）默认走阿里云镜像 containerd.io 包。
aliyun / tencent 镜像仓库已支持，仓库地址可用性需按网络环境验证（见上文"镜像源（mirror）"）。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
cmd/builder		cmd/builder
docs/superpowers/specs		docs/superpowers/specs
hack		hack
internal		internal
.gitignore		.gitignore
README.md		README.md
build-bin.sh		build-bin.sh
builder-arm64.yaml		builder-arm64.yaml
builder.yaml		builder.yaml
go.mod		go.mod
go.sum		go.sum

Navigation Menu

Uh oh!

Repository files navigation

builder

快速开始

命令一览

构建子命令

自定义附加组件（addon_packages / addon_images）

附加组件配置与构建子命令联动

产物目录结构

配置文件

build 参数配置化

上传产物（GitHub Release）

离线源服务（`serve`）

软件源与包下载

源配置（容器内执行）

包下载（容器内一次完成）

镜像源（mirror）

安装（目标机使用）

开发

已知限制

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

builder

快速开始

命令一览

构建子命令

自定义附加组件（addon_packages / addon_images）

附加组件配置与构建子命令联动

产物目录结构

配置文件

build 参数配置化

上传产物（GitHub Release）

离线源服务（serve）

软件源与包下载

源配置（容器内执行）

包下载（容器内一次完成）

镜像源（mirror）

安装（目标机使用）

开发

已知限制

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

离线源服务（`serve`）