> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/di-19-zhang-freebsd-xi-tong-geng-xin/di-19.5-jie-shi-yong-pkgbase-kua-ban-ben-sheng-ji.md).

# 19.5 使用 PkgBase 跨版本升级

PkgBase 把基本系统拆分为 `FreeBSD-*` 系列包，内核与用户态因此和第三方软件一样由 pkg 管理。本节介绍如何把已转换为 PkgBase 的系统升级到另一个发行版本：次版本（如 15.1 → 15.2）与大版本（如 15.x → 16.0）。

本节只讨论在运行中的系统上直接升级。尚未转换为 PkgBase 的读者请先阅读 19.3 节；希望保留旧系统以便随时回退的读者，应结合 19.4 节的 ZFS 启动环境操作。

## 三类更新与仓库地址

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}`：

```ini
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}`，升级并重启后变量自然解析为新版本。

## 升级前的准备

* 确认系统处于 PkgBase 模式：

```sh
# 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
```

* 记录当前版本与内核版本号：

```sh
# 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）：

```sh
# bectl create pre-upgrade-20261019  # 创建启动环境，名称建议带日期
```

> **技巧**
>
> 启动环境的名称建议带上日期。`bectl create` 在名称已存在时会失败，而沿用旧名称会让后面的回退命令激活更早的系统，而不是紧邻本次升级之前的状态。

> **警告**
>
> PkgBase 升级**不会**自动创建启动环境。根文件系统为 UFS 时没有启动环境可用，必须事先完整备份。

* 检查 Base 仓库配置。默认文件为 **/usr/local/etc/pkg/repos/FreeBSD-base.conf**，其中的 `url` 应保留 `${VERSION_MINOR}`，不要写死具体版本号。

## 次版本升级（例：15.1 → 15.2）

次版本升级不改变 ABI，只需把 Base 仓库指向新的 minor：

```sh
# 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`。升级结束检查版本：

```sh
# freebsd-version -kru  # 第二列仍是旧版本，重启后才会切换
15.2-RELEASE
15.1-RELEASE-p5
15.2-RELEASE
```

第二列（运行中的内核）仍显示旧版本是正常的：新内核已写入磁盘，但当前运行的仍是旧内核。随后重启：

```sh
# shutdown -r now
```

重启后再次执行 `freebsd-version -kru`，三列应当一致。

## 大版本升级（例：15.x → 16.0）

大版本升级改变了 ABI，同时会替换 pkg 自身。升级必须用 `pkg-static`，否则运行中的 pkg 被覆盖后可能中断：

```sh
# 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 本身再继续：

```sh
# pkg bootstrap -f  # 刷新 pkg 可执行文件
```

* 使用 UEFI 引导的系统，要在**重启之前**把新的引导器复制到 EFI 系统分区。旧引导器可能无法引导升级后的系统，一旦重启失败，复制命令也就无法执行。具体路径取决于初始安装时的布局，常见的是 `efi/BOOT/bootx64.efi`，部分安装还会写入 `efi/freebsd/loader.efi`：

```sh
# cp /boot/loader.efi /boot/efi/efi/BOOT/bootx64.efi  # 更新默认引导器
# cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi  # 若存在该目录
```

* 然后重启：

```sh
# shutdown -r now
```

* 重启后把第三方软件包切换到新的 ABI：

```sh
# pkg upgrade  # 重建或升级所有第三方软件包
```

> **技巧**
>
> kmod 仓库的地址同样带有 `${VERSION_MINOR}`，例如 `kmods_latest_${VERSION_MINOR}`。应先完成基本系统升级并重启，再升级第三方软件包，这样驱动包才会与新内核匹配。

## 验证与回退

升级完成后依次确认：

```sh
# 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",
```

需要回退时，激活升级前创建的启动环境并重启：

```sh
# bectl list  # 列出所有启动环境
# bectl activate pre-upgrade-20261019  # 激活升级前的启动环境
# shutdown -r now
```

> **注意**
>
> 回退会丢弃升级期间对当前启动环境所做的全部改动，请先备份升级后需要保留的数据。

## 参考文献

* 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 仓库配置文件的变量与字段说明。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://book.bsdcn.org/di-19-zhang-freebsd-xi-tong-geng-xin/di-19.5-jie-shi-yong-pkgbase-kua-ban-ben-sheng-ji.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
