HA Bridge

Appearance

备份与恢复 ​

日常备份和换设备迁移，使用编辑器右上角的「备份与恢复」。创建备份会下载一个密码加密的 .habackup 文件；恢复时先检查文件，再确认覆盖。

本页按 0.7.0 的流程说明，可用于独立 Docker 与 Home Assistant Add-on 之间迁移业务数据。截图来自独立演示安装，数量仅作示例。

编辑器右上角的备份与恢复入口

1. 创建备份 ​

  1. 先保存仪表盘修改，户型绘制页等待自动保存完成。
  2. 点击「备份与恢复」，选择「创建备份」。
  3. 输入并确认备份密码，长度为 8–128 个字符。
  4. 点击「下载加密备份」，等待下载完成。
  5. 将备份文件和密码妥善保存在 HA Bridge 运行设备之外。

创建备份：设置独立密码并下载加密文件

备份密码由你单独设置，遗失后无法恢复。文件上限为 512 MB；提示超过限制时，先整理不需要的素材再重试。

完成标志： 下载到 .habackup 文件，并已保存对应密码。

2. 检查并恢复 ​

开始前先登录并激活当前安装，建议先为当前数据创建一份备份。

恢复会覆盖当前业务数据

恢复会整体替换所有仪表盘、户型、素材和 HA 连接，也会丢弃未保存修改。当前管理员账号和授权继续保留；恢复后中控设备需要重新配对。操作期间保持窗口打开，等待完成。

  1. 打开「备份与恢复」，选择「恢复备份」。
  2. 选择 .habackup 文件，输入创建该文件时设置的备份密码。
  3. 点击「检查备份文件」。这一步只检查文件，不修改当前数据。

选择备份文件、输入备份密码并先检查

  1. 核对显示的备份版本、日期、仪表盘数、HA 连接数、文件数和中控配置数。
  2. 检查通过后，在 10 分钟内输入当前安装的管理员登录密码，勾选覆盖确认。
  3. 点击「确认覆盖并恢复」，等待编辑器自动刷新。

检查通过后核对内容，输入当前管理员密码并确认恢复

  1. 刷新后检查仪表盘、户型和图片；如需重新登录，使用当前账号。确认 HA 重新连接、设备状态正常。
  2. 按连接中控设备重新配对平板或浏览器。

完成标志： 恢复内容能正常打开，HA 状态与控制正常，中控重新配对后能使用。

备份包含哪些内容 ​

  • HA 连接及其访问令牌、实体与设备配置。
  • 仪表盘、已保存的草稿和组合弹窗。
  • 绘制户型、3D 交互户型、用户素材和导出文件。
  • 中控配置的名称、仪表盘关联和启用状态；恢复后会生成新配对码。

管理员账号、密码、激活密钥和安装身份不随业务备份转移，恢复时使用当前安装的账号和授权。部署命令、端口和挂载路径请另外保留。

换设备时怎么迁移 ​

  1. 在旧设备上保存内容并下载 .habackup 文件，确认备份密码已保存。
  2. 按解绑与建议释放旧设备的授权绑定。
  3. 在新设备部署 HA Bridge，创建管理员账号并完成激活。
  4. 使用本页的「恢复备份」导入旧设备的业务数据。
  5. 检查 HA 连接和设备控制，重新配对中控；确认新设备正常后再清理旧设备。

恢复会检查版本与文件格式。低版本程序不能恢复高版本备份；提示版本过低时，先更新目标安装。旧版业务备份是否兼容，以「检查备份文件」的结果为准。

找不到入口，或检查失败怎么办？
  • 没有「备份与恢复」按钮：升级到支持内置备份的版本；暂时不能升级时，按下面的目录备份方式保留数据。
  • 备份密码错误或文件损坏：核对创建备份时的密码，重新选择原文件；不要修改文件内容。
  • 检查结果已失效：重新检查文件，再在 10 分钟内确认。
  • 当前管理员密码不正确：输入当前安装的登录密码；它与备份密码是两项独立输入。
  • 文件格式不支持：内置恢复只接收 .habackup，手工压缩的目录或升级回退包请按各自的恢复方式处理。

系统会自动保留本机业务回退副本，用于恢复异常处理。仍应单独保存自己的 .habackup 文件。持续报错时先查看运行与更新问题排查，保留原文件和数据目录。

旧版或整套安装备份 ​

忘记管理员密码而无法登录，或需要保留整套安装、处理旧版数据时，可使用目录备份。HAOS 用户使用包含 Add-on 数据的 Home Assistant 备份。

Docker / NAS：完整复制目录

需要备份的内容 ​

同时保留 data、secrets 和部署配置。data 包含数据库、仪表盘、素材、户型和 admin-account.json；secrets 保存连接与安装所需密钥。

备份步骤 ​

  1. 停止 HA Bridge 容器或 Compose 项目。
  2. 完整复制 data 和 secrets，保留目录结构及文件权限。
  3. 保存 Compose 文件或 Docker Run 命令，记录镜像版本、端口和挂载路径。
  4. 确认备份可读取且不是空目录。

只复制 app.db 会遗漏账号文件、图片和密钥；不要用空目录覆盖现有数据。

恢复到原设备 ​

  1. 停止 HA Bridge，先保留当前目录副本。
  2. 将备份的 data、secrets 恢复到原挂载位置。
  3. 确认容器内路径仍为 /data 和 /run/secrets，使用匹配或兼容该数据的程序版本。
  4. 启动后检查账号、授权、仪表盘、素材和 HA 连接。

从尚未分离账号的旧版完整备份恢复到新版时，系统会迁移原账号。新版备份遗漏 admin-account.json 会进入账号设置；先核对备份，避免误建新账号。

回退旧程序需使用与该版本匹配的升级前完整备份，不能只换旧镜像继续使用升级后的数据。换设备迁移优先升级后创建业务备份，按上面的新设备流程操作。

忘记账号或密码时，另见重置本地账号与密码。

让 Home Assistant 的日常使用更直观。

HA Bridge