恢复

Mica OS 的恢复是数据优先保留的：下面的步骤按代价递增排列，走到第 n 步的 操作者，已经确认第 1..n-1 步不够用。顺着这个顺序往下走就是流程本身。 因为“大家都记得最后那一步”而直接跳到底，正是设备丢掉本不必丢的数据的方式。

本页对这个顺序中间的缺口同样直白：其中两步已经建好、测试过，而且在今天 存在的任何板卡上都无法执行。第 7 节说明是哪两步、为什么，以及操作者转而 该做什么。

1. 自动尝试与回退

新候选有三次启动尝试，固件在启动候选前持久化扣减次数。健康门确认正常部署； 失败耗尽后选择保留的可用部署。root、kernel 和 support 引用一起切换，DATA 共享 且不会回滚。卡死还需要可用看门狗复位，cx3576 物理覆盖仍需板级验收。

status: shipped — evidence: mica-deploy:src/boot.rs, mica-system:overlay/usr/lib/mica/mica-health, mica-build:tests/lifecycle-uefi/updates.sh

2. 尝试耗尽与共享存储故障

没有可用部署时，固件进入明确恢复状态，绝不补充耗尽计数。cx3576 提供本地 rockusb 恢复传输，UEFI 策略显示明确恢复信息并停止。SYSTEM 或 DATA 损坏在服务启动前作为 共享存储故障报告，不反复归咎于不同 root 映像。

保存完整串口记录、可获得的原生状态和确切镜像/组件 ID。共享存储或全部部署不可用 时刷完整最新版镜像，不编辑计数器或导入启动命令。

status: board-dependent — evidence: mica-boards:boards/cx3576/loader/mica-file-boot.c, mica-system-base:debs/mica-systemd-boot/persistence.patch, mica-build:tests/lifecycle-uefi/faults.sh

3. 决策树

#	步骤	今天可用？	可逆？	代价
1	只读诊断	是	是	无
2	受保护的手动回滚	是	是	一次重启；被判坏的部署不再是回滚目标
3	配置重置	是	否	该层级触及的全部建模设置
4	应用数据重置	是	否	/srv 下全部操作者数据，以及 /mica 下每个应用的数据
5	凭据恢复	否——现场不受支持	否	旧凭据和全部 API token
6	恢复出厂	否——现场不受支持	否	设置、凭据、应用和操作者数据，一起没
7	整盘重刷	是，需要物理接触	否	每个分区，以及设备身份
8	安全擦除	否——不受支持，也没有计划	终结	这台设备作为一个已配置单元的一生

八步里有五步是你真能走的。第 5 步和第 6 步由一个没有任何出厂板卡能够 产生的物理在场断言把关，因此在每一台已上线设备上都会被拒绝；第 8 步根本没有 实现。第 7 节逐条写出这些缺失，以及替代做法。丢了凭据和全部公钥的操作者， 只能靠第 7 步，别无他法。

**分界线在第 2 步和第 3 步之间。**线以上的一切都能靠重启撤销。线以下的每 一步都会销毁设备上曾经有的东西，本页没有任何东西能把它找回来：这个产品里 没有备份/恢复契约，所以不可逆的步骤在 Mica OS 今天能给出的最强意义上就是不可逆。

status: shipped — evidence: docs/design/recovery.md

4. 可逆的步骤

第 1 步——只读诊断

• **修复：**什么都不修。它决定下面哪一步才是对的，而大多数情况到这里就结束。
• **代价：**无。
• **不能恢复：**启动都走不到能应答的设备——那是第 2 节的情形，不是这一步。
• 读什么：GET /api/v1/update 看更新生命周期、两个部署、当前启动的部署以及 回滚是否被允许；GET /api/v1/storage/status 看各层就绪状态与介质健康； 再加诊断快照和审计轨迹。诊断本身由 troubleshooting.md 负责。

步骤 2 — 受保护的手动回滚

经过认证的 POST /api/v1/update/rollback 需要规定的 CSRF token。原生后端验证 当前启动回执和保留的已认证回退部署，将当前部署标记失败、切换启动选择，返回 当前/目标身份及明确的重启下一步。重复请求或缺失、无效回退目标会被拒绝。

该操作保留 DATA 上的配置、凭据和应用数据，不能恢复丢失凭据或撤销持久写入。 重启为独立操作。QEMU 已覆盖真实请求及随后回退，cx3576 实机执行单独验收。

status: shipped — evidence: mica-deploy:src/deployments.rs, mica-core:apid/openapi.json, mica-core:tests/apid-api/src/phases/07-update-rollback.ts

5. 破坏性的步骤：重置与凭据恢复

本节每一步都是不可逆的。每一步都要按名字请求——没有不带参数的重置—— 而且每一步都会被审计。重置是暂存一份意图，由 micad 在下一次启动时执行， 所以操作者的动作是两个：发出请求，然后重启；在那次启动之前设备完全还是 重置前的样子。被打断的重置是可重放的：下一次启动会把它做完。

第 3 步——配置重置——不可逆

• **修复：**被自己的网络、访问或策略设置搞到不可达或不可用的设备，以及任何 乱到理不清的设置状态。
• **不可逆的代价：**每一项建模设置——网络、访问、时间、更新策略、应用设置， 一次全部。没有按子树重置这回事。
• **不能恢复：**丢失的凭据（管理员凭据是被刻意保留的——一个会丢掉凭据的 设置动作，只是换了个好听名字的锁死）、应用数据、坏掉的部署。
• 怎么做：POST /api/v1/reset，body 为 {"tier": "configuration"}， 需认证，不需要物理在场。

动手之前先读这一段：更新设置也会一起还原。一次配置重置会把更新渠道 和更新服务器地址还原成这台设备镜像构建时的取值，操作员做过的改动一律丢 弃。这究竟是一条恢复路线还是一个意外，取决于那些内置取值是什么，而只有两种 情况：

• **镜像里指定了服务器。**设备回到那台服务器和那个渠道。如果有人把设备重新 指向了一台后来发现是错的服务器，这就是不用重刷、也不用物理接触就能撤销它 的办法。
• 镜像里没有指定服务器——集成商把地址留待后设的构建就是这种情况。此时重 置不会把设备换到另一台服务器，而是换到没有服务器。设备会悄无声息地 停止检查更新，剩下的路只有离线导入和整盘重刷。重置前先看 GET /api/v1/provisioning/status：它会分别报告内置地址、操作员的覆盖值 和生效值，你可以据此判断自己属于哪一种情况。

同样的话适用于第 6 步（恢复出厂），它会把这一层还原的东西全部还原、并且更 多。第 4 步不碰这些设置——应用数据重置不动更新配置。

**如果你只想把地址要回来，不必动用这一层。**用 POST /api/v1/update/config 发 {"source": {"url": null}}，那一个键就回到内置 默认值，其余配置原封不动——一次复位是拿全部设置去换回一个。见 update-rollback.md。

第 4 步——应用数据重置——不可逆

• **修复：**自身状态把自己或设备卡住的应用、塞满的 /srv、要干净移交的 应用层。
• 不可逆的代价：****/srv 下的全部操作者数据，以及 /mica 下每个应用的 数据。没有任何备份契约可以退守。
• **不能恢复：**平台设置、凭据、部署。
• **怎么做：**同一路由，{"tier": "application-data"}，条件相同。

第 5 步——凭据恢复——不可逆，且今天够不着

• **修复：**丢了管理员凭据和全部授权公钥的操作者所处的锁死状态，**而且不 丢一个字节的操作者数据。**这正是它排在恢复出厂之前的原因：它是唯一一个 既解锁又保住一切的步骤。
• **不可逆的代价：**新凭据被铸出的那一刻，旧凭据停止工作，全部 API token 一起作废。任何持有它们的自动化都必须重新登记。
• 不能恢复：旧的秘密。这个流程只铸新、绝不揭示——设备上没有任何东西 会把存储的密码交还给你。
• 纸面上怎么做：POST /api/v1/recovery/credential，只由物理在场授权， 别无其他。已认证的调用方会被拒绝，并被告知改用 POST /api/v1/actions/change-password。
• 为什么你做不了：见第 7 节。该流程已实现、已测试，而没有任何出厂板卡 声明物理恢复动作，所以在已上线的设备上它每次都被拒绝。做规划时请当它不 存在：丢失管理员凭据和全部授权公钥的操作者，只能整盘重刷（第 7 步），并 换来一个新的设备身份。

status: unsupported

第 6 步——恢复出厂——不可逆，且今天够不着

• **修复：**没有具体的哪一项。它是“这台设备的全部可变状态就此放弃”这个 决定——退役、移交，或第 3 到第 5 步都没能解决的故障。
• **不可逆的代价：**设置、管理员凭据、API token、每一个应用和全部操作者 数据，一起没。
• **按设计被保留的：**设备身份、标定数据、DATA/meta 上的更新元数据，以及两个 系统部署。重置重置的是状态，不是已安装的软件版本。
• **同样会还原的：**更新渠道与更新服务器地址，回到镜像构建时的取值——第 3 步 的警告在这里原样适用，包括内置地址为无、于是设备被留在没有任何更新服务器 的状态这一种情况。
• **不能恢复：**起不来的设备，因为没有带内程序在跑；损坏的系统部署。
• **纸面上怎么做：**重置路由加 {"tier": "full-factory"}，由与第 5 步相同的 物理在场把关——今天在每块板卡上都因同样的原因被拒绝。请按它缺席来规划： 需要干净移交的设备只能重刷（第 7 步），代价是一个新的设备身份。

status: unsupported

恢复出厂不会让设备变得匿名

这是读者最常自己脑补、而且补错的一句话；补错的结局是一台可被关联的设备落到 别人手里。

恢复出厂会保留设备身份和标定数据。这是刻意为之。deviceId 在设备上 只抽取一次，永不重新签发，因为在一台还能用的单元上重铸它，会悄悄切断车队 侧、支持侧和保修侧每一条按该身份记录的档案——这个后果比它本来要解决的锁死 更糟。恢复出厂之后回来的是同一台设备：同样的身份、同样由身份派生的主机名、 同样的标定。它不是一台新单元，也不是一台匿名单元。

所以恢复出厂不是处置操作。**要离开操作者控制的设备——转售、退货、RMA、 报废——需要整盘重刷，或者销毁介质。**只有重刷会整体替换 DATA/state，从而让下一次 首次启动铸出新身份；而只有物理销毁介质才能真正去掉数据：重刷只写镜像自身 的范围，DATA 曾经扩展进去的、超出该范围的块仍留在介质上，新文件系统不再 引用它们，但它们还在。docs/design/access.md 第 9.2 节精确陈述了重刷够得着 和够不着什么，docs/design/manufacturing.md 第 5 节则是这里遵循的 RMA 规则：退回的设备从签收那一刻起，其凭据一律按已泄露处理，因为 DATA/state 没有 加密，寄回它的人本来就读得到。

如果设备要交给另一方而它的数据不能跟着走，就销毁介质。今天没有比这更软的 说法是诚实的，第 6 节说明了为什么。

status: shipped — evidence: mica-core:micad/src/reset.rs, mica-core:apid/src/routes.rs, docs/design/manufacturing.md

6. 操作系统之下：重刷与处置

第 7 步——整盘重刷——不可逆，而且会更换设备身份

最后手段位于操作系统之下，在别的一切都不可达时仍然可达：cx3576 上是 Rockchip loader 路径（上电时按 recovery 键、启动失败时自动落入，或 loader 区本身没了时用 maskrom），然后通过 USB 写入整盘镜像；x64 上则是启动另一份 介质并重写磁盘。流程见 install.md。

• **修复：**软件层面所有可能出错的东西，包括两个部署同时坏。它不需要设备上 的任何东西还能工作。
• **不可逆的代价：**每一个分区——FIRMWARE/ESP、SYSTEM 和 DATA——以及设备身份： 下一次首次启动会铸出新的 deviceId 和新的密钥，车队侧按旧身份记录的档案 必须人工重新关联。
• 不能恢复：软件层面没有。但请注意它不做什么：它不擦除。见上面那段 和第 8 步。

status: board-dependent — evidence: mica-boards:boards/cx3576/Makefile, docs/design/access.md

第 8 步——安全擦除——终结，且未实现

Mica OS 上没有安全擦除。设备连这个请求都表达不出来：重置词汇表里正好三个层级， 没有第四个，所以 secure-wipe 不是这台设备能解析的 body。这个缺席是立场 而不是疏漏——擦除承诺的是关于介质的事，那需要一个设备级擦除原语（eMMC sanitize、NVMe format-NVM），而它在这些板卡上的真实行为没有人验证过。

**在某块板卡把这份证据存档之前，唯一的指示是销毁介质。**不是重刷它，不是 写满零，也不是在一层可以自由改写落点的闪存转换层上跑用户态粉碎工具。

status: unsupported

7. 操作者今天做不到的事

这些要写出来而不是略过，因为假定它们可用的读者，规划的是一条并不存在的 恢复路径。

• **第 5 步和第 6 步在每一台已上线的设备上都会被拒绝。**两者都由物理在场 断言把关。这道闸门是发布并测试过的，产出断言的系统侧同样已经发布：板卡 声明自己拥有哪些物理恢复动作——引导菜单项、按键组合、USB 事件——设备把 操作者实际执行的那一个映射成在场断言，并在该动作如此声明时暂存对应的 重置层级。没有任何出厂板卡声明动作——cx3576、x64、virt-arm64 都没有—— 因为三块都没有已实现的物理动作，所以这道闸门会拒绝一台已上线设备能够 发出的每一个请求——403， 附 presence_required，有审计，什么都不暂存，而且拒绝语句说的是“这块板卡 没有声明任何物理恢复动作”，而不是“没有人站在设备旁边”。要解开这一条， 需要的是某块具名板卡的 BSP 工作，而不是改动这些流程。
• **cx3576 的 recovery 键不是在场断言。**它把板卡送进 rockusb loader 模式， 没有任何软件恢复流程会去读它。这个产品里没有按键驱动的恢复。
• **所以今天被锁在外面的操作者只有一个答案，就是第 7 步。**丢失管理员凭据 和全部授权公钥，仍然意味着没有软件路径能回到设备里：只有 apid 能启用 SSH、加公钥或设密码，而它需要凭据；SSH 要么关着要么没有公钥；串口控制台 给出登录提示，但没有任何账户会接受凭据。这就是 docs/design/access.md 第 9.1 节记录的处境，在每一块板卡上它依然是已发布的 真相。退路是整盘重刷，用设备身份去换一个忘掉的密码。
• 安全擦除不存在，见第 8 步。
• **根本没有修复层，离线的和在线的都没有。**Mica OS 没有任何专门的非破坏性修复 操作：没有修复路由、没有修复流程、没有救援启动项、也没有恢复环境。一台还能 启动的设备上存在的，是启动时自动跑的布局收敛与文件系统检查，以及普通的 已验证更新——后者也能把损坏且未被引用的组件重新装一遍。无法用这条路恢复的设备， 需要一台把它的文件系统卸载后再诊断的服务主机，或者走第 7 步；Mica OS 不承诺 损坏的数据在哪一条路上能保住。

status: unsupported

8. 恢复之前：先收集证据

如果设备还能启动进保留部署，请在重置或重刷之前收集 troubleshooting.md 列出的东西——日志、更新状态、存储 状态，以及 /usr/share/mica/manifest.tsv 里的设备身份。从第 3 步往下的每一步 都会把故障连同状态一起销毁，而重刷之后才开的支持工单里什么都没有。 support.md 第 4 节列出一份报告需要包含什么。