企业官网建设流程全解析

• 文档
• 教程

本文以 PiKVM 官方文档 docs/_update_os.md 为核心骨架，系统讲解 PiKVM OS 的在线更新流程：从一条pikvm-update命令出发，覆盖标准更新操作、旧版本 OS 的command not found迁移路径、更新失败时的镜像重刷兜底方案，并结合仓库内其他文档与发布记录说明固件随系统交付、只读文件系统等设计细节。读完本文，你将能安全、正确地完成任意版本 PiKVM OS 的更新，并在异常场景下快速恢复设备。

更新前的准备与风险认知

PiKVM OS 是一套基于 Arch Linux ARM 的嵌入式系统，默认以只读文件系统运行（详见 README.md 与 docs/cheatsheet.md），更新操作本质上是对整机软件栈的一次系统性升级。官方文档在给出命令之前，先明确了两条重要前提：

1. 仅在具备物理访问条件时更新：官方建议只有在能够物理接触到设备（或极端必要）时才执行更新。尽管更新流程本身非常可靠，但任何升级都存在小概率失败的可能，届时需要重新刷写存储卡。
2. PiKVM 不会被"变砖"，但恢复需要物理访问：设备本身不会因更新失败而永久损坏，你随时可以通过重刷 SD 卡镜像恢复；但刷写操作必须物理接触存储卡，因此远程更新时务必评估风险。

这一风险提示贯穿于整个官方文档体系。例如 2024 年底的发布记录同样强调"不要在没有物理访问条件时升级"，而 docs/cheatsheet.md 中的关机指南也特别指出：系统更新期间绝不能执行关机，否则很可能损坏系统——这从侧面印证了更新操作的高风险属性。

标准更新流程：pikvm-update

对于较新的 PiKVM OS 版本，官方提供了一站式更新命令。在root用户下执行：

[root@pikvm ~]# pikvm-update

关于操作前提需要说明两点：

• 必须以 root 身份执行：可以通过su -切换到 root（参见 docs/cheatsheet.md 中的 root 权限说明），SSH 直接登录 root 或 Web 终端均适用；
• 需要可用的软件包仓库连接：pikvm-update通过 Arch Linux 的 pacman 体系拉取并应用更新，因此设备必须能正常访问 PiKVM 的软件源。

从仓库的文档结构看，pikvm-update是 PiKVM 生态中的"万能更新入口"：它被大量功能文档作为前置步骤引用（详见后文"在文档体系中的角色"一节），并被用来交付除 OS 之外的附加组件更新。例如 2025 年 1 月的发布记录 docs/blog/posts/2025/2025-01-12/index.md 明确指出：PiKVM Switch 的固件更新正是通过pikvm-update一并交付的，无需任何额外步骤；2024 年 12 月的记录 docs/blog/posts/2024/2024-12-25/index.md 也仅用一句 "To update just runpikvm-update" 概括了当时的版本更新方式。

处理 "command not found"：旧版本 OS 的升级路径

如果你在执行时遇到如下错误，说明当前系统运行的是较老的 OS 发行版本，系统中尚未内置pikvm-update命令：

[root@pikvm ~]# pikvm-update bash: pikvm-update: command not found

此时不能直接更新，需要先通过 pacman 安装更新器组件。官方给出的完整步骤如下：

[root@pikvm ~]# rw [root@pikvm ~]# pacman -Syy [root@pikvm ~]# pacman -S pikvm-os-updater [root@pikvm ~]# pikvm-update

各条命令的作用如下：

执行完毕后，系统便完成了从"旧版本"到"可在线更新"的迁移。文档特别注明：下次更新时，直接使用常规的pikvm-update即可，无需再重复上述手工安装步骤。

更新后的验证与后续事项

更新完成后，建议做以下确认：

• 再次运行pikvm-update验证：若已是最新版本，命令会正常返回且无错误输出，同时确认pikvm-update命令可用；
• 确认附带固件/功能更新已生效：如 PiKVM Switch 的固件会在pikvm-update后随系统更新一起交付，随后在 Switch 菜单中按提示操作即可（见 docs/blog/posts/2025/2025-01-12/index.md）；
• 留意配置类变更：个别版本升级会伴随配置项调整。例如 2025 年 10 月的发布记录 docs/blog/posts/2025/2025-10-23/index.md 提到!include配置指令已被移除，若配置中仍在使用，pikvm-update会提示你先清理配置再升级；2024 年 2 月的记录 docs/blog/posts/2024/2024-02-15/index.md 则提示自定义 EDID 的用户在更新后需要重新设置 EDID。升级前关注对应版本的发布说明是避免踩坑的关键。

更新失败的兜底方案：重新刷写 OS 镜像

正如文档开头所述，更新过程虽然可靠，但仍有极小概率失败，届时需要重新刷写存储卡。完整的刷写流程记录在 docs/flashing_os.md 中，要点如下：

• 准备合格的存储卡：官方要求最小 32 Gb、建议 Class 10 的 Micro-SD 卡；
• 选择正确的镜像：镜像按「板卡 × 平台 × 视频采集方式」区分，例如 V4 Mini / V4 Plus / V3 HAT、DIY V2（HDMI-CSI 桥或 HDMI-USB 采集棒）、DIY V1 等，请严格匹配你的硬件配置，官方成品设备镜像与 DIY 镜像不通用；
• 刷写并重新配置：将镜像写入 SD 卡后插入设备启动，即可恢复到可用状态。

换句话说，更新失败的恢复路径是"重刷镜像"而非"修复系统"——这也是官方反复强调需要物理访问设备的根本原因。

进阶视角：pikvm-update 在文档体系与固件交付中的角色

docs/_update_os.md在仓库中是一个被广泛复用的 MkDocs include 片段（通过{!_update_os.md!}语法嵌入），这说明"更新 OS"是绝大多数功能配置的前置步骤。它在以下文档中均有出现，可作为实际使用场景的参考：

• 网络与远程访问类：docs/tailscale.md、docs/cloudflared.md、docs/reverse_proxy.md、docs/letsencrypt.md、docs/vnc.md；
• 外设与功能类：docs/usb_pass.md、docs/usb_serial.md、docs/msd.md、docs/audio.md、docs/camera.md、docs/mouse_jiggler.md；
• 硬件平台指南：docs/v1.md、docs/v2.md、docs/v3.md、docs/v4.md；
• 其他：docs/faq.md、docs/latency.md、docs/modem.md、docs/switch.md、docs/cheatsheet.md。

从这些引用关系可以看出，官方给出的"标准动作"就是：先pikvm-update将系统更新到最新，再执行具体功能配置。此外，若你希望脱离官方镜像、从源码自行构建 PiKVM OS（适合深度定制场景），可参考 docs/building_os.md 中基于 Docker 的构建流程——它面向的是构建侧而不是更新侧，可作为理解 PiKVM OS 组成结构的补充材料。

总结与最佳实践

综合 docs/_update_os.md 及仓库内相关材料，PiKVM OS 的更新最佳实践可归纳为：

1. 评估访问条件：只在能物理接触设备时更新；远程环境除非极端必要，否则尽量不做在线升级；
2. 使用标准命令：root下执行pikvm-update；
3. 处理旧版本：若提示pikvm-update: command not found，按rw→pacman -Syy→pacman -S pikvm-os-updater→pikvm-update的顺序完成迁移，此后即可回归标准流程；
4. 关注发布说明：留意版本更新带来的配置兼容性变化（如 EDID、配置指令、固件交付等）；
5. 保留兜底方案：熟悉 docs/flashing_os.md 的镜像重刷流程，确保任何情况下都能恢复设备。

• 文档
• 教程