使用 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_fullRestore 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 SystemHAOS与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 操作步骤如下进入SettingsAutomations scenes。打开一个已有的自动化或脚本或选择Create automationCreate new automation。如果是新建自动化在When部分添加触发器脚本不需要触发器它们在被其他内容调用时运行。在Then do部分选择Add action。搜索并选择Restore from full backup。输入要恢复的备份的Slug可选输入其Password。选择Save保存。UI 中的选项在 UI 表单中该动作暴露两个字段选项描述是否必填Slug要从中恢复的备份的 slug必填Password备份的密码若该备份受密码保护可选其中Slug是定位备份的唯一标识。你可以在SettingsSystemBackups页面中找到每个备份的 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同样可在SettingsSystemBackups中查到。YAML 中的选项参考字段名类型描述是否必填slugstring要从中恢复的备份的 slug必填passwordstring备份的密码若备份受密码保护可选与 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.markdownhassio.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必须与创建备份时设置的一致恢复期间是否断网或断电由于恢复过程包含重启中途断电可能造成系统处于不完整状态恢复操作应在稳定供电与网络环境下进行。相关动作hassio.restore_full与以下动作配合使用效果最佳官方文档通过 source/_includes/actions/related.md 自动列出相关动作Restore from partial backuphassio.restore_partial从部分备份中恢复选定的部分用于只回滚单个加载项或文件夹的场景Create a full backuphassio.backup_full创建完整备份是恢复的数据来源执行后返回备份 slug可被hassio.restore_full引用。推荐的完整备份-恢复闭环是日常用hassio.backup_full按计划如每天 03:00自动备份升级或重大变更前再手动备份一次并记录 slug当系统出现问题时评估是整体回滚hassio.restore_full还是局部回滚hassio.restore_partial再执行对应动作完成恢复。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考