> 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/openbsd/system-administration/upgrade.md).

# 更新与升级

## 概要

维护 OpenBSD 系统涉及若干不同任务：为基本系统应用二进制补丁、更新已安装的软件包、升级到新版本，以及（可选）跟踪开发分支（`-current`）。OpenBSD 为每项操作都提供了可靠且定义明确的工具。

本章介绍以下流程：

* 使用 `syspatch(8)` 为基本系统应用安全与稳定性补丁
* 使用 `pkg_add -u` 升级已安装的软件包
* 使用 `fw_update(8)` 应用固件更新
* 使用 `sysupgrade(8)` 执行就地系统升级
* 切换到 `-current` 开发分支并保持维护

每种工具对应系统的不同层面。二进制补丁（`syspatch`）仅覆盖基本系统，不影响已安装的软件包；软件包升级也不会修改内核或核心系统库。完整系统升级由 `sysupgrade` 单独处理。

跟踪 `-current` 的系统通过手动构建或频繁重装来更新，面向开发者与有经验的用户。

下面分节给出每种更新与升级方式的详细流程与示例。

## 使用 `syspatch` 为基本系统打补丁

OpenBSD 基本系统以一组文件的形式发布，这些文件由经审计的源代码编译而成。对于已发布版本（如 7.8），安全与稳定性修复以二进制补丁形式发布，通过 `syspatch(8)` 工具应用。

补丁机制仅作用于**基本系统**，不影响用户安装的软件包。补丁针对受支持的版本发布，直接从 OpenBSD 镜像站下载。

### 应用补丁

获取并为当前版本应用所有可用的二进制补丁：

```sh
# syspatch
```

该命令会：

* 从官方镜像下载缺失的补丁
* 按正确顺序应用
* 将变更记录到 `/var/syspatch/`

`syspatch` 可随时运行；已应用的补丁会自动跳过。

### 检查可用补丁

要**仅检查是否有可用补丁而不应用**，使用 `-c`（check）选项：

```sh
# syspatch -c
```

该命令列出尚未应用的补丁（若有），并在需要补丁时以非零状态退出，适用于脚本化或自动化维护任务。

### 查看已安装补丁

列出当前已应用的所有补丁：

```sh
# syspatch -l
```

每条记录对应一个匹配官方勘误的二进制补丁。补丁文件存放于 `/var/syspatch/`。

### 移除补丁

移除先前应用的补丁（一般不推荐）：

```sh
# syspatch -r patch_name
```

仅在受到建议时使用，例如排查问题时。移除补丁可能使系统处于不受支持或存在漏洞的状态。

### 应用补丁后重启

若补丁修改了内核或其他早期引导组件，`syspatch` 会显示：

```
Relinking to create unique kernel... done; reboot to load the new kernel
```

该提示表示需重启才能使补丁生效。其他补丁（如用户态二进制或守护进程）可能无需重启。

若不确定，`syspatch` 执行后重启总是安全的：

```sh
# reboot
```

### 可用性与支持范围

`syspatch` 仅支持 OpenBSD 的发行版本。不适用于运行 `-current` 或 `-stable` 的系统，这些系统须通过手动构建或完整系统升级来更新。

## 使用 `pkg_add -u` 升级已安装软件包

OpenBSD 软件包系统独立于基本系统更新。每个受支持版本的软件包持续更新，通过 OpenBSD 镜像网络分发。

要将所有已安装软件包升级到最新版本，使用带 `-u` 选项的 `pkg_add(1)`。该过程不会影响 `baseXX.tgz` 等发行集安装的基本系统文件。

### 升级所有软件包

升级当前已安装的全部软件包：

```sh
# pkg_add -u
```

该命令会：

* 将已安装软件包版本与镜像上的最新版本进行比对
* 下载并安装更新后的软件包
* 自动移除或替换过时的依赖

需具备可用的网络连接与有效的软件包路径。

### 确认软件包路径

若未设置 `PKG_PATH` 环境变量，`pkg_add` 会查阅 `/etc/pkg.conf`。验证：

```sh
# grep '^installpath' /etc/pkg.conf
```

手动设置路径：

```sh
# export PKG_PATH=https://cdn.openbsd.org/pub/OpenBSD/$(uname -r)/packages/$(arch -s)/
```

适用于非默认配置或脚本环境。

### 交互式提示

若某软件包存在多个可用版本，`pkg_add` 可能提示选择：

```
ambiguous: choose package for ImageMagick
 a 0: <ImageMagick-6.9.12p4>
 a 1: <ImageMagick-7.0.10p0>
Your choice:
```

选择相应版本，或按回车接受默认值。

### 需重启的软件包

升级提供服务的软件包或守护进程后，可能需要重启：

```sh
# rcctl restart unbound
```

可查看 `/var/db/pkg` 或系统日志，了解哪些服务被升级。

### 校验软件包状态

校验已安装软件包集合的一致性：

```sh
# pkg_check
```

该命令检查依赖、共享库链接及记录的安装状态，不会修改系统。

在生产系统上运行 `pkg_add -u` 升级软件包是安全的，除非替换了关键库或组件，否则无需重启。基本系统须另行通过 `syspatch(8)` 或 `sysupgrade(8)` 更新。

## 使用 `fw_update` 更新固件

部分设备需要专有固件文件才能正常工作。由于授权限制，这些文件不包含在 OpenBSD 安装集中，但可在系统安装后通过 `fw_update(8)` 安装。

无线网卡、USB 设备及其他含嵌入式微控制器的硬件通常需要固件。

### 安装固件

为当前运行的系统安装所有必需的固件文件：

```sh
# fw_update
```

该命令会：

* 判定需要哪些固件文件
* 从 OpenBSD 固件镜像获取
* 安装到 `/etc/firmware/`
* 更新 `/var/db/fw_update.status` 以跟踪已安装文件

固件安装需要可用的网络连接。

### 升级后更新固件

系统升级（通过 `sysupgrade` 或手动安装）后，固件文件须更新以匹配新内核。此步骤在首次引导时自动完成：若有必需固件缺失或不兼容，系统会调用 `fw_update`。

手动确保所有固件为最新：

```sh
# fw_update
```

该步骤可随时安全重复执行，确保无线网卡、USB 外设等设备在新版本系统下正常工作。

### 校验已安装固件

已安装的固件文件位于：

* `/etc/firmware/` — 存放二进制固件 blob
* `/var/db/fw_update.status` — 跟踪已安装固件及其版本

列出已安装固件：

```sh
# ls /etc/firmware/
```

固件由设备驱动在引导时或设备接入时自动加载。

### 移除未使用的固件

移除不再需要的固件：

```sh
# fw_update -c
```

该命令将已安装固件与当前硬件配置进行比对，并提供删除未使用文件的选项。

移除是可选的，若系统会在多种硬件配置下使用，可跳过此步。

依赖无线网卡（`iwn(4)`、`iwx(4)`、`urtwn(4)` 等）或其他需二进制 blob 才能工作的外设的系统，固件管理至关重要。

## 使用 `sysupgrade` 升级系统

OpenBSD 基本系统每年发布两次。从一个版本升级到下一版本（如从 7.7 升级到 7.8）可使用 `sysupgrade(8)` 工具自动完成。该工具处理安全就地升级到下一正式版本所需的全部步骤。

`sysupgrade` 面向跟踪 OpenBSD **发行分支**的系统，不用于升级 `-current` 系统，也不用于应用基本系统补丁（请使用 `syspatch`）。

### 执行升级

升级到下一个可用版本：

```sh
# sysupgrade
```

该命令依次执行：

1. 从最近的镜像下载新版本的安装集
2. 校验完整性
3. 重启进入临时升级内核
4. 就地安装新安装集
5. 重启进入升级后的系统

此过程无需手动干预，除非使用了自定义磁盘布局或系统配置。完成升级始终需要重启。

### 升级到指定版本

默认情况下，`sysupgrade` 安装最新可用版本。要升级到指定版本：

```sh
# sysupgrade -R 7.8
```

适用于跨多个版本分阶段升级，或与全站发布策略保持一致的场景。

### 升级后的操作

系统引导进入新版本后，会自动触发以下维护任务：

* `fw_update(8)` 运行，安装或更新与新内核匹配的固件
* `syspatch(8)` 应用新版本发布以来的二进制补丁
* `sysmerge(8)` 运行，整合 `/etc` 中的配置文件

`sysmerge` 期间，系统可能提示审查被修改的文件。本地自定义可按需保留或与更新后的默认值合并。

通过 ports 系统安装的第三方软件包**不会**自动升级。要让软件包与新版本保持一致，请运行：

```sh
# pkg_add -u
```

强烈建议在系统升级后升级软件包，以免与共享库或内核接口不匹配。

### 校验升级状态

确认系统正在运行新版本：

```sh
$ uname -a
OpenBSD myhost.example.org 7.8 GENERIC#123 amd64
```

仅获取并校验升级文件、不立即重启：

```sh
# sysupgrade -n
```

这**并非**空运行。`-n` 选项会下载并校验安装集，创建 `/bsd.upgrade`，然后在重启前停止。之后从 `/bsd.upgrade` 引导即可继续升级。该选项仅用于在受控的重启窗口前预先准备升级。

### 清理

下载的安装集默认存放在 `/home/_sysupgrade`。这些文件不会自动删除。释放磁盘空间：

```sh
# rm -rf /home/_sysupgrade
```

此步骤可选，若可能需要回滚或重装，可暂缓执行。

### 建议

升级前务必备份关键数据，尤其是生产系统。`sysupgrade` 虽设计为安全且全自动，但意外的配置或硬件问题可能仍需手动恢复。

## 跟踪开发分支（`-current`）

OpenBSD `-current` 分支代表正在进行的开发，包含新功能、持续的安全增强与架构变更，这些内容将出现在下一正式版本中。运行 `-current` 的用户应频繁更新系统，并准备好排查问题。该环境面向开发者、测试者与技术熟练的用户。

### 安装或升级到 `-current`

切换到 `-current` 需从 OpenBSD 镜像下载并安装最新快照：

```sh
# ftp https://cdn.openbsd.org/pub/OpenBSD/snapshots/amd64/installXX.img
```

将 `XX` 替换为最新可用版本（如 `install78.img`）。将该镜像写入 U 盘或其他可引导介质后，重启系统并执行完整安装。安装程序会识别快照并将系统配置为 `-current`。

快照也以其他格式提供（如可 PXE 引导的内核与安装集），更新频繁，通常每日一次。

### 保持 `-current` 更新

运行 `-current` 的系统**不**使用 `syspatch(8)` 或 `sysupgrade(8)`。

保持 `-current` 系统更新的方式有两种：

* 定期从较新的快照重装
* 或从源代码构建基本系统

推荐做法是定期使用快照重装，以确保基本系统、软件包与配置文件保持同步。

确认当前版本：

```sh
$ sysctl kern.version
OpenBSD 7.8-current (GENERIC.MP) #123: ...
```

将该构建日期与 OpenBSD 镜像上最新快照的时间戳进行比较。

### 在 `-current` 上更新软件包

`-current` 的二进制软件包会频繁重建，以匹配当前内核与库。由于基本系统处于变动中，软件包与库版本必须保持同步。

更新软件包：

```sh
# export PKG_PATH=https://cdn.openbsd.org/pub/OpenBSD/snapshots/packages/$(arch -s)/
# pkg_add -u
```

若软件包暂时不可用或不同步，等待数小时后重试。开发活跃期镜像延迟属正常现象。

### 从源代码构建

高级用户可按官方 `release(8)` 与 `build(7)` 流程从源代码构建基本系统。使用快照时无需如此，但若要测试内核改动、提交补丁或验证未发布功能，则可能需要。

从源代码构建需要干净的环境、最新的源代码树，并留意已发布的系统架构变更。OpenBSD FAQ 与源代码树中对此有详细文档。

运行 `-current` 提供了提交缺陷报告与测试新代码的机会，但需要定期维护并熟悉系统内部机制。


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/openbsd/system-administration/upgrade.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.