19.5 使用 PkgBase 跨版本升级
PkgBase 把基本系统拆分为 FreeBSD-* 系列包,内核与用户态因此和第三方软件一样由 pkg 管理。本节介绍如何把已转换为 PkgBase 的系统升级到另一个发行版本:次版本(如 15.1 → 15.2)与大版本(如 15.x → 16.0)。
本节只讨论在运行中的系统上直接升级。尚未转换为 PkgBase 的读者请先阅读 19.3 节;希望保留旧系统以便随时回退的读者,应结合 19.4 节的 ZFS 启动环境操作。
19.5.1 三类更新与仓库地址
FreeBSD 的版本号形如 15.1-RELEASE-p4,三类更新的含义并不相同:
- 补丁级:
p4→p5,同一发行版本内的安全与缺陷修复,仓库地址不变。 - 次版本:
15.1→15.2,同一主版本下的新发行版本,ABI 不变,Base 仓库的 minor 号改变。 - 大版本:
15.x→16.0,主版本号改变,ABI 由FreeBSD:15:amd64变为FreeBSD:16:amd64,基本系统包整体替换。
Base 仓库的地址带有 ${VERSION_MINOR}:
FreeBSD-base: {
url: "pkg+https://pkg.FreeBSD.org/${ABI}/base_release_${VERSION_MINOR}",
mirror_type: "srv",
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkgbase-${VERSION_MAJOR}",
enabled: yes
}pkg 用当前运行系统的版本替换这个变量,所以在 15.1 上它始终指向 base_release_1,不会自行跳到下一个版本。这正是次版本升级需要显式指定 minor 号的原因。
技巧
可以用
pkg -o VERSION_MINOR=2 -vv预览替换后的仓库地址。该选项只影响本次命令,不修改配置文件;配置文件保留${VERSION_MINOR},升级并重启后变量自然解析为新版本。
19.5.2 升级前的准备
- 确认系统处于 PkgBase 模式:
# pkg info 'FreeBSD-*' | head -5 # 列出基本系统包
FreeBSD-acct-15.1p4
FreeBSD-acpi-15.1
FreeBSD-apm-15.1
FreeBSD-at-15.1
FreeBSD-atf-15.1- 记录当前版本与内核版本号:
# freebsd-version -kru # 依次为已安装内核、运行中的内核与用户态的版本
15.1-RELEASE-p5
15.1-RELEASE-p5
15.1-RELEASE-p5
# sysctl kern.osreldate # 15.1 对应 1501000
kern.osreldate: 1501000- 创建可回退的启动环境(ZFS):
# bectl create pre-upgrade-20261019 # 创建启动环境,名称建议带日期技巧
启动环境的名称建议带上日期。
bectl create在名称已存在时会失败,而沿用旧名称会让后面的回退命令激活更早的系统,而不是紧邻本次升级之前的状态。
警告
PkgBase 升级不会自动创建启动环境。根文件系统为 UFS 时没有启动环境可用,必须事先完整备份。
- 检查 Base 仓库配置。默认文件为 /usr/local/etc/pkg/repos/FreeBSD-base.conf,其中的
url应保留${VERSION_MINOR},不要写死具体版本号。
19.5.3 次版本升级(例:15.1 → 15.2)
次版本升级不改变 ABI,只需把 Base 仓库指向新的 minor:
# pkg -o VERSION_MINOR=2 update -r FreeBSD-base # 刷新 15.2 的 Base 仓库
# pkg -o VERSION_MINOR=2 upgrade -r FreeBSD-base # 升级基本系统注意
目标基本系统包的 OSVERSION 高于当前运行的系统,pkg 会打印
Newer FreeBSD version for package并询问是否忽略版本不匹配,默认选项为N。此时输入y继续;也可以在升级前执行export IGNORE_OSVERSION=yes免去逐条确认。
确认待升级包清单后输入 y。升级结束检查版本:
# freebsd-version -kru # 第二列仍是旧版本,重启后才会切换
15.2-RELEASE
15.1-RELEASE-p5
15.2-RELEASE第二列(运行中的内核)仍显示旧版本是正常的:新内核已写入磁盘,但当前运行的仍是旧内核。随后重启:
# shutdown -r now重启后再次执行 freebsd-version -kru,三列应当一致。
19.5.4 大版本升级(例:15.x → 16.0)
大版本升级改变了 ABI,同时会替换 pkg 自身。升级必须用 pkg-static,否则运行中的 pkg 被覆盖后可能中断:
# ABI="FreeBSD:16:$(pkg config abi | cut -d: -f3)" # 沿用本机架构构造 16.0 的 ABI
# export ABI
# pkg-static update -r FreeBSD-base # 以 16.0 的 ABI 刷新仓库
# pkg-static upgrade -r FreeBSD-base # 升级基本系统注意
ABI 的第三段是架构名,必须与主机一致:amd64 为
amd64,arm64 为aarch64。上面的写法直接沿用pkg config abi的架构段;若手写FreeBSD:16:amd64,在 arm64 机器上会取到错误架构的包。
技巧
覆盖 ABI 后 pkg 会据此推断 OSVERSION(
FreeBSD:16:amd64推断为1600000),所以${VERSION_MINOR}与${VERSION_MAJOR}也随之指向新版本(base_release_0、pkgbase-16),无需另行指定。
警告
大版本升级可能移除不属于基本系统的软件包,其中可能包括正在使用的桌面环境。请先切换到控制台,或准备好重新安装这些包。
注意
新主版本通常使用新的软件包签名密钥(如 /usr/share/keys/pkgbase-16)。若提示找不到密钥,需先安装新版本提供的 pkg 引导包:
sh# pkg add -f https://pkg.freebsd.org/FreeBSD:16:$(uname -p)/base_release_0/FreeBSD-pkg-bootstrap-16.0.pkg
注意
基本系统包的 OSVERSION 通常高于推断出的
1600000,pkg 会打印Newer FreeBSD version for package并询问是否忽略版本不匹配,默认选项为N。输入y继续,或预先执行export IGNORE_OSVERSION=yes。
若 pkg 提示 Major OS version upgrade detected,按提示先刷新 pkg 本身再继续:
# pkg bootstrap -f # 刷新 pkg 可执行文件- 使用 UEFI 引导的系统,要在重启之前把新的引导器复制到 EFI 系统分区。旧引导器可能无法引导升级后的系统,一旦重启失败,复制命令也就无法执行。具体路径取决于初始安装时的布局,常见的是
efi/BOOT/bootx64.efi,部分安装还会写入efi/freebsd/loader.efi:
# cp /boot/loader.efi /boot/efi/efi/BOOT/bootx64.efi # 更新默认引导器
# cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi # 若存在该目录- 然后重启:
# shutdown -r now- 重启后把第三方软件包切换到新的 ABI:
# pkg upgrade # 重建或升级所有第三方软件包技巧
kmod 仓库的地址同样带有
${VERSION_MINOR},例如kmods_latest_${VERSION_MINOR}。应先完成基本系统升级并重启,再升级第三方软件包,这样驱动包才会与新内核匹配。
19.5.5 验证与回退
升级完成后依次确认:
# uname -r # 运行中的内核版本
16.0-RELEASE
# freebsd-version -kru # 三列应一致
16.0-RELEASE
16.0-RELEASE
16.0-RELEASE
# pkg -vv | grep -E '^ABI =|base_release' # 确认 ABI 与仓库地址已指向新版本
ABI = "FreeBSD:16:amd64";
url : "pkg+https://pkg.FreeBSD.org/FreeBSD:16:amd64/base_release_0",需要回退时,激活升级前创建的启动环境并重启:
# bectl list # 列出所有启动环境
# bectl activate pre-upgrade-20261019 # 激活升级前的启动环境
# shutdown -r now注意
回退会丢弃升级期间对当前启动环境所做的全部改动,请先备份升级后需要保留的数据。
19.5.6 参考文献
- FreeBSD Project. Updating and Upgrading FreeBSD[EB/OL]. [2026-10-19]. https://docs.freebsd.org/en/books/handbook/cutting-edge/. 官方手册,含 PkgBase 的补丁、次版本与大版本升级步骤。
- FreeBSD Project. pkgbase[EB/OL]. [2026-10-19]. https://wiki.freebsd.org/pkgbase. PkgBase 项目的 Wiki,说明仓库分支、转换工具与升级方式。
- FreeBSD Project. pkg-repository(5)[EB/OL]. [2026-10-19]. https://man.freebsd.org/cgi/man.cgi?query=pkg-repository&sektion=5. pkg 仓库配置文件的变量与字段说明。