使用 hassio.restore_full 动作从完整备份恢复 Home Assistant-港品优选

使用 hassio.restore_full 动作从完整备份恢复 Home Assistant

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本篇技术指南讲解 Home Assistant 的hassio.restore_full动作：它如何将整个系统（Home Assistant 本体、所有加载项应用及其数据）从一份完整备份中整体还原。读完本文，你将掌握在自动化与脚本中通过 UI 与 YAML 两种方式调用该动作的完整方法、slug与password两个参数的准确含义与取值范围、以及它与hassio.restore_partial、hassio.backup_full的配合关系，能够在系统故障或升级失败时设计出可靠的恢复流程。

动作概述：一次还原整个系统

hassio.restore_full（Restore from full backup）是 Home Assistant 中用于"从完整备份恢复"的内置动作。执行该动作时，系统会把当前运行的 Home Assistant、所有加载项（apps）及其数据整体替换为备份中的内容——也就是说，备份之后对系统所做的任何更改都会丢失。

这一点在官方动作文档 source/_actions/hassio.restore_full.markdown 中有明确告诫：

Restoring overwrites your current setup with the contents of the backup. Anything you changed after the backup was made is lost.

因此，官方文档也特别强调：大多数用户应当从 UI 的备份页面恢复，而不是从自动化中触发恢复。hassio.restore_full更适合被理解为一个"紧急救援"手段——例如自动化检测到某次核心更新导致系统无法正常工作时，自动回滚到更新前的备份。

与"创建备份"动作的关系

hassio.restore_full与创建备份的动作hassio.backup_full（见 source/_actions/hassio.backup_full.markdown）是一对配套操作：

hassio.backup_full负责产生完整备份，包含 Home Assistant、全部加载项及其数据，执行后可返回本次备份的slug，供后续步骤引用；
hassio.restore_full负责消费这份备份，用备份内容覆盖当前系统。

一个典型的"先备份、后恢复"闭环是：升级前用hassio.backup_full生成快照并记录slug，若升级后出现问题，再用hassio.restore_full以该slug还原现场。两者的slug可以在Settings > System > Backups页面中查看。

适用环境与权限限制

在配置该动作之前，需要先确认你的安装方式是否满足前提条件。根据文档"Good to know"部分的说明，hassio.restore_full有两个硬性限制：

仅管理员可执行：只有 Home Assistant 的管理员用户（admin）才能运行该动作。普通用户在自动化、脚本或开发者工具中调用会失败。
仅部分安装方式可用：该动作只在Home Assistant Operating System（HAOS）与Supervised（监督式）两种安装方式下可用；在Home Assistant Container（容器）与Home Assistant Core（纯 Core）安装方式下该动作不存在、无法调用。

这两条限制同样适用于配套动作hassio.restore_partial与hassio.backup_full，它们是整个备份体系的一致性约束。

从用户界面使用该动作（无需 YAML）

如果你习惯在 UI 中构建自动化与脚本，Home Assistant 会引导你逐步完成配置，无需编写任何 YAML（对应文档 include 见 source/_includes/actions/ui_header.md）。

官方文档给出的 UI 操作步骤如下：

进入Settings>Automations & scenes。
打开一个已有的自动化或脚本，或选择Create automation>Create new automation。
如果是新建自动化，在When部分添加触发器；脚本不需要触发器，它们在被其他内容调用时运行。
在Then do部分选择Add action。
搜索并选择Restore from full backup。
输入要恢复的备份的Slug，可选输入其Password。
选择Save保存。

UI 中的选项

在 UI 表单中，该动作暴露两个字段：

选项	描述	是否必填
Slug	要从中恢复的备份的 slug	必填
Password	备份的密码（若该备份受密码保护）	可选

其中Slug是定位备份的唯一标识。你可以在Settings>System>Backups页面中找到每个备份的 slug。需要注意的是：UI 中的必填项意味着如果留空，动作无法正常执行。

在 YAML 中使用该动作

如果你直接编写 YAML，或者希望精确掌握 Home Assistant 底层的字段行为，可以按 YAML 技术参考来调用（对应文档 include 见 source/_includes/actions/yaml_header.md）。

在 YAML 中，该动作的名称为hassio.restore_full。官方文档给出的基础示例如下：

action: hassio.restore_full data: slug: 1f2e3d4c

这个示例中的slug值1f2e3d4c是文档使用的示例值，实际使用时必须替换为你系统中真实备份的 slug（同样可在Settings>System>Backups中查到）。

YAML 中的选项参考

字段名	类型	描述	是否必填
`slug`	string	要从中恢复的备份的 slug	必填
`password`	string	备份的密码（若备份受密码保护）	可选

与 UI 表单一一对应：slug是唯一必填参数，password仅在备份创建时设置了密码的情况下才需要提供。若备份没有密码而你在恢复时提供了password，或反之备份有密码而恢复时未提供，动作可能无法完成解密与还原。

在完整自动化中调用

下面是一个将hassio.restore_full放入真实自动化场景的完整 YAML 示例。该自动化在 Home Assistant Core 的更新实体变为on（即有可用更新）时先执行备份，随后在指定条件下恢复——实际生产环境建议仅在确认更新失败时才执行恢复，可将恢复步骤封装为独立脚本或由人工确认触发：

automation: - alias: "Rollback to previous full backup" triggers: - trigger: state entity_id: update.home_assistant_core_update to: "on" actions: - action: hassio.restore_full data: slug: "1f2e3d4c" # 替换为更新前由 hassio.backup_full 创建的备份 slug

参考 source/_actions/hassio.backup_full.markdown 中"Automation: a full backup before a core update"的写法，可以先用hassio.backup_full在更新前生成备份，再在需要回滚时用hassio.restore_full恢复。注意hassio.backup_full会返回所创建备份的slug（存于response_variable中），你可以据此在后续动作中引用它。

恢复期间系统不可用

执行hassio.restore_full会触发一次Home Assistant 重启，重启是恢复流程的组成部分。这意味着：

恢复过程中 Home Assistant 会暂时不可用（unavailable for a while）；
自动化、脚本中依赖 HA 的后续步骤可能因系统重启而中断；
请勿在关键服务运行期间随意触发该动作，建议将恢复动作安排在维护窗口或系统故障场景下。

这一点与hassio.restore_partial有所区别：部分恢复只有在恢复了 Home Assistant 设置这一项时才会触发重启；而完整恢复必然覆盖整个系统，因此必然重启。

与部分恢复（restore_partial）的选择

在动手恢复之前，请判断你的需求是"全部还原"还是"只还原一部分"。官方文档为两者提供了清晰的分工（见 source/_actions/hassio.restore_partial.markdown）：

hassio.restore_full：还原整个系统（Home Assistant + 全部加载项 + 全部数据），适合系统级故障、整体回滚；
hassio.restore_partial：只还原选中的部分——Home Assistant 设置（homeassistant: true）、指定加载项（apps:列表）或指定文件夹（folders:列表）。当你只想回滚某一个加载项而不想动系统其他部分时，部分恢复更安全、影响面更小。

# 对比：部分恢复仅还原 Home Assistant 设置 action: hassio.restore_partial data: slug: 1f2e3d4c homeassistant: true

由于restore_full会覆盖你当前的全部配置与数据，而restore_partial只影响所选部分，官方文档在两条动作的说明中都强调：大多数情况下应从 UI 的备份页面手动恢复，而不是通过自动化触发。只有在你有明确、可控的恢复流程设计时，才适合在自动化中调用恢复动作。

常见问题与排查思路

文档末尾的"Still stuck?"部分（见 source/_includes/actions/stuck.md）提示，当动作执行不符合预期时，可以携带以下信息寻求社区帮助：

你正在调用的动作名称（hassio.restore_full）；
你期望发生什么（例如"恢复到某日的完整备份"）；
实际发生了什么（报错信息、日志片段）。

在实际排查hassio.restore_full执行失败时，可以按以下顺序检查：

slug 是否正确：slug 是必填项且必须对应Settings > System > Backups中真实存在的备份；
权限是否足够：当前登录用户是否为管理员；
安装方式是否符合前提：HAOS 或 Supervised 环境才有此动作；
密码是否匹配：若备份有密码保护，password必须与创建备份时设置的一致；
恢复期间是否断网或断电：由于恢复过程包含重启，中途断电可能造成系统处于不完整状态，恢复操作应在稳定供电与网络环境下进行。

企业官网建设流程全解析