Home-Assistant-Matter-Hub 可以将 Home Assistant 中的设备通过 Matter 协议发布给 Apple Home、Google Home、Alexa 等控制器。在切换 Alpha 与 Stable 版本、更换硬件或升级镜像时，备份与恢复功能帮你完整保留桥接配置、实体映射和 Matter 配对身份，让你无需重新配对任何设备。

Home-Assistant-Matter-Hub 备份与恢复设置页面，可下载配置备份和含身份数据的全量备份

为什么迁移前必须备份？

Alpha 和 Stable 两个版本使用不同的 Add-on 标识符（hamh-alpha与hamh），它们各自拥有独立的数据目录。这意味着：

• Home Assistant 系统备份无法在两个版本之间迁移数据
• 直接切换版本后，新目录里没有桥接配置，控制器会认为所有设备都消失了
• 更糟的是，如果目标版本里已存在旧桥接，它会带着旧的身份先启动，导致控制器把设备识别为"新设备"，丢失自定义名称和房间归属

解决办法就是项目内置的备份系统：它会把桥接配置、实体映射，以及最关键的Matter 身份数据（密钥对、fabric 凭证）打进一个 ZIP 包。只要恢复了身份文件，Google Home、Apple Home、Alexa 会认出原设备，完全不需要重新配对。

💡 备份文件里自带README.txt提醒：全量备份包含敏感的 Matter 身份数据，请妥善保管。

备份入口在哪里？

打开 WebUI，进入Settings页面，最上方就是Backup & Restore卡片，提供三类操作：

前端界面源码位于 BackupRestore.tsx，API 定义在 backup.ts。

快照：自动+手动双保险

除了手动下载，项目还支持快照机制，由 backup-service.ts 实现：

• 自动快照：应用每次启动时自动执行，默认开启（autoBackup: true），默认保留最近5 份（backupRetentionCount，可配置 1–100），逻辑见 start-handler.ts
• 手动快照：在设置页一键创建，文件名形如hamh-manual-2.0.33-2026-03-11_08-34-12.zip（自动生成为hamh-auto-...）

切换版本之前，先手动打一份快照，再下载到本地保管，是最稳妥的做法。

跨 Alpha / Stable 迁移：4 步操作

以下以 Stable → Alpha 为例，反向操作同理：

第 1 步：下载全量备份（含身份）

在当前版本运行正常时，进入 Settings → Backup & Restore，点击Download Full Backup。⚠️ 注意：一定要选"含身份"的版本，否则恢复后所有设备都需要重新配对。

第 2 步：清空目标版本的数据目录

启动目标版本前，先清掉它的旧数据，确保它是"干净状态"启动。通过 SSH 执行：

# Stable → Alpha：清空 Alpha 数据 rm -rf /addon_configs/hamh-alpha/data

Docker 部署时，数据默认在~/.home-assistant-matter-hub（挂载到容器/data），直接整目录复制备份即可，参考 migration-from-t0bst4r.md。

第 3 步：上传并恢复

启动目标版本后，打开 WebUI，在 Backup & Restore 卡片点击Restore from Backup，选择刚下载的 ZIP 文件。恢复时可选择：

• 只恢复指定桥接（按桥接 ID 勾选）
• 覆盖已存在的桥接（默认不覆盖，避免误删）
• 是否恢复实体映射（includeMappings）
• 是否恢复身份数据（restoreIdentity，跨版本迁移务必保持开启）

第 4 步：重启应用

恢复完成后界面会提示需要重启。点击重启后，桥接会用恢复的身份重新上线，控制器端无需任何操作，设备名称、房间、fabrics 连接全部保留。

Home-Assistant-Matter-Hub 桥接列表页面，桥接状态为 Running，显示 161 台设备与 2 个 fabrics

恢复后如何验证没丢设备？

进入Devices页面核对设备数量是否与迁移前一致：

Home-Assistant-Matter-Hub 全部设备列表，展示恢复后的桥接设备与集群信息

核对要点：

1. 桥接卡片上 Running 状态正常，fabrics数量与迁移前一致
2. 设备总数与迁移前相同（桥接页显示 devices 数量）
3. 打开 Apple Home / Google Home 确认设备仍显示原来的房间和图标

如果恢复结果中出现errors列表，通常是目标目录权限问题或该桥接在备份中缺少身份文件，按提示的bridgeId单独排查即可。

常见问题 FAQ

Q：恢复后控制器显示"新设备"？说明身份数据没有恢复成功。请确认备份是"Full Backup (with Identity)"，且恢复选项里勾选了恢复身份，并在恢复后重启了应用。详见 faq.md。

Q：可以同时运行 Alpha 和 Stable 吗？可以。两者使用不同端口（如 8482 / 8483）、不同数据目录和不同的 Matter 端口即可并存，但注意桥接端口不要冲突，详见 alpha-features.md。

Q：备份文件能直接拷贝到另一台机器吗？可以。把 ZIP 在新实例的 Backup & Restore 页面上传恢复即可；只要恢复身份，配对关系原样带过去。

Q：自动快照会一直占空间吗？不会。保留数量由backupRetentionCount控制（默认 5 份），超出后自动删除最旧的快照。

关键源码与文档索引

一句话总结：切版本前先"Full Backup (with Identity)"，目标版本先清数据再恢复，重启后设备一个都不少。🎉