更新、回滚与重置

这些命令用于照管运行 IronFlockOS 的设备。os update 安装发布版本，os rollback 回到之前运行的发布版本，os reset 让设备重新回到刚写入时的状态。

根槽位与数据分区

IronFlockOS 设备的磁盘包含：

• 两个根槽位 A 和 B — 每个都包含一个完整的 IronFlockOS 系统。一个在运行。另一个包含之前运行的系统，在刚写入的设备上则尚无任何内容。IronFlockOS 所用的更新工具 RAUC 将发布版本写入未运行的槽位，并记录下次启动哪个槽位。
• 数据分区（/data） — 应用及其数据，以及设备代理程序及其设备配置文件（.flock）副本。两个系统都使用它，因此更新或回滚不会改动应用及其数据。
• IRONFLOCKOS 分区（挂载在 /boot/efi） — 一个小型 FAT 分区。设备启动时用在那里找到的 .flock 文件注册，os reset 也将其请求写在那里。

新系统必须证明自己：设备代理程序从新系统连接到 IronFlock 并将其标记为良好之后，设备才会保留它。无法启动或未能做到这一点的系统，会在下一次重启时被弃用，改回之前运行的系统。ironflock status 显示各槽位：

System:        IronFlockOS 0.13.0 (amd64-efi, base)
  Image:       ironflockos-amd64-efi-base (build 20261105T120000Z-g1a2b3c4)
  Slot A:      inactive, good
  Slot B:      booted, good, 0.13.0 installed 2026-11-05T14:00:00Z
  Next boot:   slot B

命令在哪里运行

这三个命令在运行 IronFlockOS 的设备上运行，需要 root，并在执行操作之前询问。在其他系统上（macOS、不是 IronFlockOS 的 Linux、IronFlockOS 安装 U 盘），它们以退出码 3 结束。

• 在设备上 — 0.15.0 之后的 IronFlockOS 发布版本自带 ironflock。登录到设备，用 sudo 运行命令。
• 从另一台电脑 — 0.15.0 及更早的 IronFlockOS 发布版本不带 ironflock。请从一台 Linux 或 macOS 电脑借助 --host，以设备的 SSH 用户身份运行命令：即 .flock 文件为项目所有者设置的账户，在示例中为 operator。--host 会为本次运行将 ironflock 复制到设备上，并在那里通过 sudo 运行命令。

ironflock --host operator@kitchen-pc os update --reboot --yes

给出 --yes 时，os update 和 os rollback 可以同时在多台设备上运行（多次给出 --host，或使用 --hosts）。os reset 一次只在一台设备上运行；在多台设备上运行时，它以退出码 2 结束。全局标志参见标志、输出与退出码。

ironflock os update

将设备通道提供的 IronFlockOS 发布版本安装到未运行的根槽位中。新系统在下一次重启时启动，带 --reboot 时立即启动。

ironflock os update [flags]

设备的通道就是其设备代理程序所跟随的通道，取自代理程序 .flock 文件中的 environment：在 IronFlock 的测试平台上为 test，否则为 production。如果目录中没有设备的通道，则为 production。下载基址依次取自 --download-base、IRONFLOCK_DL_BASE、代理程序 .flock 文件中的更新服务器（update_url）（在 IronFlock Appliance 的设备上，即 Appliance 的下载镜像站，这类设备只能访问它），否则为 IronFlock 云。

它按以下顺序执行：

1. 读取已签名的 IronFlockOS 目录，并选取通道（或 --version）的发布版本中设备镜像的更新包。
2. 说明哪个发布版本在哪个槽位中运行、它要将哪个发布版本安装到哪个槽位、该槽位目前包含什么，以及下载的大小。然后询问。
3. 将更新包下载到数据分区上的 /var/cache/ironflockos 中。被中断的下载会续传。只有当文件的大小和 SHA-256 与目录中的一致时，才会使用该文件。
4. 让 RAUC 将更新包安装到未运行的槽位中。RAUC 检查更新包的签名，写入该槽位，并将其设为下次启动的槽位。该槽位之前的内容会被覆盖。安装完成后，更新包会被删除。
5. 带 --reboot 时，重启设备进入新系统。

正在运行的系统在重启之前保持原样。应用及其数据保持不变。当前运行的槽位保留其发布版本，当新发布版本无法启动或无法连接到 IronFlock 时，设备会回到它。

当设备已经运行该发布版本时，以及该发布版本已安装在另一个槽位中、正在等待重启时，不会安装任何内容，退出码为 0。在第二种情况下，--reboot 会询问并重启设备。

# 安装设备通道的发布版本；它在下一次重启时启动
sudo ironflock os update
# 安装并重启进入新版本，不询问
sudo ironflock os update --reboot --yes
# 安装目录中的一个较旧发布版本
sudo ironflock os update --version 0.13.0

进度输出到 stderr：先是下载及其检查，然后是 RAUC 给出的每个步骤。在槽位 A 中运行 0.13.0 的设备上，os update --yes 的输出如下：

Download base: https://instance-registry.ironflock.com/dl (from default)
IronFlockOS catalog of 2026-11-20T09:00:00Z, signed with key 036ef3bd: production 0.14.0, test 0.14.0.
This device runs IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) from slot A.
IronFlockOS 0.14.0, the release of the production channel, is installed into slot B, which holds nothing yet:
  - the bundle (580.2 MB) is downloaded into /var/cache/ironflockos
  - RAUC checks its signature and writes it into slot B
  - it starts with the next restart
Slot A keeps IronFlockOS 0.13.0: the device goes back to it when 0.14.0 does not start or does not reach IronFlock. Apps and their data stay.
Downloading: 0% (0 B of 580.2 MB)
...
Installing IronFlockOS 0.14.0 into slot B.
Installing:   0% Installing
...
Installing:  82% Copying image to rootfs.1
...
Installing: 100% Installing done.
IronFlockOS 0.14.0, the release of the production channel, is installed in slot B and starts with the next restart ('sudo reboot').

使用 --json 时，安装过程是进度阶段 installing，以百分比表示。os update --reboot --yes --json 的结果：

{"action":"installed","image":"ironflockos-amd64-efi-base","channel":"production","version":"0.14.0","running_version":"0.13.0","slot":"B","up_to_date":false,"reboot":true}

拒绝执行的情况（退出码 3）：

• 它不是以 root 身份运行、在不运行 IronFlockOS 的机器上运行，以及在安装 U 盘上运行。
• RAUC 已经在安装一个更新包，该更新包由 IronFlock Studio 经由代理程序或其他调用启动。RAUC 一次只安装一个。
• 该发布版本没有适用于设备镜像的更新包。
• 该发布版本比正在运行的旧，除非 --version 指定了它。当另一个槽位包含该发布版本时，消息会指出 os rollback。
• /var/cache/ironflockos 没有足够的空间容纳尚待下载的内容。消息会列出该文件夹中之前更新留下的更新包，您可以删除它们。

错误的命令行（退出码 2）：同时给出 --channel 和 --version、格式不是版本号的版本、目录中没有的通道或发布版本。

失败的情况（退出码 1）：目录验证不通过或无法读取；下载中断（已下载的部分保留在 /var/cache/ironflockos 中，同一命令会续传）；下载的文件不是目录中的文件；RAUC 拒绝该更新包或安装失败。错误会给出 RAUC 的原因。如果 RAUC 已经开始写入，该槽位会被标记为损坏，不含可用的系统，设备继续启动正在运行的系统。更新包保留在缓存中，供下一次尝试使用。

在下载期间或下载刚结束时按下 Ctrl-C，命令会在安装或重启任何内容之前以退出码 130 结束；同一命令会续传下载。询问被回答为“否”时，命令以退出码 4 结束。

ironflock os rollback

将另一个根槽位设为启动的槽位，并重启设备进入该槽位：回到上一次更新之前运行的系统。对于能启动但运行异常的系统，请使用它。无法启动或无法连接到 IronFlock 的系统，IronFlockOS 会在下一次重启时自行弃用。

ironflock os rollback [flags]

该命令没有自己的标志。它总是会重启设备：不重启的回滚在下一次重启之前不会改变任何内容。

只有其系统曾在本设备上启动过的槽位才符合条件：

• 其系统在运行期间被标记为良好、此后没有被再次尝试过的槽位。尝试过但从未被标记为良好的槽位不符合条件。
• 设备写入时所用的槽位（A），前提是尚未向其中安装任何内容，且它没有被标记为损坏。

应用及其数据保持不变，因为两个系统使用同一个数据分区。原先运行的槽位保留其发布版本。重启之后，较旧的系统必须再次证明自己：设备代理程序从它连接到 IronFlock 之后，设备才会保留它。在 UEFI 机器上，之前曾做到这一点的槽位，在运行满两分钟后也会被保留。在此之前，重启可能会恢复较新的系统。IronFlock Studio 会再次提供通道的发布版本，os update 会安装它。

# 回到另一个槽位中的系统，先询问
sudo ironflock os rollback
# 不询问
sudo ironflock os rollback --yes

在槽位 B 中运行 0.14.0 的设备上，os rollback --yes 的输出如下：

This device runs IronFlockOS 0.14.0 from slot B.
Slot A holds IronFlockOS 0.13.0, which ran on this device before. The rollback makes slot A the one that starts and restarts the device now.
Slot B keeps IronFlockOS 0.14.0. Apps and their data stay: both systems use the same data partition.
The device keeps IronFlockOS 0.13.0 once it has proven itself again (the device agent reaches IronFlock from it); until then a restart can bring back 0.14.0.
Rolled back to IronFlockOS 0.13.0 in slot A: the device restarts now.

使用 --json 时，slot 和 version 是要启动的槽位及其发布版本（无法读取时为空），from_slot 和 from_version 是原先运行的系统：

{"action":"rolled_back","slot":"A","version":"0.13.0","from_slot":"B","from_version":"0.14.0"}

拒绝执行的情况（退出码 3，并说明原因）：

• 它不是以 root 身份运行、在不运行 IronFlockOS 的机器上运行、在安装 U 盘上运行，以及 RAUC 正在安装更新包时。
• 设备的引导加载程序是命令不认识的：它认识 GRUB（UEFI 机器）和 Raspberry Pi 的引导加载程序。
• 另一个槽位尚无任何内容（刚写入的设备）、包含尝试过但未被标记为良好的系统、由于安装未完成而不含可用的系统，或者已被标记为损坏。
• 另一个槽位正在等待下一次重启，原因是安装了更新，或者回滚之后没有重启。sudo reboot 会启动它，sudo rauc status mark-bad other 会放弃它。

失败的情况（退出码 1）：RAUC 无法将该槽位设为启动的槽位（未做任何更改）；重启失败（此时该槽位会在下一次重启时启动）。询问被回答为“否”时，命令以退出码 4 结束。

ironflock os reset

请求 IronFlockOS 恢复出厂设置，并重启设备。在下一次启动期间，设备会清除其所有者、其应用和注册所留下的内容，并以刚写入的设备的状态启动；带 -c 时，它会作为新 .flock 文件所对应的设备注册。

ironflock os reset [-c <new.flock>] [flags]

IronFlockOS 0.15.0 是第一个支持恢复出厂设置的发布版本。在更早的发布版本上，命令会拒绝执行；os update 可以安装较新的发布版本。

重置会在数据分区和两个根槽位中清除：

• 应用及其数据，以及 Docker 的容器、镜像和卷。
• 设备在 IronFlock 中的身份：设备代理程序及其 .flock 文件副本、其数据库和服务。主机名恢复为 ironflockos，machine ID 会重新生成。
• SSH 用户和所有其他用户账户，连同其主目录和 sudo 规则。
• 日志、SSH 主机密钥、已下载的更新和实时调优设置。
• 不带 --keep-network 时：网络配置文件（包括 WiFi）、代理设置（proxy.conf）和 PTP 设置（ptp.conf）。

它保留根槽位中的 IronFlockOS 系统（正在运行的系统，以及另一个槽位中的系统，如果有的话），以及 RAUC 对它们的记录，因此更新和回滚照常进行。带 --keep-network 时，它还会保留上述网络设置。它不会撤销在系统本身中手动做出的更改，例如某个软件包或 /etc 中的某个文件；用 os flash 将 IronFlockOS 重新写入磁盘才能做到这一点。

它按以下顺序执行：

1. 拒绝设备无法按要求完成的请求（见下文），并检查 -c 的 .flock 文件：名为 *.flock、最大 5 MiB 的文件，内容是一个带有 secret 和 device_key 的 JSON 对象，其 name 和 serial_number 是普通名称。
2. 在 stderr 上说明哪些内容会被清除、哪些会保留、设备如何恢复以及其上一次重置的情况，然后要求您输入设备的名称：即代理程序 .flock 文件中的名称（与 ironflock status 显示的相同），或者尚未注册的设备的主机名。输入其他任何内容（包括直接按 Enter）都视为回答“否”。
3. 在设备自身的检查接受该请求之后，将请求写入 IRONFLOCKOS 分区。已有的请求会被替换；这次是一个新请求，有自己的三次尝试机会。
4. 带 -c 时，从该分区中删除所有其他 .flock 文件（因为设备会用最新的那个注册），并将新的 .flock 文件写到那里。如果这一步失败，请求会再次被删除。
5. 重启设备。在下一次启动期间，设备会在几秒钟内（在较慢的 SD 卡上需要几分钟）完成自我重置，再重启一次，并以刚写入的设备的状态启动，带有新的 SSH 主机密钥。

重置之后，带 -c 时，设备会作为该 .flock 文件所对应的设备注册，并可以通过 SSH 以其 SSH 用户的身份访问。不带 -c 时，它会等待其 IRONFLOCKOS 分区上出现 .flock 文件，并且只能通过其控制台访问：它没有 SSH 用户，也没有与 IronFlock 的连接。与设备的 SSH 连接（包括 --host 的连接）会随重启而结束；不带 -c 时，不会再有任何连接恢复。

注意：如果您只能通过网络访问设备，请用 -c 给出新的 .flock 文件。不带它时，必须有人到设备现场才能让它重新上线。

失败的尝试不会重启设备：设备按原样启动，其下一次启动（无论由人触发还是由更新触发）会再次尝试。三次尝试失败之后，重置会放弃，设备以现有的内容启动。带着旧数据，它仍是原来的设备，以旧身份在线，随请求而来的 .flock 文件和代理设置会被删除。已结束的请求（无论已完成还是已放弃）永远不会再次触发，无论在哪个槽位、经过哪次更新。不响应的磁盘可能会让一次尝试持续长达 25 分钟。ironflock status 会在其 Last reset: 这一行中显示失败或已放弃的重置。

在询问之前，命令会显示设备记录的上一次重置：

# 重置设备；之后它会等待 .flock 文件
sudo ironflock os reset
# 重置设备，并让它成为 new-device.flock 所对应的设备
sudo ironflock os reset -c new-device.flock
# 保留网络设置，不询问
sudo ironflock os reset --keep-network --yes
# 从另一台电脑运行，适用于 IronFlockOS 0.15.0
ironflock --host operator@edge-01 os reset -c new-device.flock

在上一次重置已放弃的设备 edge-01 上，os reset -c kitchen-pi.flock 的输出如下，询问时输入了名称：

This device runs IronFlockOS 0.15.0 from slot B and is the IronFlock device edge-01.
The last factory reset of this device: gave up after 3 attempts at 2026-11-11T09:00:00Z: the data partition is not the partition named data on the disk of the root slot; /data holds the old data; left of the old owner: the data partition, the booted root slot, the other root slot; the device stayed the device it was, online with its old identity, and the .flock and proxy.conf that came with the request were removed.
What can be done: request the reset again, as this command does now, with three new attempts; or write IronFlockOS to the device's disk anew ('ironflock os flash'), which clears everything.
The factory reset restarts the device now. During the next boot the device resets itself, in seconds (minutes on a slow SD card), and restarts once more. It clears:
  - the apps with their data, and Docker's containers, images and volumes
  - the device's identity at IronFlock: the agent with its copy of the .flock and its database; the hostname goes back to ironflockos
  - the SSH user and every other user account, with their home folders
  - the logs, the SSH host keys and the downloaded updates
  - the network profiles (the WiFi among them), the proxy setting and the PTP setting
It keeps IronFlockOS 0.15.0 in slot B, which runs, and IronFlockOS 0.14.0 in slot A, so updates and rollbacks work as before.
It does not undo what was changed by hand in the system itself, such as a package or a file in /etc.
Then the device starts as a freshly written one with kitchen-pi.flock, which goes onto its IRONFLOCKOS partition: it enrolls as kitchen-pi and can be reached over SSH as operator, with the device key of that .flock and new SSH host keys.
An attempt that fails does not restart the device: it comes up as it is, and its next start tries again; after three failed attempts the reset gives up, and the device starts with what is there. 'ironflock status' shows a failed or given-up reset.
An SSH connection to the device, also the one of --host, ends with the restart.
? Type the device's name, edge-01, to reset it: edge-01
Factory reset requested: the device restarts now, resets itself and enrolls as kitchen-pi.

os reset --keep-network --yes --json 的结果：

{"action":"reset","device":"edge-01","keep_network":true}

拒绝执行的情况（退出码 3，并说明原因和应对办法）：

• 它不是以 root 身份运行、在不运行 IronFlockOS 的机器上运行、在安装 U 盘上运行，以及 RAUC 正在安装更新包时。
• 该 IronFlockOS 不支持恢复出厂设置：较新的发布版本支持，os update 可以安装它。
• /boot/efi 不是已挂载的 IRONFLOCKOS 分区：那里没有挂载任何内容，或者挂载的是 FAT 以外的文件系统。
• 重置已经开始：它会在下一次启动时继续，在此之前不应更改任何内容。消息会给出上一次尝试。
• 不带 -c 时，IRONFLOCKOS 分区上有一个 .flock 文件：重置之后，设备会用它注册，而不是等待 .flock 文件。
• 下一次启动的不是已标记为良好的正在运行的系统。更新或回滚正在等待重启：sudo reboot 会启动它，sudo rauc status mark-bad other 会放弃它。或者正在运行的系统尚未被标记为良好：sudo rauc status mark-good 会保留它，os rollback 会回退。
• 设备自身的检查不接受该请求：不会请求任何内容，消息会给出设备的原因。

失败的情况（退出码 1）：

• 无法读取挂载表，因此命令无法判断 /boot/efi 是否为 IRONFLOCKOS 分区。不写入任何内容。
• -c 的 .flock 文件无效。
• 无法写入请求或 .flock 文件，或者无法删除另一个 .flock 文件。请求会被撤回，错误会说明已删除了什么。
• 重启失败。此时设备会在下一次启动时完成自我重置；从 IRONFLOCKOS 分区中删除 /boot/efi/factory-reset.conf 和 .flock 文件即可取消重置。

在命令写入请求期间，Ctrl-C、SIGTERM 或 SSH 会话丢失会使它撤回请求：命令以退出码 130 结束，设备不会重启。询问时输入错误的名称，命令会以退出码 4 结束。

所有命令的退出码在标志、输出与退出码中有说明。通过 --host 运行时，退出码 255 表示 SSH 连接失败。